Overview

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:

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:

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:

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 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:

Catalog

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