---
title: Overview
description: Platform-adaptive mobile components you copy into your project.
---

Components are the individual controls that make up a touchcn app — a button, an
input, a tab bar. Each one renders Material 3 chrome on Android and iOS 26 liquid
glass on iOS from a single component set, with no platform conditionals in your
code.

## How components work

Components are not imported from a package — you copy their source into your
project with the CLI, the same shadcn-style workflow used throughout touchcn:

```bash
npx touchcn add button
```

This copies the component into `src/components/ui/<name>/` (React and Vue) or
`src/app/components/ui/<name>/` (Angular) and resolves any components it depends
on. From there the source is yours to edit.

Import a copied component through the `@/components/ui/<name>` alias:

```tsx
import { TcnButton } from '@/components/ui/button';
```

## Updating components

Because the source is copied into your project, updates don't arrive through `npm`. The CLI tracks
what it installed and can pull newer registry versions on demand — even into files you've edited:

```bash
npx touchcn diff            # which components have updates, and how your files compare
npx touchcn update          # apply updates; local edits are three-way merged
```

`update` overwrites files you never touched and merges the rest, writing conflict markers into any
file where your edits and the upstream change overlap. See the [CLI reference](/docs/cli#diff) for
statuses, merge behavior, and conflict resolution.

## Component naming

Overlays are named by their **physical presentation** — where the surface sits and what it holds —
rather than by borrowed ecosystem terms. A **Dialog** is a small panel floating over content
(confirm/prompt), a **BottomSheet** slides up from the bottom with free-form content, an
**ActionSheet** is a bottom-anchored list of actions, and a **Modal** is full-screen. The name
**Alert** is deliberately avoided — it means a confirm dialog in one ecosystem and an inline status
message in another, so it is ambiguous.

If you know a component by its name in another library, this is where it lands:

| Ionic                             | shadcn        | touchcn                                        |
| --------------------------------- | ------------- | ---------------------------------------------- |
| `ion-alert`                       | AlertDialog   | [Dialog](/docs/components/dialog)              |
| `ion-modal`                       | Dialog        | [Modal](/docs/components/modal)                |
| `ion-modal` (sheet breakpoints)   | Sheet         | [Bottom Sheet](/docs/components/bottom-sheet)  |
| `ion-action-sheet`                | —             | [Action Sheet](/docs/components/action-sheet)  |
| `ion-menu`                        | Sheet (side)  | [Drawer](/docs/components/drawer)              |
| `ion-popover`                     | Popover       | [Popover](/docs/components/popover)            |
| `ion-toast`                       | Toast         | [Toast](/docs/components/toast)                |

## Catalog

- [Action Sheet](/docs/components/action-sheet) — a bottom-anchored list of actions.
- [Avatar](/docs/components/avatar) — a user image with fallback.
- [Badge](/docs/components/badge) — a compact status label.
- [Banner](/docs/components/banner) — an inline persistent message.
- [Bottom Sheet](/docs/components/bottom-sheet) — a sheet that slides up from the bottom.
- [Button](/docs/components/button) — a platform-adaptive button.
- [Card](/docs/components/card) — an elevated content surface.
- [Checkbox](/docs/components/checkbox) — a multi-select control.
- [Chip](/docs/components/chip) — input, filter and assist chips.
- [Colorpicker](/docs/components/colorpicker) — an inline color swatch picker with an optional hex input.
- [Datepicker](/docs/components/datepicker) — a calendar date picker.
- [Dialog](/docs/components/dialog) — a centered confirm/prompt panel.
- [Divider](/docs/components/divider) — a hairline content separator.
- [Drawer](/docs/components/drawer) — a side navigation drawer.
- [FAB](/docs/components/fab) — a floating action button.
- [Infinite Scroll](/docs/components/infinite-scroll) — load more on scroll to end.
- [Input](/docs/components/input) — a text field with label.
- [Input OTP](/docs/components/input-otp) — a one-time-code entry field.
- [List](/docs/components/list) — grouped rows with slots.
- [Modal](/docs/components/modal) — a full-screen surface.
- [Navbar](/docs/components/navbar) — a fixed top bar with slots.
- [Page](/docs/components/page) — a scrollable screen container.
- [Popover](/docs/components/popover) — an anchored floating panel.
- [Progress](/docs/components/progress) — a determinate progress bar.
- [Pull to Refresh](/docs/components/pull-to-refresh) — pull down to refresh content.
- [Radio](/docs/components/radio) — a single-select control.
- [Searchbar](/docs/components/searchbar) — a search field with clear.
- [Segmented](/docs/components/segmented) — a single-choice segmented control.
- [Select](/docs/components/select) — a single-select field.
- [Skeleton](/docs/components/skeleton) — a loading placeholder.
- [Slider](/docs/components/slider) — a range value selector.
- [Spinner](/docs/components/spinner) — an indeterminate loading indicator.
- [Stepper](/docs/components/stepper) — a numeric plus/minus input.
- [Swipeout](/docs/components/swipeout) — swipe a row to reveal actions.
- [Switch](/docs/components/switch) — an on/off toggle.
- [Tabbar](/docs/components/tabbar) — bottom tab navigation.
- [Tabs](/docs/components/tabs) — content tabs with panels.
- [Toast](/docs/components/toast) — a transient message with action.