For a React web app that people use on phones and desktops, Wingo UI does the most for you: its selects, popovers, menus and dialogs open as draggable bottom sheets below 768px and its buttons grow to 44px on touch. For a mobile-only app or a Capacitor build with a native iOS or Material look, Ionic React is the stronger pick, with Framework7 and antd-mobile as alternatives. MUI, shadcn/ui, HeroUI and Mantine render fine on a 390px screen but leave most phone behavior, from sheets to safe areas, to you.

Picking the best React component library for mobile comes down to what each component does on a phone. This comparison is for React web apps: a Next.js app that people open in a phone browser, add to the home screen or ship inside Capacitor. React Native kits are out of scope. Four things decide the choice: what a select or menu opens on a 390px screen, how big the targets are under a thumb, whether fixed bars clear the notch and the home indicator, and which gestures work. We checked nine libraries on those four points on October 9, 2026.

We build Wingo UI, one of the nine, so read this as a vendor's comparison with sources, including the cases where another library is the better pick. If you arrived from a general "best React UI library 2026" list, this one is narrower: it only scores what happens on a phone. Broader head to head posts live under Comparisons and alternatives, and our guide to shadcn alternatives covers prices, licenses and MCP support.

What is the best React component library for mobile?

Wingo UI when the same app has to work on phones and desktops, and Ionic React when the app is mobile-only and should look native. The rest of the field fits narrower cases.

• Phones and desktops from one codebase, Tailwind CSS, source in your repository: Wingo UI. Its overlays switch to bottom sheets below 768px and its controls grow on touch, so the phone behavior ships inside each component.
• A mobile-only app or a Capacitor build with a native look: Ionic React. It covers every phone pattern in this comparison and picks iOS or Material styling by platform.
• The same idea outside Ionic's ecosystem: Framework7 React, which brings its own app shell and router.
• A mobile-only app in the Ant Design family: antd-mobile.
• Tailwind classes with an iOS or Material look, inside an Ionic or Framework7 shell: Konsta UI.
• A desktop-first product that must also work on phones: MUI gives the most phone help among the general-purpose packages. shadcn/ui, HeroUI and Mantine work too, with more wiring on your side.

How did we test the libraries at 390px?

We opened each library's own docs demos in Chromium through Playwright at 390 by 844 pixels with touch emulation on, so (pointer: coarse) matched as it does on a phone. On each site we measured the default button and tapped the first Select demo to see what opens and how tall its rows are. Ionic's and Framework7's docs blocked our headless browser, so for those two and for Konsta UI the numbers come from their source code and docs on GitHub. Versions are the latest on npm on October 9, 2026.

Two limits apply. Docs demos use each site's own theme, which matters for shadcn/ui, whose button size depends on the style you pick. And emulation is not an iPhone: it has no home indicator, no on-screen keyboard and no collapsing toolbar, so we checked safe areas in each library's source instead of on screen. Our mobile-first React components guide lists what only a real phone shows.

How do the libraries compare on a phone?

The mobile-only libraries (Ionic, Framework7, antd-mobile) cover every phone pattern, the general-purpose ones leave most of them to you, and Wingo UI ships the phone patterns inside components that also work on a desktop. The table is dated October 2026. "Select at 390px" is what opened when we tapped a select, or what the source does by default.

The mobile-only libraries keep behaving like a phone app on a wide screen: Ionic's select still opens an alert dialog, and its modal becomes a 600 by 500 pixel card once the window is 768px wide and 600px tall. The general-purpose libraries look right on a desktop and leave most phone behavior to you. Wingo UI aims at the middle: one component that is a sheet on a phone and a popover or dialog on a desktop.

Which libraries open selects and menus as bottom sheets?

Among the general-purpose libraries, only Wingo UI opens a select as a bottom sheet by default. The mobile-only libraries get there by option or by design: Ionic's select takes interface="action-sheet" or interface="modal", Framework7's Smart Select takes openIn: "sheet", and antd-mobile's Picker always opens in a bottom popup. shadcn/ui, Mantine and HeroUI opened a floating list anchored under the field, with rows of 28, 34 and 36 pixels. MUI also opened a floating menu, but it was the one general-purpose package with finger-sized rows: its menu items grow to 48px below its sm breakpoint of 600px. Konsta UI uses a native select, which opens the phone's own picker and is a fine answer for short lists.

A floating list puts small rows next to the thumb that opened it. A sheet gives full-width rows at the bottom of the screen, where the thumb already is, and leaves room for a search row. In Wingo UI the Select does this through its responsive prop, which defaults to true, so the call site has no media query:

"use client";

import { useState } from "react";
import { Select, type SelectOption } from "@/components/ui/select";

const STATES: SelectOption[] = [
  { value: "CA", label: "California", keywords: ["Los Angeles"] },
  { value: "NY", label: "New York", keywords: ["New York City"] },
  { value: "TX", label: "Texas", keywords: ["Austin"] },
];

export function ShippingState() {
  const [state, setState] = useState("");
  return (
    <Select
      label="State"
      placeholder="Choose the state"
      options={STATES}
      value={state}
      onValueChange={setState}
      name="state"
      autoComplete="address-level1"
    />
  );
}

Below 768px the field opens a sheet titled with its label, with 48px rows and the chosen row scrolled into view. With more than 8 options a search row sits under the title, and on a touch screen it waits for a tap instead of raising the keyboard over the list. Pass responsive={false} to keep the floating list on phones. The Popover, Dropdown Menu, Dialog and date pickers follow the same rule, and all but the date pickers are free.

Live demo: Select. The original article embeds an interactive demo here (On a phone, tap the State field: a sheet slides up with large rows and a search box; on a wide screen the same field opens a list under it). Try it live on wingo-ui.com or open the Select docs. Install: npx wingo-ui@latest add select

How big are the touch targets out of the box?

Most libraries ship a 32 to 40 pixel default button and keep that size on every device. WCAG 2.2 asks for 24 by 24 pixels at level AA and 44 by 44 at level AAA, and Apple's guidelines use 44 points. Every default button here clears AA; few reach 44 without help.

Wingo UI is the only library here whose buttons change size by pointer type rather than by screen width or platform, so a touch laptop gets 44px buttons and a narrow desktop window keeps 40px. The rule is one Tailwind variant in the size map of the Button:

// components/ui/button.tsx (excerpt)
md: "h-10 gap-2 px-4 text-sm pointer-coarse:h-11",

The small size keeps its 32px look and gets a 44px hit area through a pseudo-element instead. Our touch target guide explains when pointer: coarse beats any-pointer: coarse and how to test it.

Which libraries handle safe areas for you?

The mobile-only libraries do, and most general-purpose ones do not. Ionic pads its toolbars, tab bar and modals with --ion-safe-area-* variables you can override, and Framework7 does the same with --f7-safe-area-*. Konsta UI ships pb-safe style utilities that its toolbars use. antd-mobile has a SafeArea component, but its tab bar's safeArea prop is off by default. We searched the published @mui/material 9.4.0 and @heroui/styles 3.2.6 packages and shadcn/ui's base components and styles for safe-area-inset and found nothing; Mantine uses the insets only in its AppShell, whose footer pads the bottom inset.

All of these read env(safe-area-inset-*), which stays at 0 until the page opts in with viewport-fit=cover. In the Next.js App Router that is one export from the root layout:

import type { Viewport } from "next";

export const viewport: Viewport = { viewportFit: "cover" };

In Wingo UI, 38 component files read the insets. The Bottom Tab Bar pads the home indicator, keeps at least 12px under its floating variant, and publishes its height so a floating button or a sticky buy bar can sit above it. Here it is with Pull To Refresh on the page behind it, as a client component your root layout can wrap around children:

"use client";

import type { ReactNode } from "react";
import Link from "next/link";
import { usePathname, useRouter } from "next/navigation";
import { House, Inbox, Plus, UserRound, Users } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";
import { PullToRefresh } from "@/components/ui/pull-to-refresh";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Clients", href: "/clients", icon: <Users /> },
  { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: 4 },
  { label: "Profile", href: "/profile", icon: <UserRound /> },
];

export function PhoneShell({ children }: { children: ReactNode }) {
  const router = useRouter();
  const pathname = usePathname();
  return (
    <>
      <PullToRefresh onRefresh={() => router.refresh()} variant="ios">
        <div className="pb-(--bottom-bar-offset)">{children}</div>
      </PullToRefresh>
      <BottomTabBar
        className="md:hidden"
        items={tabs}
        currentPath={pathname}
        linkComponent={Link}
        action={{ label: "New client", icon: <Plus />, href: "/clients/new" }}
        hideOnScroll
      />
    </>
  );
}

The tab bar is fixed to the viewport by default and writes its height, safe area included, to --bottom-bar-offset on the root element, which the pb-(--bottom-bar-offset) wrapper reads so the last row of the page stays above the bar. linkComponent and currentPath hand it the Next.js router, so tabs navigate without a full page load and the active pill follows the route. hideOnScroll slides the bar away while you scroll down and brings it back on the way up, with transforms only. The pull calls router.refresh() to refetch the page's server data and spins for at least 500ms (or until a promise you return settles), and a trackpad scroll past the top pulls too, so the gesture has a desktop path. The safe area guide covers stacking a buy bar or a floating button above the tab bar.

Live demo: Bottom Tab Bar. The original article embeds an interactive demo here (Tap the tabs: the pill glides to the active one; scroll the page and the bar slides away, then comes back when you scroll up). Try it live on wingo-ui.com or open the Bottom Tab Bar docs. Install: npx wingo-ui@latest add bottom-tab-bar

Which libraries ship mobile gestures?

Wingo UI, Ionic, Framework7 and antd-mobile ship all four common phone gestures. The general-purpose libraries ship a swipeable drawer at most, and Konsta UI none.

In Wingo UI the Drawer is free; Pull To Refresh, the swipe rows of the List and the Picker Wheel are Pro.

For sheets, Ionic's API and ours read almost the same. Ionic needs a 0 breakpoint before a swipe can dismiss the sheet:

// Ionic React: stops at half and full height, swipe down to close
// import { IonContent, IonModal } from "@ionic/react";
<IonModal trigger="open-filters" initialBreakpoint={0.5} breakpoints={[0, 0.5, 1]}>
  <IonContent className="ion-padding">Price, condition and categories</IonContent>
</IonModal>

// Wingo UI: the same stops; drag down from the first one to close
// import { Button } from "@/components/ui/button";
// import { Drawer } from "@/components/ui/drawer";
<Drawer trigger={<Button>Filters</Button>} title="Filters" snapPoints={[0.5, 1]}>
  <p className="text-sm text-muted-foreground">Price, condition and categories</p>
</Drawer>

The difference is what happens at 768px and up: the Drawer stays a capped sheet, or becomes a side panel or a centered dialog through its desktop prop, while Ionic's sheet modal stays a sheet at the bottom of the screen. Our bottom sheet guide covers snap points, nesting and the keyboard in detail.

The wheel picker is the gesture most web libraries skip. The Picker Wheel spins with native momentum, ticks as rows pass the center on phones that can vibrate, and works from a keyboard with arrows, Page Up and Down and type to jump. As a field it opens the wheels in a bottom sheet with Done and Cancel on phones and in a popover on a desktop:

"use client";

import { PickerWheelField, pickerRange } from "@/components/ui/picker-wheel";

export function AppointmentTime() {
  return (
    <PickerWheelField
      label="Appointment time"
      name="time"
      defaultValue={["10", "30"]}
      columns={[
        { id: "hour", label: "h", options: pickerRange(8, 19, { pad: 2 }) },
        { id: "minute", label: "min", options: pickerRange(0, 55, { step: 5, pad: 2 }) },
      ]}
    />
  );
}

Live demo: Picker Wheel. The original article embeds an interactive demo here (Flick a column: it spins with momentum and clicks into place on a row; with a mouse, drag it or scroll it, or Tab to it and use the arrow keys). Try it live on wingo-ui.com or open the Picker Wheel docs. Install: npx wingo-ui@latest add picker-wheel

When are Ionic React or Framework7 the better choice?

Pick Ionic React when the app is phone-first, you want it to look native on iOS and Android, and you may ship it to the app stores with Capacitor. Its sheet modal, refresher, sliding items, picker and tab bar are mature, and the modes switch by platform with no work from you. The costs are real: its core.css is required, its guide for existing React apps warns that its CSS reset may conflict with your global styles, its router package needs React Router 6, and its components look like a phone app on a desktop. Framework7 React makes a similar trade with its own App, View and routes, and has Vue and Svelte versions too.

Wingo UI is the better fit when the same screens have to work as a desktop product, you style with Tailwind CSS, and you want the source in your repository. It is younger with a much smaller community, it is React only, and it has one design with iOS-style options on some parts instead of a platform mode.

When should you stay on MUI, shadcn/ui, HeroUI or Mantine?

Stay when most of your users are on desktops and phones are a secondary target. MUI is the strongest of the four on phones: 48px menu rows on small screens, a SwipeableDrawer and a responsive DatePicker from MUI X that opens in a modal on touch devices. shadcn/ui has a large registry ecosystem and a Drawer with snap points, and you write the responsive dialog recipe once per overlay. If you go this way, budget for three wrappers: overlay to sheet, touch target sizing and safe-area padding on anything fixed. That checklist is what a mobile first React component library saves you, whichever one you choose.

Where should you start?

Start with the overlay your users open most on a phone, because a floating list under a thumb is the most visible mobile failure. Install the free Select with npx wingo-ui@latest add select (no account needed), put it in one form, and open that form on your own phone. The Drawer, Popover, Dialog and Dropdown Menu are free as well. The tab bar, pull to refresh, picker wheel and the other React mobile UI components in the Mobile category are part of Wingo UI Pro, at $8 a month, $80 a year or $150 once. Whichever React mobile UI library you pick, test it at 390px with touch on before you commit.

Components in this post

• Select (Free): A custom select with search, groups, icons, thousands of virtualized rows and a hidden native select for forms. Install: npx wingo-ui@latest add select
• Drawer (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: npx wingo-ui@latest add drawer
• Bottom Tab Bar (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: npx wingo-ui@latest add bottom-tab-bar
• Picker Wheel (Pro): The iOS wheel picker for the web: columns that spin with native momentum and click into place on a 3D cylinder, inline or as a field. Install: npx wingo-ui@latest add picker-wheel
• Pull To Refresh (Pro): Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick. Install: npx wingo-ui@latest add pull-to-refresh

FAQ

Which React UI library is best for mobile web apps?

For an app that runs on phones and desktops, pick a library whose components change behavior on a phone, such as Wingo UI, where overlays become bottom sheets below 768px. For a mobile-only app with a native look, pick Ionic React, which ships sheet modals, pull to refresh, sliding list items, pickers and a tab bar that pads the safe area.

Does shadcn/ui work on mobile?

It renders well on phones and its Drawer is a real bottom sheet with swipe and snap points. As of October 2026 its Select, Popover and Dropdown Menu stay floating panels at every width, its default button stays 32px on touch screens, and none of its components pad the safe area, so you add those yourself.

Is MUI good for mobile?

Better than most general-purpose libraries: its menu rows grow to 48px below 600px, SwipeableDrawer adds swipe gestures and the MUI X date pickers open in a modal on touch devices. Dialogs need a useMediaQuery recipe to go full screen, its drawer has no snap points, and safe areas are up to you.

Is Ionic React still a good choice in 2026?

Yes, for mobile-only apps and Capacitor builds. Version 9.0.7 shipped on October 7, 2026 under the MIT license, with iOS and Material modes picked by platform. It brings its own CSS and router integration, so it fits less naturally into a Tailwind CSS app that also has to look like a desktop product.

Are these libraries for React Native?

No. Everything here is for React DOM: web apps, PWAs and web views such as Capacitor. A React Native app needs a React Native component library, since these render HTML elements.

Can I try Wingo UI on a phone for free?

Yes. The Drawer, Select, Popover, Dialog, Dropdown Menu and Button are free, and they already switch to bottom sheets and 44px targets on phones. The Bottom Tab Bar, Pull To Refresh, Picker Wheel and the other components of the Mobile category are part of Wingo UI Pro.

This article was originally published on the Wingo UI blog: Best React Component Library for Mobile in 2026: 9 Compared. The original has the live, interactive demos and is kept up to date.

A component library MCP server gives coding agents tools to search the catalog, read real props and design rules, and check installed versions, so they stop guessing APIs from training data. It works best with three companions: a short rules file that tells the agent when to call those tools, llms.txt and Markdown docs for agents without MCP, and a registry plus CLI that writes the real files and records their versions.

Ask Claude Code for a settings page and it will write one in a minute. It may also invent a <Button intent="primary"> your library never had, hardcode #3b82f6 where a token belongs and rebuild a date picker you already own. A component library MCP server fixes that at the source: it gives the agent tools to look up what exists, read the real props and install the real files. This guide covers how a React component library exposes itself to Claude Code, Cursor and Codex, the four pieces that make it work (an MCP server, a rules file, llms.txt and a registry), and the setup our CLI writes for you.

We build Wingo UI, so the examples use our server, CLI and registry, with output copied from release 1.7.0. The approach applies to any library, an internal design system included, and where another tool fits better, we say so. Shorter guides on agents and UI live under Building UI with AI agents: AGENTS.md vs CLAUDE.md vs Cursor rules for the rules file, a Claude Code shadcn setup for the shadcn MCP server next to a second registry, and a React AI chat UI guide for when the screen you are building is the chat itself.

What is a component library MCP server?

A component library MCP server is a Model Context Protocol server that turns a UI library into tools an agent can call: search the catalog, read one component's props and usage, fetch the design rules, and compare installed versions with the latest release. The agent asks instead of remembering.

The client (Claude Code, Cursor, Codex, Gemini CLI) lists a server's tools and lets the model decide when to call them. A server runs as a local process over stdio or as a remote endpoint over Streamable HTTP. Remote servers are easier to keep current, because every client sees a new release the moment you deploy it.

The React component library MCP servers we checked come in three shapes. Here is how they compare, as of October 2026:

Sources, checked in October 2026: the shadcn MCP docs, the Material UI MCP guide, the React Suite MCP guide and our MCP server docs.

The first shape is a docs lookup. MUI and React Suite ship npm packages, so the agent needs correct props and working links; it never needs source files. If your app runs on Material UI, MUI's own server is the right choice.

The second shape is a registry installer. The shadcn docs describe listing, searching and installing from any shadcn-compatible registry in components.json; they do not mention design rules or update checks. If you pull from several registries, one shadcn server covers them all, which is a real advantage.

The third shape is what a source-copy library needs: docs, install and maintenance in one server. When components live in your repository as code you can edit, the agent has to know what the library offers, which version your project has and how the library expects to be used. That last part is the one a props table alone does not carry.

Why do coding agents invent components?

Because the model writes from training data, and training data predates your library version and leans toward the most common APIs. Without a way to check, the agent fills every gap with the likeliest guess: shadcn's API on a library that is not shadcn, a prop that was renamed two majors ago, a hex color where a semantic token belongs.

The monday.com engineering team described the same failure in How We Use AI to Turn Figma Designs into Production Code (Rivka Ungar, February 2, 2026). Their first attempt, a Figma link pasted into Cursor with the Figma MCP, produced code that hardcoded colors and skipped their design system components. Their diagnosis: "the model had no understanding of what the design system actually was." They then built an MCP server for the design system and found it was still not enough on its own: "the MCP only provided knowledge; it didn't decide how or when that knowledge should be applied across a full UI."

A server full of correct facts does nothing if the agent never calls it, calls it after writing the code, or reads the props and then restyles everything with utility classes. So the server is one of four pieces.

What does an agent need besides the MCP server?

It needs a rules file that says when to call which tool, docs it can read without MCP, and a registry plus CLI that writes the files. Each piece answers a different question and changes at a different speed:

The split that matters: the rules file stays short and stable, and everything that changes lives behind the server. Prop tables pasted into a rules file go stale with the next release, and an agent tends to trust the copy already in its context over a tool it would have to call. Our rules file names tools and commands. It never lists a component's props.

Which tools should a component library MCP server expose?

A few read-only tools, shaped around what an agent does when it builds UI: find, read, follow the rules, install, stay current. Ours has ten:

• search_components: find components, blocks, hooks and helpers by keywords.
• list_categories: browse the categories with item counts.
• get_component: props, parts, usage, dependencies, the install command and the source.
• get_block: a full screen or section and the components it composes.
• get_design_rules: tokens, sizes, motion, forms, overlays and mobile rules.
• get_theme_tokens: the CSS variables for light and dark mode.
• get_install_instructions: project setup for Next.js or Vite.
• check_updates: compare installed items with the latest release.
• get_changelog: recent releases and their notes.
• get_account_status: whether the key has Pro, with the links to upgrade.

There is also one prompt, build_screen, that walks the agent through search, rules, install and composition. Every tool is marked read-only and idempotent in its annotations, and none of them writes to your disk. Writing files is the CLI's job.

Search should return slugs and one line each

A search result is a short list the agent can scan in one glance. This is the real answer from our server to search_components with the query "orders table with filters" and limit: 5, trimmed to the first three hits:

5 results for "orders table with filters":

- **Data Table** `data-table` (component, pro, v1.1.0): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones.
- **Audit Log** `audit-log` (component, pro, v1.0.0): Who did what, when and to which record: a filterable activity log with day groups, before / after diffs and a CSV export.
- **Rule Builder** `rule-builder` (component, pro, v1.0.0): An if-this-then-that editor for automations: a trigger, conditions and ordered actions as sentence cards, read back as one sentence.

Next: get_component (or get_block for blocks) with a slug for props, usage and the install command.

Every hit carries its slug, kind, access tier and version, and the last line names the next tool, so the agent never has to guess which call turns a slug into props. The third hit is a weak match. That is fine: one line of description lets the agent skip it without spending a get_component call to find out.

Props need their defaults

get_component returns the props table the docs page shows, with types and defaults, plus parts, a usage example, the npm and registry dependencies, and the install command. Defaults are what keep generated code short. An agent that knows the Button defaults to type="button", tone="neutral" and size="md" writes <Button>Cancel</Button> instead of spelling out props it guessed. One that knows loading keeps the width and sets aria-busy does not wrap the button in its own spinner logic.

Below is that Button with the brand tone and a loading label set through props.

Live demo: Button. The original article embeds an interactive demo here (Click Pay now: the spinner takes the label's place, the width holds and the button ignores clicks until it settles). Try it live on wingo-ui.com or open the Button docs. Install: npx wingo-ui@latest add button

Without JavaScript, the demo is one solid "Pay now" button in the brand color; pressing it shows a spinner and "Paying" in the same width.

Keep tool output small

Large answers run into hard limits in the clients. As of October 2026, Claude Code's MCP docs say it warns when a tool result passes 10,000 tokens, caps results at 25,000 tokens by default (MAX_MCP_OUTPUT_TOKENS raises it) and saves text results over 50,000 characters to a file instead of putting them in context.

Our Data Table is one file of 3,940 lines, about 150 KB of TypeScript. Its docs without source come back as about 18,000 characters, roughly 4,500 tokens. With the source attached (a Pro key), the same call grows past 160,000 characters and passes every one of those limits. So the rule for agents, and for anyone designing one of these servers, is: docs through MCP, files through the CLI. Call get_component with includeSource: false for large items and let npx wingo-ui@latest add write the code.

The same goes for rules. get_design_rules with the topic all returns about 45,000 characters, roughly 11,000 tokens at the usual four characters per token, which is already past Claude Code's warning line. The mobile topic alone is about 1,900 characters and forms about 4,200. Ask for the topic the task needs.

Errors should say what to do next

A tool error is a prompt the agent reads, so write it like one. An unknown slug answers with the closest matches and points back to search_components. A Pro item requested without a Pro key answers with the docs and this, word for word from our server (links trimmed, lines wrapped):

Login Page is part of Wingo UI Pro; the source is not included for this caller
(no API key; a free account at https://wingo-ui.com/sign-in unlocks the free items).
Do not re-create it from the docs.
Tell the user it needs Pro (https://wingo-ui.com/pricing); with a Pro key
(Authorization: Bearer wui_...) this tool returns the files and
`npx wingo-ui@latest add login-page` works after `npx wingo-ui@latest login`.
Free alternatives to look at: otp-input.

"Do not re-create it from the docs" is the most important sentence on the server. An agent that has just read a complete props table and a long interaction description has everything it needs to attempt a rewrite, and the result is a half copy that matches the docs on paper and nothing else: no version record, no updates, none of the edge cases the description summarizes in one line.

Server instructions are the first thing the agent reads

Claude Code turns on tool search by default, so only tool names and each server's instructions load at the start of a session; full tool definitions load when the model looks for them. The same docs say Claude Code cuts each tool description and each server's instructions at 2,048 characters by default. The instructions are your server's pitch to the model: what tasks it handles, when to search for its tools, and the rules that must survive truncation. Put "search before you write UI" in the first lines.

We learned the cost of that limit on our own server. Its instructions run 2,235 characters in release 1.7.0, so Claude Code drops the last sentence, the one that says never to re-create a component without the right key. The rule still reaches the agent because every refusal and the rules file repeat it. Count your characters, and repeat any rule that matters somewhere the model cannot miss.

How do I connect Claude Code, Cursor and Codex?

One CLI command writes both the MCP config and the rules for your agent. With WINGO_UI_API_KEY set it writes the HTTP configs below, which read the key from the environment so it never lands in your repository; without the variable it writes the local stdio proxy. You can also add the server by hand.

npx wingo-ui@latest login                     # once per computer
npx wingo-ui@latest agents install claude     # or codex, gemini, grok, cursor, all

Running it again changes nothing, and it keeps the other servers in your MCP configs. Where each agent's files go:

Access works in three tiers. Without a key, search, docs, props, design rules and tokens all answer, with no source. A key from a free account (email only, no card) adds the source of the 75 free items. A Pro key adds the source of all 326. Create the key in your account and export it in your shell profile as WINGO_UI_API_KEY.

Claude Code

Claude Code stores MCP servers in three scopes: local (the default, private to you in ~/.claude.json), project (.mcp.json at the repository root, committed for the whole team) and user (all your projects). For a library the team shares, use project scope; .mcp.json expands ${VAR} from the environment, so the file is safe to commit:

{
  "mcpServers": {
    "wingo-ui": {
      "type": "http",
      "url": "https://wingo-ui.com/mcp",
      "headers": {
        "Authorization": "Bearer ${WINGO_UI_API_KEY}"
      }
    }
  }
}

For a quick personal setup, the one-liner adds it in local scope:

claude mcp add --transport http wingo-ui https://wingo-ui.com/mcp --header "Authorization: Bearer $WINGO_UI_API_KEY"

Run /mcp inside a session to see whether the server connected. If you already run other Claude Code MCP servers, this one sits next to them in the same file, and agents install keeps the entries it did not write. Our Claude Code shadcn tutorial walks through the shadcn MCP server, its skill and a second registry in the same project.

Cursor

Cursor reads .cursor/mcp.json in the project and ~/.cursor/mcp.json for every project. It uses its own variable syntax, ${env:NAME}, documented in Cursor's MCP docs:

{
  "mcpServers": {
    "wingo-ui": {
      "url": "https://wingo-ui.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WINGO_UI_API_KEY}"
      }
    }
  }
}

Codex

Codex reads MCP servers from ~/.codex/config.toml (or a trusted project's .codex/config.toml). For a remote server, bearer_token_env_var names the variable that holds the token, as the Codex MCP docs describe. Restart Codex after adding it so it picks up the server.

[mcp_servers.wingo-ui]
url = "https://wingo-ui.com/mcp"
bearer_token_env_var = "WINGO_UI_API_KEY"

Any other client

Clients that cannot send a header to a remote server can run the local proxy. It reads the key saved by wingo-ui login and mirrors the remote tools, so new tools appear without updating anything:

{
  "mcpServers": {
    "wingo-ui": { "command": "npx", "args": ["-y", "wingo-ui@latest", "mcp"] }
  }
}

What goes in the rules file?

When to call which tool, how to install, and what never to do, in as few lines as you can manage. This is the whole block we put in AGENTS.md, CLAUDE.md or GEMINI.md:

<!-- wingo-ui:start v=2 -->
## Wingo UI

This project builds its UI with Wingo UI (React 19 + Tailwind CSS v4 components installed as source, see `wingo-ui.json`).

- Before writing UI, use the `wingo-ui` MCP tools: `search_components` to find what exists (blocks for whole screens), `get_component` / `get_block` for props and usage, `get_design_rules` for tokens, sizes, motion and mobile rules. Never recreate a component the library has.
- Install with `npx wingo-ui@latest add <slug...>`. At the start of UI work run `check_updates` (or `npx wingo-ui@latest outdated`) and mention updates; update with `npx wingo-ui@latest update`.
- Semantic tokens only (`bg-background`, `bg-surface`, `text-muted-foreground`, `border-border`), configure components through props, keep `cn()`, `data-slot` and license headers in copied files. Check 390px and 1440px, light and dark.
- No MCP tools available? The CLI has `search`, `info`, `add`, `outdated`, `update`; the docs for models are at https://wingo-ui.com/llms.txt.
<!-- wingo-ui:end -->

A few choices in there are deliberate. Every bullet tells the agent what to do or when to do it. It names tools and commands but lists no component's props, because props change and tool names do not. It has a fallback for sessions without the MCP server, so the agent degrades to the CLI instead of guessing. And it carries a version marker: npx wingo-ui@latest agents status tells you whether your copy is current, and agents update rewrites only the text between the markers.

Claude Code also gets a skill with the longer workflow, and Cursor gets a project rule scoped to .tsx, .jsx and .css files. The full setup is on the coding agents docs page.

For an internal library, copy the structure: one line on what the library is, one on which tools to call before writing UI, one on how to install, one on styling, one fallback. Five lines that an agent follows beat fifty that it skims. Which of these files each agent reads, and how one AGENTS.md can serve Claude Code, Codex and Cursor at once, is in our AGENTS.md vs CLAUDE.md comparison.

Where do llms.txt and Markdown docs fit?

They serve assistants that can read a URL but have no MCP connection, and they back up the server when it is not configured. The llms.txt proposal, published by Jeremy Howard in September 2024, puts a Markdown file at the site root: an H1 with the name, a short summary, then sections of links. It also recommends a clean Markdown version of each page at the same URL with .md added, and its current version (updated August 2026) describes a rel="alternate" link of type text/markdown that points to it.

Our version follows that layout:

• /llms.txt is the map: what the library is, the counts, pricing, the docs pages, the install commands, a link per category and one line per item with its Markdown link.
• /llms/<category>.txt holds the item docs for one category, for example every table or every overlay.
• Every docs page has a Markdown twin, like /components/button.md, linked from the HTML head.
• /llms-full.txt has everything in one file, about 3.3 MB as of October 2026 (the docs of release 1.7.0 plus the blog posts).

That last file is the trap. A model handed 3.3 MB of docs either truncates it or spends its context on components it will never use. Treat llms.txt as a map and point the agent at the one category file or .md page the task needs. For a chat assistant that can fetch URLs, "read https://wingo-ui.com/components/data-table.md, then write an orders table with it" puts the real props in front of the model with one fetch.

What llms.txt cannot do is act. It cannot tell the agent which version your project has, whether your key covers an item, or write files with their dependencies. That is why it is the fallback in our rules and the MCP server is the default.

Why install through a registry instead of pasting code?

Because the registry and CLI write the exact files with their dependencies and record what they installed, and that record is the only way later releases can reach code you have edited. An agent that copies source out of a tool result skips all three steps.

Take the Login Page block. npx wingo-ui@latest add login-page writes three files into components/blocks, then pulls in the 16 registry items the block depends on (Alert, Avatar, Button, Checkbox, Input, OTP Input, Password Input, Separator, Toast and seven hooks and helpers), plus whatever those depend on, and installs its npm packages: motion, lucide-react, react-hook-form and zod. It records each item's version and content hash in wingo-ui.json and keeps a pristine copy under .wingo-ui/base/. When a release changes the block, npx wingo-ui@latest update runs a three-way merge between that pristine copy, your edited file and the new version, the way git merges branches.

An agent pasting code from get_block can miss a dependency, records nothing, and leaves you with files no tool can update. That is why every answer carries the install command and the rules say "install with the CLI" before anything about styling.

The registry also speaks the shadcn format. Free items install straight from their URL, for example npx shadcn@latest add https://wingo-ui.com/r/button.json, and Pro items install by name once the @wingo-ui registry with your key is in components.json, which also lets the shadcn MCP server install them. The trade-off is on our installation page: the shadcn CLI does not record versions, so wingo-ui update cannot merge later changes into files installed that way.

What does a full agent session look like?

Take a Next.js app that already has a wingo-ui.json and a plain prompt: "Build a sign-in page with two-step codes and an orders page with filters, using Wingo UI." With the server connected and the rules in place, the rules and server instructions lay out this path, and the prompt never names a tool:

1. check_updates with the items from wingo-ui.json, and a one-line report of what changed upstream.
2. search_components with "sign in page" and the kind block. On our server the first hit is login-page.
3. get_block for login-page: the props, the components it composes and the install command.
4. search_components with "orders table with filters", then get_component for data-table with includeSource: false.
5. get_design_rules for the forms and mobile topics.
6. One install for everything: npx wingo-ui@latest add login-page data-table (Button, Input and the rest come along as dependencies).
7. Two pages built from the installed components, configured through their props.

Step 2 is the one a setup without the server skips. With nothing to search, an agent writes a sign-in form from scratch: two fields, a button, perhaps a "forgot password" link that leads nowhere. The block the search returns covers password, email link or code sign-in, Google, Apple and Microsoft buttons, two-step codes that lock for a minute after three wrong tries, and the whole password recovery flow. The page code is short because the block does the work:

// app/(auth)/login/page.tsx
"use client";

import { useRouter } from "next/navigation";
import { LoginPage } from "@/components/blocks/login-page";

// a non-2xx answer becomes the message the block shows above the form
async function post(url: string, body: unknown, error: string) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!response.ok) throw new Error(error);
}

export default function Page() {
  const router = useRouter();
  return (
    <LoginPage
      methods={["password"]}
      showProviders={false}
      twoFactor
      onSignIn={(values) => post("/api/login", values, "The email or the password is not correct")}
      onVerifyCode={(code, { backup }) => post("/api/login/verify", { code, backup }, "That code is not correct")}
      onForgot={(email) => post("/api/password/forgot", { email }, "We could not send the email. Try again.")}
      onSuccess={() => router.push("/orders")}
    />
  );
}

A rejected promise from onSignIn shows its message in an alert above the form, and twoFactor sends a correct password to the code step. Three wrong codes lock the input for a minute whatever your handler does.

The pitfall is in the handlers the code leaves out. The block ships simulated ones so its demo works, and every on* prop you skip keeps its simulation. Without onVerifyCode, the two-step view accepts 123456. Without showProviders={false} or your own onProvider, the Google, Apple and Microsoft buttons spin for 1.2 seconds and then call onSuccess. An agent that wires onSignIn and stops ships a login page where a click on Google goes straight to /orders without signing anyone in. The get_block props table documents every one of these defaults, so the fix is the same as everywhere else: read the props, then wire each handler or turn the feature off.

The demo below runs on those simulated handlers, with the default methods and providers.

Live demo: Login Page. The original article embeds an interactive demo here (Sign in with any email and a password shorter than 8 characters to see the error alert, then choose "Email me a sign-in link" and send it to see the resend countdown). Try it live on wingo-ui.com or open the Login Page docs. Install: npx wingo-ui@latest add login-page

Without JavaScript, the demo shows the sign-in form: email and password fields, a "Remember me for 30 days" checkbox, the sign-in button, the emailed link option and buttons for Google, Apple and Microsoft.

The orders page follows the same pattern. The Data Table props the agent read decide most of the code: typed columns from createColumns, a badge column with a tone per status, a currency column with a footer sum, filters per column and quick filter chips.

// app/orders/orders-table.tsx
"use client";

import { useRouter } from "next/navigation";
import { Eye, Plus } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

export type Order = {
  id: string;
  customer: string;
  city: string;
  status: "Paid" | "Pending" | "Refunded";
  total: number;
  placedAt: string;
};

const col = createColumns<Order>();
const columns = col([
  col.accessor("customer", { header: "Customer", filter: "text", mobile: "title" }),
  col.accessor("id", { header: "Order", mobile: "subtitle" }),
  col.accessor("city", { header: "City", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Pending: { tone: "warning" }, Refunded: { tone: "neutral" } },
    filter: "multi-select",
  }),
  col.accessor("total", { header: "Total", type: "currency", footer: "sum", filter: "number-range" }),
  col.accessor("placedAt", { header: "Placed", type: "date", filter: "date-range" }),
]);

export function OrdersTable({ orders }: { orders: Order[] }) {
  const router = useRouter();
  return (
    <DataTable
      data={orders}
      columns={columns}
      getRowId={(order) => order.id}
      caption="Orders"
      locale="en-US"
      searchPlaceholder="Search orders"
      quickFilters={[{ id: "pending", label: "Pending", columnFilter: { id: "status", value: ["Pending"] } }]}
      toolbarActions={[{ label: "New order", icon: <Plus />, primary: true, onSelect: () => router.push("/orders/new") }]}
      rowActions={(order) => [{ label: "View", icon: <Eye />, onSelect: () => router.push(`/orders/${order.id}`) }]}
      persistKey="orders"
    />
  );
}

The page itself stays a server component that loads the rows and passes them down:

// app/orders/page.tsx
import { OrdersTable, type Order } from "./orders-table";

async function getOrders(): Promise<Order[]> {
  // your database query goes here
  return [{ id: "ORD-1042", customer: "Emma Carter", city: "New York", status: "Paid", total: 129, placedAt: "2026-10-02" }];
}

export default async function Page() {
  const orders = await getOrders();
  return (
    <main className="mx-auto flex max-w-6xl flex-col gap-4 p-4 sm:p-8">
      <h1 className="text-xl font-semibold text-foreground">Orders</h1>
      <OrdersTable orders={orders} />
    </main>
  );
}

The split is deliberate. getRowId, rowActions and onSelect are functions (so is any custom cell renderer in the columns), and the App Router cannot pass functions from a server component to a client one. An agent that renders <DataTable> with inline callbacks straight from a server page.tsx gets that error at render time. Keeping the columns and callbacks in a client file and passing only plain rows avoids it.

Two more details come straight from the docs get_component returns. The mobile roles pick each card's title and subtitle below 768px, where the table becomes cards by default (mobileLayout="cards"). And persistKey remembers column visibility, order, widths, density and page size in local storage.

Live demo: Data Table. The original article embeds an interactive demo here (Search for a client, toggle the Overdue chip, then sort or filter from the toolbar; on a phone the rows become cards with a Load more button). Try it live on wingo-ui.com or open the Data Table docs. Install: npx wingo-ui@latest add data-table

Without JavaScript, the demo is a client table (client, city, status, owner, balance, last invoice) with a search field, quick filter chips such as Active and Overdue, and export and new client actions.

One more case to plan for: the Login Page and the Data Table are both Pro. Without a Pro key, steps 3 and 4 return the docs plus the refusal quoted earlier, and an agent that follows the rules reports the gap instead of rebuilding them from their props tables.

How do agent-installed components stay up to date?

The agent checks, you decide. At the start of UI work the rules ask for check_updates with the items in wingo-ui.json. The answer lists each update with its semver bump and the notes of every library release that touched the item, then the items that are current. Here is the real output for a project with an older Data Table and a current Button:

Latest Wingo UI release: 1.7.0.

1 update:
- **data-table**: 1.0.0 → 1.1.0 (minor)
  - 1.2.0: with no rows to show the empty state stands alone and compact, without column headers spread over nothing; `showHeaderWhenEmpty` keeps them.
  - 1.0.1: sticky header cells no longer drop down over the first row when the header is pinned while scrolling.

Update with `npx wingo-ui@latest update <slug...>` (a 3-way merge that keeps local edits); read breaking notes first.

Up to date: button

The numbers in front of the notes are library releases; the item itself goes from 1.0.0 to 1.1.0.

The Claude Code skill tells the agent to mention updates and run them only when you agree. An update is a code change in files you own, and it deserves the same review as any other diff. From the terminal the loop is three commands:

npx wingo-ui@latest outdated        # installed items vs the latest release
npx wingo-ui@latest diff data-table # your file vs upstream
npx wingo-ui@latest update          # 3-way merge, with the release notes

The rules have their own version: agents status reports an old copy and agents update refreshes it. To keep your own edits to a managed file, delete its wingo-ui:managed line. The updates docs cover conflicts and the --theirs flag, and our guide to updating shadcn components without losing edits shows the same 3-way merge done by hand with git.

How do I check what the agent built?

Review it like a pull request from a fast junior developer who has read the docs. The server gets the first draft onto the right components; it does not replace looking at the result. Our checklist:

• Hardcoded colors and radii. Search the diff for hex values, rgb( and arbitrary rounded-[...] classes. The rules ask for semantic tokens, and a stray hex color is easy to miss.
• Rebuilt components. A new file under components/ that looks like a library item means the agent skipped search.
• Restyling instead of props. A long class list on a Button often stands in for a variant, tone or size the agent did not read.
• Simulated handlers. Blocks ship demo handlers for every on* prop. Compare the handlers the agent wired with the features left on screen, as in the login example above.
• Phone width and both themes. At 390px tables should become cards and menus should open as bottom sheets (our mobile-first React components guide has the full list); light and dark should both hold up.
• Library files. npx wingo-ui@latest diff <slug> shows whether the agent edited one. Edits are allowed, but they become merge work on the next update.

Should you build an MCP server for your own design system?

If several people or agents build UI on an internal library, yes. A UI component library MCP server is a smaller project than it sounds: ours is one file of about 220 lines on the TypeScript SDK (@modelcontextprotocol/server) plus four small tool modules, and most of the effort went into the data behind it. The protocol part was the easy bit. What we would tell a design system team, from building ours:

• Start from metadata you already keep. Our tools read the same registry metadata that renders the docs pages. If your props live only in TypeScript types, extract them once into data the docs and the server share, or the two will drift.
• Keep every tool read-only. Let the agent read; let your CLI or package manager write.
• Return structured content and text. The model reads the text; scripts and future clients parse the structure.
• Make outputs small and name the next step. Slugs in search, the source behind a flag, the next tool at the end.
• Write errors as instructions. "Did you mean ..." and "do not re-create it" put the fix in front of the model at the moment it needs it.
• Keep server instructions under 2,048 characters, with the "when to use this server" sentence first. Ours are 187 characters over in 1.7.0, and the sentence that falls off is one we care about.
• Serve the release you deployed. One fresh server per request, backed by that deploy's registry, means agents never see stale props.
• Offer HTTP and stdio. Remote HTTP for clients that send headers, a local proxy for the rest.

The MCP server for UI components we run answers without an account, so you can point any client at it and see these choices from the agent's side before you design your own.

Where should I start?

To try it, connect the server with npx wingo-ui@latest agents install claude (or your agent's name) and ask for a screen in plain words. A free account adds the source of the 75 free items to MCP answers, including the Button and the OTP Input; the CLI installs those without an account. The Login Page and Data Table are part of Pro, which covers all 326 items: $8 a month, $80 a year or $150 once, on the pricing page. The MCP server docs have the per-client setup and troubleshooting.

If you maintain your own library, an MCP server is the cheapest way we know to make agents use it correctly. Pair it with five lines of rules and an installer that records versions, and the agent stops inventing your components and starts installing them.

Components in this post

• Button (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: npx wingo-ui@latest add button
• Login Page (Pro): The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. Install: npx wingo-ui@latest add login-page
• Data Table (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: npx wingo-ui@latest add data-table

FAQ

What is a component library MCP server?

It is a Model Context Protocol server that exposes a UI library to coding agents as tools: search the catalog, read one component's props with defaults and usage, fetch the design rules and check installed items for updates. The agent calls these tools instead of guessing an API from its training data.

Do I still need a rules file if I connect an MCP server?

Yes. The server supplies facts, but an agent does not always reach for a tool on its own. A few lines in CLAUDE.md, AGENTS.md or a Cursor rule tell it to search before it writes UI, to install with the CLI and never to rebuild a component the library has.

Is llms.txt enough without an MCP server?

It helps assistants that can only read URLs, but it cannot act on anything. It cannot install files, compare your installed versions with the latest release or tell the agent which items your plan includes.

Does the Wingo UI MCP server work without an account?

Yes for docs: search, props, usage, design rules and theme tokens answer without a key. A key from a free account (email only) adds the source of the 75 free items, and a Pro key adds the source of everything else.

Can I use the shadcn MCP server with Wingo UI?

Yes. Add the @wingo-ui registry to components.json, with your API key for Pro items, and the shadcn MCP server can search and install from it. It does not serve our design rules or update checks, and the shadcn CLI does not record versions, so wingo-ui update cannot merge later releases into files installed that way.

Which coding agents can connect to the Wingo UI MCP server?

npx wingo-ui@latest agents install writes ready configs and rules for Claude Code, Codex, Gemini CLI, Grok and Cursor. Any other client that runs local commands can use the stdio proxy, npx -y wingo-ui@latest mcp.

This article was originally published on the Wingo UI blog: Component Library MCP: Make Agents Use Real Components. The original has the live, interactive demos and is kept up to date.

Tailwind v4 design tokens are CSS variables: keep the values that change between light and dark in :root and .dark, then map them to utilities with @theme inline, so bg-surface or text-muted-foreground follow the theme with no dark: prefix. A complete set names roles instead of colors: surfaces in the order they stack, text levels, tones split into a solid fill and a readable text color, plus radius, elevation, z-index and motion scales. Check every text and surface pair for 4.5:1 contrast in both themes with a script, because a color that passes on white often fails on a dark popover.

Tailwind CSS v4 moved configuration out of tailwind.config.js and into CSS, and many guides stop at the first step: put a few brand colors in @theme and call them tokens. A component library needs more than a palette. It needs Tailwind v4 design tokens for every decision a component makes: which surface sits in front of which, how muted secondary text can get, what a warning uses as a fill and as text, how round a 32px button is next to a 48px one, how a popover casts a shadow on a black page, and which layer a select opens on inside a dialog. This guide is the token system we use in Wingo UI, a React 19 and Tailwind CSS v4 component library, with the real CSS and the contrast numbers behind each choice. We build Wingo UI, so we are not neutral; outside facts link to their sources and are dated.

What are design tokens in Tailwind v4?

Design tokens in Tailwind v4 are CSS custom properties. Tailwind v4 theme variables, the ones you declare inside an @theme block, do two jobs at once: they are CSS variables you can read with var(), and their namespace decides which utilities Tailwind generates. --color-surface creates bg-surface, text-surface and border-surface; --shadow-raised creates shadow-raised. Tailwind CSS v4.0 shipped this CSS-first configuration on January 22, 2025 (release post), and the theme variables docs list the namespaces. We run Tailwind 4.3.3 as of October 2026.

The namespaces a component library uses most:

--z-index-* and --transition-duration-* are not in the docs table as of October 2026, but Tailwind 4.3 compiles them: our CSS has .z-modal { z-index: var(--z-modal) }.

How should you layer Tailwind v4 design tokens?

Use three layers. Raw values that change between themes go in :root and .dark. A mapping in @theme inline turns them into utilities. Components then paint through a few runtime variables that a prop sets, so a tone or a custom color never needs its own class.

Here is a trimmed but working excerpt of our app/globals.css, with the real values:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.3211 0 0);
  --surface: #ffffff;
  --popover: oklch(1 0 0);
  --muted-foreground: oklch(0.52 0.0234 264.3637);
  --success: #15803d;
  --success-foreground: #ffffff;
  --success-soft: #e7f6ec;
  --success-soft-foreground: #166534;
  --elevation-raised: 0 0 0 1px rgb(0 0 0 / 0.07), 0 1px 2px rgb(0 0 0 / 0.05), 0 2px 8px -2px rgb(0 0 0 / 0.06);
}

.dark {
  --background: oklch(0 0 0);
  --foreground: oklch(0.9219 0 0);
  --surface: #1a1a1a;
  --popover: #262626;
  --muted-foreground: oklch(0.7155 0 0);
  --success-soft: #0d2315;
  --success-soft-foreground: #4ade80;
  --elevation-raised: inset 0 1px 0 0 rgb(255 255 255 / 0.06), 0 0 0 1px rgb(255 255 255 / 0.08), 0 1px 2px rgb(0 0 0 / 0.5);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-surface: var(--surface);
  --color-popover: var(--popover);
  --color-muted-foreground: var(--muted-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-success-soft: var(--success-soft);
  --color-success-soft-foreground: var(--success-soft-foreground);
  --shadow-raised: var(--elevation-raised);
}

The success fill and its white text are the same in both themes (5.02:1), so this excerpt declares them only in :root and .dark inherits them. Everything that changes is redeclared under .dark, and a component uses the same classes everywhere:

export function InvoiceRow() {
  return (
    <div className="flex items-center justify-between rounded-2xl bg-surface p-4 text-foreground shadow-raised">
      <div>
        <p className="text-[15px] font-medium">Invoice 1042</p>
        <p className="text-sm text-muted-foreground">Emma Carter, New York</p>
      </div>
      <span className="rounded-full bg-success-soft px-2 py-0.5 text-xs font-medium text-success-soft-foreground">Paid</span>
    </div>
  );
}

The raw names follow shadcn/ui's convention on purpose: --background, --card, --popover and --muted-foreground are shadcn names, and the ones shadcn does not have (--surface, --canvas, the --success-* family) use the same name and name-foreground pattern. A project that already has shadcn tokens can take ours without renaming anything.

When do you need Tailwind v4 @theme inline?

Use @theme inline whenever a theme variable points at another variable, which is every token that changes with the theme. The Tailwind docs say it directly: with inline, "the utility class will use the theme variable value instead of referencing the actual theme variable". Here is what that means in compiled CSS:

/* @theme inline { --color-surface: var(--surface); } */
.bg-surface {
  background-color: var(--surface);
}

/* @theme { --color-surface: var(--surface); } */
:root, :host {
  --color-surface: var(--surface);
}
.bg-surface {
  background-color: var(--color-surface);
}

The difference shows up below the root. A custom property inherits its computed value, and var() is substituted where the property is declared. In the second version --color-surface is resolved once, on :root, and every element inherits that result. A .dark class on <html> still works, because <html> is the root. A dark section inside a light page (<section className="dark">), a dark preview pane or a data-theme attribute on a container does not: the section inherits the light value that :root already resolved. With inline, bg-surface reads var(--surface) on the element itself, so it picks up the nearest override. The Tailwind docs explain the option with the same kind of parent and child example.

One catch remains with inline: if you write var(--color-surface) yourself, in an arbitrary value like bg-[var(--color-surface)] or in plain CSS, Tailwind 4.3 emits --color-surface: var(--surface) on :root to satisfy it, and that reference is resolved on the root again. Inside components, read the raw variable instead: bg-(--surface) or var(--surface).

Two more rules from the docs: theme variables must sit at the top level, never under a selector or a media query, so per-theme values live outside @theme anyway; and Tailwind only emits the theme variables your code uses, unless you write @theme static. The raw variables in :root always ship, which helps when a chart library reads a token with getComputedStyle.

Which semantic color tokens does a component library need?

Name colors by role, never by hue. A component library needs surfaces in the order they stack, text levels with a contrast floor, translucent tints for hover and fills, a border and a focus ring, and status tones. With semantic color tokens, components never contain bg-gray-100 or text-blue-600, so a theme can change every value without touching a component.

Surfaces, back to front

In dark mode the surfaces get lighter as they come forward: #000, #121212, #1A1A1A, #262626. In light mode most of them are white, so the shadow does the separating. canvas exists because a dashboard on a white page has nothing to set white cards against; a cool gray page makes every bg-surface panel read as a card.

Text levels

text-muted-foreground is the floor for anything people must read. The disabled level has no contrast target because WCAG 2.2 success criterion 1.4.3 exempts text in inactive controls, which is why it is never used for anything else.

Tints instead of gray fills

Hover states, field fills, chips, tracks and skeletons use translucent foreground: bg-foreground/5, /7, /10 and /15, plus border-foreground/10 for hairlines. Tailwind 4.3 compiles the opacity modifier to color-mix(), with the plain color as a fallback:

.bg-foreground\/5 {
  background-color: var(--foreground);
  @supports (color: color-mix(in lab, red, red)) {
    background-color: color-mix(in oklab, var(--foreground) 5%, transparent);
  }
}

A tint is relative to whatever sits behind it, so it moves one step toward the text color on every surface, in both themes. A fixed fill cannot do that. Our dark --muted is #171717: lighter than the black page and darker than the #1A1A1A surface, so the same field would look raised on one and sunken on the other. The full-strength fallback only shows in browsers without color-mix(), which are all below Tailwind's browser baseline of Chrome 111, Safari 16.4 and Firefox 128.

shadcn/ui's secondary and accent stay in our file so ported components keep working, but our --accent is an orange tint, and new components never use either.

How do status colors work without a class per color?

Give each status tone four tokens: a solid fill, the text on that fill, a soft tinted surface, and tone text that reads on the soft surface and on every neutral surface. Then let components paint through five generic variables that one class sets. That is the whole idea behind the free Tones utility.

The four tokens per tone, for brand, success, warning, destructive and info:

--success: #15803d;                 /* bg-success: buttons, solid badges, progress */
--success-foreground: #ffffff;      /* text on the fill */
--success-soft: #e7f6ec;            /* bg-success-soft: soft badges, alerts, selected rows */
--success-soft-foreground: #166534; /* colored text on the tint and on any neutral surface */

The split between fill and tone text is the easiest rule to skip, and it is where dark mode breaks. Fills are tuned to carry white text, and they make poor text. text-destructive (#DC2626) on our dark popover is 3.13:1; text-destructive-soft-foreground (#FF8A80) on the same surface is 6.63:1. The warning fill is amber (#F5A524) at 2.04:1 against white, so it carries dark text (#2B1700, 8.40:1) and is never used as text on a neutral surface.

Component variables

A component with a tone prop does not map tokens itself. toneClasses[tone] sets five variables, and every variant paints with them:

// lib/tones.ts (excerpt)
success:
  "[--tone:var(--success)] [--tone-foreground:var(--success-foreground)] [--tone-soft:var(--success-soft)] [--tone-soft-foreground:var(--success-soft-foreground)] [--tone-border:color-mix(in_oklab,var(--success)_45%,transparent)]",

The neutral tone maps --tone to --primary (black in light, near-white in dark) and builds its soft surface from color-mix(in oklab, var(--foreground) 7%, transparent), which is why a neutral soft button works on any surface. A badge built this way:

import type { ComponentProps } from "react";
import { colorVars, toneClasses, type Tone } from "@/lib/tones";
import { cn } from "@/lib/utils";

type StatusBadgeProps = ComponentProps<"span"> & { tone?: Tone; color?: string };

export function StatusBadge({ tone = "neutral", color, className, style, ...props }: StatusBadgeProps) {
  return (
    <span
      data-slot="status-badge"
      className={cn(
        toneClasses[tone],
        "inline-flex rounded-full bg-(--tone-soft) px-2 py-0.5 text-xs font-medium text-(--tone-soft-foreground)",
        className,
      )}
      style={{ ...colorVars(color), ...style }}
      {...props}
    />
  );
}

bg-(--tone-soft) is Tailwind v4's shorthand for bg-[var(--tone-soft)]. The free Badge is the full version of this pattern, with solid, soft and outline variants. colorVars(color) builds the same five variables from any CSS color as an inline style. Its text-on-fill value uses relative color syntax, oklch(from <color> clamp(0, (0.7 - l) * 1000, 1) 0 0): white when the color's OKLCH lightness is below 0.7, black above. As of October 2026, caniuse lists full support for relative color syntax from Chrome 131, Safari 18 and Firefox 133, and partial support before that, so full support arrived later than Tailwind's own baseline. Where a browser cannot compute the value, the declaration is invalid at computed-value time and the text inherits its parent's color. If you support those browsers, force the text color with className="[--tone-foreground:white]".

Live demo: Tones. The original article embeds an interactive demo here (Each row paints one tone three ways from the same five variables, and the last row is built by colorVars from one hex value, #0EA5E9. Switch the site theme: the solid fills stay, while the soft tints and the tone text take their dark values). Try it live on wingo-ui.com or open the Tones docs. Install: npx wingo-ui@latest add tones

The free Button is the reference consumer. Its variant map contains no color at all:

const VARIANTS: Record<ButtonVariant, string> = {
  solid: "bg-(--tone) text-(--tone-foreground) shadow-raised",
  soft: "bg-(--tone-soft) text-(--tone-soft-foreground)",
  outline: "border border-(--tone-border) text-(--tone-soft-foreground)",
  ghost: "text-(--tone-soft-foreground)",
  link: "rounded-[4px] text-(--tone-soft-foreground) underline decoration-current/35 decoration-1 underline-offset-4 transition-[color,text-decoration-color] hover:decoration-current",
};

Six tones times five variants, plus any custom color, from five lines. Hover and press are a layer of currentColor at 8% and 12% opacity, so they also work for every tone without extra classes.

How do you design dark mode with tokens?

Treat dark as a second set of values for the same roles, picked by hand, and switch it with a class. Components keep the same classes in both themes, so almost nothing in a component needs a dark: prefix.

The variant: our tokens, like shadcn/ui's, use @custom-variant dark (&:is(.dark *));. The Tailwind dark mode docs show &:where(.dark, .dark *), which also matches the element that carries the class and adds no specificity. With the class on <html>, both behave the same for normal use. The class itself comes from next-themes, which writes it before the first paint: wrap the app in its ThemeProvider with attribute="class" (the full provider file is in the props section below), and render <html lang="en" suppressHydrationWarning> in the root layout, because next-themes changes the class before React hydrates:

// app/layout.tsx
import type { ReactNode } from "react";
import { Providers } from "./providers";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className="bg-background text-foreground">
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

What a designed dark theme looks like in practice, from our token file:

• Surfaces lighten as they come forward. #000 page, #121212 card, #1A1A1A surface, #262626 popover.
• Fills stay, soft surfaces flip. The brand fill is #D63F00 in both themes, so white text keeps 4.59:1. Its soft surface goes from #FFEFE6 to #2A1509, and its text from #B03400 to #FF8A4C.
• The neutral fill inverts. primary is black with white text in light mode and #FAFAFA with #171717 in dark, so the neutral solid button keeps 21:1 in light and 17.16:1 in dark.
• Elevation changes technique. A drop shadow barely shows on black, so dark shadows lean on a lit top edge and a white hairline (see the elevation levels below).
• The focus ring shifts. --ring is oklch(0.60 0.20 36.93) in light and oklch(0.6617 0.2215 36.93) in dark, deeper on white so a 2px outline keeps 3:1 on white and on the gray card.
• Some components need an exception. Our soft Card uses bg-card in light but bg-foreground/7 in dark, because the dark --card is the same gray as a dark sidebar or stage and the card would vanish there. An inversion script never makes that call.

How do you check contrast for every token pair?

List the pairs that are meant to be used together, convert both colors to sRGB, compute the WCAG ratio in both themes, and fail the build below 4.5:1. WCAG asks for 4.5:1 for body text and 3:1 for large text (1.4.3), and 3:1 for UI components and focus indicators against what is next to them (1.4.11).

Our check covers 54 pairs per theme, 108 in total, and reports 0 below 4.5:1 as of release 1.7.0. The tightest pairs are brand-foreground on brand at 4.59:1 and muted-foreground on the light card at 4.62:1. Here is a self-contained version you can drop into scripts/ and run with npx tsx scripts/check-contrast.ts. It reads hex and oklch() values (decimal or percent lightness), follows var() references and exits with code 1 on a failure. It expects the token names used in this guide; if yours differ, edit SURFACES, TONES and PAIRS:

// scripts/check-contrast.ts
import { readFileSync } from "node:fs";

type Rgb = [number, number, number];
const css = readFileSync("app/globals.css", "utf8").replace(/\/\*[\s\S]*?\*\//g, "");

// every --name: value inside the blocks that start with this selector
function vars(selector: string) {
  const map = new Map<string, string>();
  const block = new RegExp(`(?:^|\\n)${selector.replace(".", "\\.")}\\s*\\{([^}]*)\\}`, "g");
  for (const m of css.matchAll(block))
    for (const d of m[1].matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) map.set(d[1], d[2].trim());
  return map;
}

export function oklchToRgb(l: number, c: number, h: number): Rgb {
  const a = c * Math.cos((h * Math.PI) / 180);
  const b = c * Math.sin((h * Math.PI) / 180);
  const l3 = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
  const m3 = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
  const s3 = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
  const linear = [
    4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
    -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
    -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3,
  ];
  // clamp into srgb, then gamma-encode
  return linear.map((v) => {
    const x = Math.min(1, Math.max(0, v));
    return x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055;
  }) as Rgb;
}

function parse(value: string, map: Map<string, string>): Rgb {
  const ref = value.match(/^var\((--[\w-]+)\)$/);
  if (ref) return parse(map.get(ref[1]) ?? "", map);
  if (value.startsWith("#")) {
    const hex = value.length === 4 ? [...value.slice(1)].map((ch) => ch + ch).join("") : value.slice(1);
    return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255) as Rgb;
  }
  const ok = value.match(/^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)\s*\)$/);
  if (ok) return oklchToRgb(ok[2] ? +ok[1] / 100 : +ok[1], +ok[3], +ok[4]);
  throw new Error(`cannot parse "${value}"`);
}

const channel = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
const luminance = ([r, g, b]: Rgb) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);

export function contrast(fg: Rgb, bg: Rgb) {
  const [hi, lo] = [luminance(fg), luminance(bg)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}

const SURFACES = ["background", "card", "popover", "surface", "canvas"];
const TONES = ["brand", "success", "warning", "info", "destructive"];
const PAIRS = [
  ["foreground", "background"],
  ...SURFACES.map((s) => ["muted-foreground", s]),
  ...TONES.flatMap((t) => [
    [`${t}-foreground`, t],
    [`${t}-soft-foreground`, `${t}-soft`],
    ...SURFACES.map((s) => [`${t}-soft-foreground`, s]),
  ]),
];

const light = vars(":root");
const themes = { light, dark: new Map([...light, ...vars(".dark")]) };
let failures = 0;
for (const [theme, map] of Object.entries(themes)) {
  for (const [fg, bg] of PAIRS) {
    const ratio = contrast(parse(map.get(`--${fg}`) ?? "", map), parse(map.get(`--${bg}`) ?? "", map));
    if (ratio < 4.5) {
      failures++;
      console.log(`FAIL ${theme}: ${fg} on ${bg} is ${ratio.toFixed(2)}:1`);
    }
  }
}
console.log(`${PAIRS.length * 2} pairs checked, ${failures} below 4.5:1`);
process.exitCode = failures ? 1 : 0;

This trimmed version checks 82 pairs. Our full script adds the remaining surface, primary and legacy pairs and composites translucent values over the page first. The pair list is the valuable part: it encodes which text may sit on which surface, so a new token is checked the day it is added. Run it in CI next to the type check.

Should you write Tailwind v4 OKLCH values or hex?

Use whichever format you can reason about; the format does not change contrast. Tailwind's own palette moved "from rgb to oklch, taking advantage of the wider gamut" in v4.0 (release post), and its colors reference lists every Tailwind v4 OKLCH value, such as --color-red-500: oklch(63.7% 0.237 25.331). OKLCH earns its place when you derive colors in code, because lightness is its own channel: you can move it while hue and chroma stay put, and the result still looks like the same color.

In our file, neutrals are oklch() with zero chroma (oklch(0.3211 0 0) is the light foreground), and the tone values are hex, tuned by hand against the contrast check. The theme generator goes the other way: you pick a base color for each tone (brand, success, warning, danger, info), and it derives that tone's fill, soft surface and text in OKLCH. For light mode it puts the soft surface at lightness 0.965 with chroma capped at 0.035, then walks the tone text's lightness down from 0.6 in 0.005 steps until it reaches 4.6:1 on the soft surface and on every neutral surface. Move oklchToRgb and contrast from the contrast script into their own module, scripts/color.ts, so importing them does not run the check, and the same search is a few lines:

import { contrast, oklchToRgb } from "./color";

type Rgb = [number, number, number];

// keep hue and chroma, walk lightness until the color reads on every surface it can sit on
export function findReadable(c: number, h: number, surfaces: Rgb[], from: number, to: number, target = 4.6): Rgb {
  const step = from < to ? 0.005 : -0.005;
  for (let l = from; step > 0 ? l <= to : l >= to; l += step) {
    const rgb = oklchToRgb(l, c, h);
    if (Math.min(...surfaces.map((bg) => contrast(rgb, bg))) >= target) return rgb;
  }
  return oklchToRgb(to, c, h);
}

The target is 4.6 rather than 4.5 so rounding to hex cannot push a color under the line. One caution: a high-chroma OKLCH value can fall outside sRGB, and what a screen then shows depends on the display and the browser. Keep token values inside sRGB, or at least measure the clamped sRGB value, as oklchToRgb does.

How do radius, elevation, z-index and motion become tokens?

They become scales with a fixed set of steps, each with one job, so a component picks a step instead of a number. A Tailwind v4 design system that only tokenizes color still ends up with one-off shadows and a z-[9999] somewhere.

Radius follows size

Tie radius to the control's size. A 32px and a 48px button only read as the same shape when the larger one has the larger radius. Our controls copy this map from the Button:

type Scale = "sm" | "md" | "lg";
type ButtonRadius = "none" | "sm" | "md" | "lg" | "full";

const RADII: Record<ButtonRadius, Record<Scale, string>> = {
  none: { sm: "rounded-none", md: "rounded-none", lg: "rounded-none" },
  sm: { sm: "rounded-[6px]", md: "rounded-[8px]", lg: "rounded-[10px]" },
  md: { sm: "rounded-[8px]", md: "rounded-[10px]", lg: "rounded-[12px]" },
  lg: { sm: "rounded-[10px]", md: "rounded-[14px]", lg: "rounded-[16px]" },
  full: { sm: "rounded-full", md: "rounded-full", lg: "rounded-full" },
};

Surfaces use rounded-2xl (16px) for cards, menus and popovers, rounded-3xl (24px) for dialogs, and rounded-t-[28px] for bottom sheets. Anything inside a padded surface takes the outer radius minus the padding: a rounded-2xl p-1.5 menu has rounded-[10px] items. Sizes follow the same thinking: 32, 40 and 48px, with the 40px size growing to 44px on touch screens, the rule from our mobile-first React components guide.

The trap is a global radius token. Our file still carries shadcn/ui's older scale for ported components: --radius: 0.375rem, --radius-lg: var(--radius) and --radius-sm: calc(var(--radius) - 4px). That remaps Tailwind's rounded-sm, rounded-md, rounded-lg and rounded-xl to 2, 4, 6 and 10px everywhere, including markup pasted from Tailwind's docs (the compiled .rounded-lg is border-radius: var(--radius)), so new components never use those four classes. As of October 2026, shadcn/ui's theming docs derive the scale by multiplication instead (--radius-sm: calc(var(--radius) * 0.6) up to --radius-4xl), which has the same project-wide reach. If you theme radius globally, own every component that uses it.

Three elevation levels

Three levels cover a library: shadow-raised for buttons, cards and thumbs, shadow-floating for popovers, menus and toasts, shadow-modal for dialogs and sheets. Each level carries its own 1px hairline, so an elevated surface needs no border:

:root {
  --elevation-floating: 0 0 0 1px rgb(0 0 0 / 0.06), 0 4px 12px -2px rgb(0 0 0 / 0.08), 0 16px 36px -10px rgb(0 0 0 / 0.16);
}
.dark {
  /* on a black page a drop shadow barely shows: a lit top edge and a hairline do the work */
  --elevation-floating: inset 0 1px 0 0 rgb(255 255 255 / 0.07), 0 0 0 1px rgb(255 255 255 / 0.09), 0 8px 24px -4px rgb(0 0 0 / 0.6), 0 20px 48px -12px rgb(0 0 0 / 0.7);
}
@theme inline {
  --shadow-floating: var(--elevation-floating);
}

An interactive Card moves between two of these levels on hover, and the lift runs as a CSS transition on a spring curve (below), so a grid of fifty cards animates without JavaScript.

Live demo: Card. The original article embeds an interactive demo here (Hover the card to see it lift from shadow-raised to shadow-floating, then press it to see the dip to 98% (phones get only the press). Switch the site theme to see the dark elevation draw a lit top edge instead). Try it live on wingo-ui.com or open the Card docs. Install: npx wingo-ui@latest add card

Stacking layers

Popovers sit above modals on purpose: a select inside a dialog has to open over it. No overlay in the library uses a raw number like z-50; small values such as z-10 only order parts inside one component.

Motion

CSS transitions use three durations (duration-fast 150ms, duration-normal 240ms, duration-slow 400ms) and named curves (ease-smooth is cubic-bezier(0.22, 1, 0.36, 1), ease-sheet is cubic-bezier(0.32, 0.72, 0, 1)). Our JavaScript springs are also sampled into CSS linear() easings: ease-spring with duration-spring (500ms) matches a spring with stiffness 300 and damping 30.

Can component props work like design tokens?

Yes, for the decisions that are props: the radius of every button, the default size of fields, the variant of every card. CSS variables cannot set a prop, so Wingo UI reads those from a React provider, and UIProvider defaults works as a token layer for props. The free UIProvider merges app-wide defaults under the props each component receives, keyed by its data-slot name:

// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { ThemeProvider } from "next-themes";
import { UIProvider } from "@/lib/ui-config";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
      <UIProvider locale="en-US" defaults={{ button: { radius: "full" }, card: { variant: "outline" } }}>
        {children}
      </UIProvider>
    </ThemeProvider>
  );
}

Inside a component, the first line reads the defaults, and the signature defaults stay the last fallback:

export function Button(buttonProps: ButtonProps) {
  const { variant = "solid", tone = "neutral", size = "md", radius = "md", ...rest } = useDefaults("button", buttonProps);
  // ...
}

Explicit props win, then the provider, then the component's own defaults. An undefined prop does not override a provider value, so wrappers can pass props through without erasing the theme. The same signature takes ref as a regular prop, with no forwardRef wrapper; our React 19 forwardRef migration guide moves older components to that pattern, TypeScript types included.

Live demo: UIProvider. The original article embeds an interactive demo here (The first button uses its built-in defaults; the two below get radius full, size lg and tone brand from a UIProvider, and the outline one keeps the variant it passes itself). Try it live on wingo-ui.com or open the UIProvider docs. Install: npx wingo-ui@latest add ui-config

How do you add these tokens to an existing Next.js project?

Run npx wingo-ui@latest init in a project that has Tailwind CSS v4. It writes wingo-ui.json and lib/utils.ts (the cn helper), installs clsx and tailwind-merge, and merges the tokens into the stylesheet that contains @import "tailwindcss". It only adds missing names and keeps your values; add later brings any tokens a new component needs. The full block, 74 variables in :root plus their dark values and Tailwind mappings, is served at /r/tokens.css, and coding agents get the same CSS from the MCP tool get_theme_tokens (see our component library MCP guide). The theming docs show the main tokens with their light and dark values, and the two dark mode setups the CLI supports: a .dark class, or prefers-color-scheme when your stylesheet already uses it.

To restyle, open the theme generator, pick a brand color, neutrals, radius, font and component defaults, check its contrast report, and apply the export:

npx wingo-ui@latest theme apply ./theme.json

It replaces the values of the tokens the theme sets, in light and dark, adds Tailwind mappings for new ones and prints the UIProvider defaults and locale to paste into your provider.

Coming from shadcn/ui: the shared names line up, but two keep different meanings. Our --card is a flat gray tile where shadcn's is the card background, and our --accent is an orange tint. Because init keeps your existing values, a shadcn project keeps its own --card and --accent, so check the soft Card variant after the merge. Our shadcn alternatives comparison covers the wider differences between the two libraries.

Which mistakes break a Tailwind v4 design system?

The same few mistakes show up in most token files:

• dark: classes in components. A component that needs dark:bg-zinc-900 is missing a token.
• Palette names in components. bg-blue-600 cannot follow a theme; use a role or a tone.
• Fill colors as text. text-destructive on a dark surface fails AA; use the soft foreground.
• Per-theme values in plain @theme. Keep them in :root and .dark, mapped with inline.
• A global radius that rewrites Tailwind's scale. Every pasted rounded-lg changes with it.
• Raw z-index numbers. Two z-50 overlays from two authors will collide.
• No contrast check. Tokens drift with every tweak; a check in CI catches it the same day.

Where should you start?

Run npx wingo-ui@latest init in your Next.js project, then npx wingo-ui@latest add button, which brings the Tones and UIProvider items with it. Replace one hard-coded color in a real screen with a role token, open it in both themes, and add the contrast script to CI. Two more guides in Next.js and Tailwind CSS cover the component code around the tokens: the React 19 forwardRef migration and an SSR-safe React use mobile hook that hydrates without a mismatch.

Components in this post

• Button (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: npx wingo-ui@latest add button
• Tones (Free): One way to color a component: a tone or any CSS color becomes five CSS variables every variant paints with. Install: npx wingo-ui@latest add tones
• UIProvider (Free): App-wide configuration for Wingo UI: default props for every component, the Intl locale and the reduced-motion policy. Install: npx wingo-ui@latest add ui-config
• Card (Free): The surface listings, stats, settings and plans sit on: media, header, body and footer parts, four variants and a lift-and-press mode. Install: npx wingo-ui@latest add card
• Badge (Free): Status chips, removable filters and animated counts in three variants and six tones, plus an anchor that pins a count or dot to any corner. Install: npx wingo-ui@latest add badge

FAQ

Where do design tokens go in Tailwind v4?

In the global CSS file, after @import "tailwindcss". Variables in an @theme block become utilities (--color-surface gives bg-surface), and values that change per theme live in :root and .dark and are mapped with @theme inline. A tailwind.config.js file is no longer required.

What is the difference between @theme and @theme inline in Tailwind v4?

With @theme, the utility references the theme variable, so bg-surface compiles to var(--color-surface), which is resolved once on :root. With @theme inline, the utility gets the referenced value written in, so bg-surface compiles to var(--surface) and resolves on the element that uses it. Use inline whenever a theme variable points at another variable.

Should Tailwind v4 colors be OKLCH or hex?

Either works, because tokens are plain CSS colors and the format does not change contrast. Tailwind's own palette moved to oklch in v4.0. OKLCH helps most when you derive colors in code, since you can keep hue and chroma and move lightness until a contrast target passes.

How do I add dark mode to Tailwind v4 design tokens?

Redefine the same variables in a .dark block and add @custom-variant dark (&:is(.dark *)); so dark: utilities follow the class too. next-themes with attribute="class" sets the class before the first paint. Components that use semantic tokens then need no dark: classes.

How do I check color contrast for design tokens?

List every text token with each surface it can sit on, convert the values to sRGB, and compute the WCAG ratio for light and dark. Fail the build below 4.5:1 for body text; focus rings and other UI shapes need 3:1.

Are the Wingo UI design tokens free?

Yes. npx wingo-ui@latest init merges the tokens into your stylesheet without an account, and the Button, Card, Tones and UIProvider items in this guide are free. As of release 1.7.0, 75 of the 326 registry items are free and the rest need Pro.

This article was originally published on the Wingo UI blog: Tailwind v4 Design Tokens: Colors, Dark Mode and Contrast. The original has the live, interactive demos and is kept up to date.

For a responsive table on mobile, render each row as a card below 768px: the main field as the title, one status or amount in the corner, two to four label and value pairs, and the row actions in a menu. Keep horizontal scrolling only for grids people compare column by column, like a timesheet or a pricing matrix. Switch the layouts with CSS breakpoints so the server HTML is already right, and give sorting, selection and bulk actions their own phone controls, because the headers and checkbox column are gone.

You ship an admin page with a seven-column table, open it on a phone, and see the client name, half a city and a horizontal scrollbar. The column headers have scrolled away by the time you reach the amount, and nobody can tell which number belongs to which row. A good responsive table mobile view is a different layout for most tables, not a narrower version of the same one. This tutorial shows when to turn rows into cards, which columns make it onto the card, how to build the switch on a plain shadcn/ui table without a hydration flash, and how sorting, selection and bulk actions keep working once the headers and the checkbox column are gone.

The short version of this rule is one of nine in Mobile-first React components. This post is the detailed version.

When should a table become cards on a phone?

When people read one record at a time. A list of clients, orders, invoices or tickets is a list of records: on a phone you scan for the one you want, then open it. A card per row shows everything that matters about that record in one glance, with no sideways scrolling and no header to remember.

Keep the table when the job is comparing values across rows and columns. A timesheet, a pricing matrix, a monthly revenue grid or a feature comparison only makes sense when the columns line up, and cards destroy that. For those, let the table scroll sideways inside its own box and pin the first column so every row keeps its name.

The last row catches a common mistake: a "table" with two columns, Label and Value, describing one client. That is a description list. The Description List stacks label above value on phones and switches to one to three columns based on its container width, so it fits a narrow sidebar card as well as a full page.

Why does horizontal scrolling fail for records?

A 390px screen shows two or three columns of an admin table at once. To read one record, people scroll right, lose the name column, scroll back, and repeat for every row. The header usually scrolls out of view vertically too, so the numbers they reach have no labels. Every row costs two scroll directions.

Horizontal scrolling is also what you get by default. Out of the box, shadcn table mobile responsive behavior means a scroll: the shadcn/ui Table wraps the <table> in a div with relative w-full overflow-x-auto, so a wide table never breaks the page layout, it just scrolls inside that box. That is the right fallback, and the right layout for comparison grids, but for a client list it means the phone gets the desktop table at a third of the width.

Which columns survive on a card?

Five or six of them, each in a defined slot. Go through your columns and give each one a role:

• Title: the field people recognize the record by. The client name, the order number, the ticket subject. One per card.
• Subtitle: the line that tells two similar titles apart, like the city or the email. Optional.
• Meta: one value in the top corner that people scan the list for. A status badge or an amount, not both.
• Fields: two to four label and value pairs under the title. Pick the ones people use to decide whether to open the record.
• Hidden: everything else. Internal ids, created-at dates, columns that only exist for sorting on desktop.

For a client list with Name, Tax ID, City, Status, Balance, Last invoice, Owner and Created, that gives: Name as the title, City as the subtitle, Status as the meta, Balance, Last invoice and Owner as fields, and Tax ID and Created hidden. The record is still one tap away for the hidden columns.

Actions move into a "⋯" menu in the card's corner that opens as a bottom sheet. Inline icon buttons in a row are fine with a mouse; on a card they compete with the title for a 44px touch target.

How do you turn a shadcn table into cards on mobile?

Render the table and a list of cards from the same data, and let CSS pick one. Here is the full component on top of the stock shadcn/ui table (npx shadcn@latest add table), with a plain span for the status so it needs nothing else:

// components/clients-table.tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";

type Client = { id: string; name: string; city: string; status: "Active" | "Overdue"; balance: number; owner: string };

const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

function Status({ value }: { value: Client["status"] }) {
  const tone = value === "Overdue" ? "bg-destructive/10 text-destructive" : "bg-muted text-muted-foreground";
  return <span className={`shrink-0 rounded-full px-2 py-0.5 text-xs font-medium ${tone}`}>{value}</span>;
}

export function ClientsTable({ clients }: { clients: Client[] }) {
  return (
    <>
      {/* desktop and tablets: the real table */}
      <div className="hidden md:block">
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Client</TableHead>
              <TableHead>City</TableHead>
              <TableHead>Status</TableHead>
              <TableHead>Owner</TableHead>
              <TableHead className="text-right">Balance</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {clients.map((c) => (
              <TableRow key={c.id}>
                <TableCell className="font-medium">{c.name}</TableCell>
                <TableCell>{c.city}</TableCell>
                <TableCell>
                  <Status value={c.status} />
                </TableCell>
                <TableCell>{c.owner}</TableCell>
                <TableCell className="text-right tabular-nums">{usd.format(c.balance)}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>

      {/* phones: one card per row */}
      <ul aria-label="Clients" className="flex flex-col gap-2 md:hidden">
        {clients.map((c) => (
          <li key={c.id} className="rounded-2xl border p-4">
            <div className="flex items-start justify-between gap-3">
              <div className="min-w-0">
                <p className="font-semibold">{c.name}</p>
                <p className="truncate text-sm text-muted-foreground">{c.city}</p>
              </div>
              <Status value={c.status} />
            </div>
            <dl className="mt-3 grid grid-cols-2 gap-x-4 gap-y-2 text-sm">
              <div>
                <dt className="text-xs text-muted-foreground">Balance</dt>
                <dd className="tabular-nums">{usd.format(c.balance)}</dd>
              </div>
              <div>
                <dt className="text-xs text-muted-foreground">Owner</dt>
                <dd>{c.owner}</dd>
              </div>
            </dl>
          </li>
        ))}
      </ul>
    </>
  );
}

That is the whole table to cards on mobile pattern. Three details matter more than the styling.

The switch is a CSS breakpoint. hidden md:block and md:hidden are both in the server HTML, so a phone paints the cards on first load. If you switch with a useIsMobile() hook instead, the server renders the table (the hook is false there), the phone shows it, and the cards replace it after hydration. The use mobile hook guide covers why that happens and where a hook is still the right tool.

The cards are a real list. <ul> with an aria-label tells a screen reader how many records there are, and <dt> / <dd> pairs keep each value attached to its label. Hiding the table with display: none also removes it from the accessibility tree, so screen reader users on a phone get the same cards as everyone else, not a hidden table.

Both copies render, so the DOM holds every row twice. For 25 rows a page that is nothing. For hundreds, paginate or virtualize, or render the hidden layout lazily. Past 200 rows, the Wingo UI Data Table virtualizes the visible layout and renders only a first screen of 30 rows in the hidden one.

What about the CSS-only data-label trick?

The popular alternative keeps one <table>, sets display: block on rows and cells below a breakpoint, and prints each header through td::before { content: attr(data-label) }. It saves the second copy of the markup, but it has two costs. Changing display on table elements used to strip their table semantics: Adrian Roselli's long-running test post records that Safari dropped them for every display value until Safari 17 fixed it, and as of his October 2023 update display: contents is the one value that may still cause issues (Tables, CSS Display Properties, and ARIA). And a screen reader still announces a table with seven columns while the screen shows a stack of cards, with the labels living in CSS.

If you use it, test with VoiceOver on an iPhone and TalkBack on Android. If you cannot test, the two-layout version above is the safer default.

How do sorting and bulk actions work without headers?

They need their own controls, because the things people pressed on desktop are gone. Plan each one:

• Sort: a row of "Sort by" chips above the cards, one per sortable column, tap to cycle the direction. Or, with many sortable columns, a Sort button that opens a bottom sheet listing "Balance, descending", "Client, ascending" and so on.
• Filters: the same filter UI as desktop, opened in a bottom sheet instead of a popover.
• Selection: no checkbox column. Long press a card to start selecting (the way Gmail and Photos do it on Android), then each tap toggles a card, and a checkbox appears on every card while selection mode is on.
• Bulk actions: a bar that floats at the bottom of the screen while rows are selected, padded for the home indicator, instead of a toolbar band at the top that has scrolled away.
• Paging: Load more at the end of the list. Numbered pages with 32px page buttons are hard to hit and break the scroll flow.

Long press is invisible, so it cannot be the only way in. Keep the "⋯" menu visible on every card, and if selection matters, add a visible Select action to the toolbar or the row menu as well.

How do you get the same layout from Wingo UI?

Use the Table for small read-only tables and the Data Table for admin lists. Both make a React table mobile responsive without a second markup branch: they render the desktop table and the phone layout in the server HTML and switch at 768px with CSS, and both assign card roles from your columns: the first column is the title, the last numeric column (in the Data Table, the first badge column before that) is the meta, and the rest are fields until you say otherwise with mobile.

Here is an orders table with the roles spelled out:

// components/recent-orders.tsx
"use client";

import { Table, type TableColumn } from "@/components/ui/table";

type Order = { id: string; customer: string; city: string; placed: string; items: number; total: number };

const columns: TableColumn<Order>[] = [
  { key: "customer", header: "Customer", sortable: true, mobile: "title" },
  { key: "city", header: "City", mobile: "subtitle" },
  { key: "id", header: "Order", mobile: "hidden" },
  { key: "placed", header: "Placed", type: "date", sortable: true },
  { key: "items", header: "Items", type: "number" },
  { key: "total", header: "Total", type: "currency", sortable: true, mobile: "meta" },
];

export function RecentOrders({ orders }: { orders: Order[] }) {
  return <Table caption="Recent orders" columns={columns} data={orders} locale="en-US" onRowClick={(order) => console.log(order.id)} />;
}

On a phone each order is a card with the customer as the title, the city under it, the total in the corner, and Placed and Items as fields. The order number stays on desktop only. Columns past the fourth field move behind a "Show more" toggle on the card. Because customer, placed and total are sortable, a row of Sort by chips appears above the cards, and onRowClick makes each card a single button that keyboard users reach with Tab.

Live demo: Table. The original article embeds an interactive demo here (Below 768px each invoice line becomes a card with the amount in the corner and Sort by chips above; on a wide screen it is a regular table with sortable headers and a totals row). Try it live on wingo-ui.com or open the Table docs. Install: npx wingo-ui@latest add table

The demo is an invoice with five lines and totals. Narrow your window, or open the page on a phone, to see the cards and the separate totals card. For a receipt-like look, mobileLayout="stack" lists label and value lines without card chrome, and mobileLayout="scroll" keeps the table scrolling sideways with the first column pinned, for comparison grids.

How does the Data Table handle selection on a phone?

The way the previous section describes. With selectionMode="multiple", a long press of about 450ms selects a card, then taps add or remove cards, and the bulk actions you return from bulkActions float at the bottom. The sort button in the toolbar opens a bottom sheet of "Balance, descending" style options, filters and the row menu open as bottom sheets too, and mobilePagination="load-more" (the default) appends rows.

// components/clients.tsx
"use client";

import { Archive, Mail, Pencil } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

type Client = { id: string; name: string; city: string; status: string; balance: number; owner: string; taxId: string };

const col = createColumns<Client>();
const columns = col([
  col.accessor("name", { header: "Client" }),
  col.accessor("city", { header: "City", mobile: "subtitle", filter: "multi-select" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Active: { tone: "success" }, Overdue: { tone: "danger" } },
    filter: "multi-select",
  }),
  col.accessor("balance", { header: "Balance", type: "currency" }),
  col.accessor("owner", { header: "Owner" }),
  col.accessor("taxId", { header: "Tax ID", mobile: "hidden" }),
]);

export function Clients({ clients }: { clients: Client[] }) {
  return (
    <DataTable
      data={clients}
      columns={columns}
      caption="Clients"
      locale="en-US"
      selectionMode="multiple"
      bulkActions={(rows) => [
        { label: "Send email", icon: <Mail />, onSelect: () => console.log(rows.length) },
        { label: "Archive", icon: <Archive /> },
      ]}
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
    />
  );
}

Here the defaults do the rest: Client becomes the title because it is first, and Status becomes the meta because it is the first badge column. Balance and Owner are the fields. The Data Table shows at most four fields and drops the others from the card, so put the important ones first or mark the rest hidden on purpose.

Live demo: Data Table. The original article embeds an interactive demo here (On a phone, long press a client card to start selecting, then tap more cards: the bulk bar floats at the bottom. On a wide screen it is the full table). Try it live on wingo-ui.com or open the Data Table docs. Install: npx wingo-ui@latest add data-table

When the column mapping is not enough, both components take a renderCard function for a card of your own, and mobileLayout="scroll" opts a single table out of cards.

What if the rows are simpler than a table?

Then skip the table on every screen size. A list of team members, notifications or settings with a name, a line of detail and one value is a list, and the List gives it rows with an avatar or icon, a trailing value, a row menu, and swipe actions on touch (swipe left to archive or delete, with a long press sheet as the visible alternative). It reads well at 390px and at 1440px without a breakpoint.

How do you test a responsive table on mobile?

Check the one thing that breaks most: the page should never scroll sideways at phone width. A Playwright test catches it in CI:

// e2e/no-horizontal-scroll.spec.ts
import { test, expect } from "@playwright/test";

test.use({ viewport: { width: 390, height: 844 } });

test("the clients page fits a phone", async ({ page }) => {
  await page.goto("/clients");
  const overflow = await page.evaluate(() => document.documentElement.scrollWidth - window.innerWidth);
  expect(overflow).toBeLessThanOrEqual(0);
  await expect(page.getByRole("list", { name: "Clients" })).toBeVisible();
  await expect(page.getByRole("table")).toBeHidden();
});

Add a 360px case for small Android phones, and run it in light and dark. Then do one pass on a real phone: long press a card, open the row menu and the sort control, and check that the bulk bar clears the home indicator.

Where should you start?

Take your busiest admin table, give each column a role on paper, and build the card layout next to the table with md:hidden. If you would rather start from components that already do the mapping, the sort chips, the long press selection and the floating bulk bar, the Table and the Data Table are part of Wingo UI Pro; add one with npx wingo-ui@latest add data-table. For the step by step build of filters and server pagination on TanStack, read the TanStack Table v9 data table tutorial, and find more phone layouts in Mobile UI in React.

Components in this post

• Data Table (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: npx wingo-ui@latest add data-table
• Table (Pro): The library's one table look: semantic table parts plus a props API for small read-only tables that turn into cards on phones. Install: npx wingo-ui@latest add table
• List (Pro): Rows on a page for settings, contacts, inboxes and orders: iOS grouped panels, selection, row menus, swipe actions and drag to reorder. Install: npx wingo-ui@latest add list
• Description List (Pro): The key-value grid of every detail page: client details, invoice summaries and profiles, with copy buttons, skeletons and iOS rows. Install: npx wingo-ui@latest add description-list

FAQ

How do I make a table responsive on mobile?

Decide first whether people read records or compare columns. For records, render a card per row below 768px with the main field as the title and two to four labeled fields; for comparison grids, keep the table and let it scroll sideways inside its box with the first column pinned.

Is the shadcn table responsive on mobile?

It scrolls. The shadcn/ui Table wraps the table in a div with overflow-x-auto, so a wide table scrolls sideways inside its container. Turning rows into cards is up to you, usually with a second markup branch hidden and shown with md: classes.

Should I use display: block on table rows to make cards?

It works visually and keeps one copy of the markup, but changing display on table elements removed table semantics in Safari until Safari 17 (Adrian Roselli, October 2023), and display: contents can still cause problems. A separate list of cards with real dt and dd labels is easier to get right for screen readers.

How do users sort a table on a phone without column headers?

Give them a control that does what the headers did: a row of Sort by chips above the cards, or a Sort button that opens a bottom sheet listing each column ascending and descending.

Should I use useIsMobile to switch between the table and the cards?

No. A media query hook is false on the server, so phones render the table first and swap to cards after hydration. Render both and hide one with md:hidden and hidden md:block, which is correct in the first paint.

This article was originally published on the Wingo UI blog: Responsive Table Mobile Layout: Rows to Cards in React. The original has the live, interactive demos and is kept up to date.

A React bottom sheet for the web is a draggable dialog pinned to the bottom of the screen, so build it on a DOM dialog primitive: Base UI's Drawer (maintained) or vaul (unmaintained per its README, still the most complete option on Radix). Pass snap points as fractions from 0 to 1 in a stable array, let the body scroll only at the last point, raise the sheet above the on-screen keyboard with the visualViewport API, and pad the part that touches the bottom edge with env(safe-area-inset-bottom). The free Wingo UI Drawer does all of this on top of vaul 1.1.2.

Search for a React bottom sheet and many of the top results are React Native packages such as @gorhom/bottom-sheet, which reach the browser only through React Native Web. This guide is about the React bottom sheet web apps need: a real dialog in the DOM, pointer events, position: fixed, an on-screen keyboard that covers half the screen and a home indicator under your Save button. It covers the five parts that decide whether a sheet feels native on a phone (snap points, drag to dismiss, nested sheets, the keyboard and the safe area), with code for vaul and for the free Wingo UI Drawer, which is built on it.

Which React bottom sheet library works on the web?

For apps that render to the DOM, vaul and Base UI's Drawer are the two serious choices, because both sit on a dialog primitive: focus trapping, Escape and the accessible title come with them. As of October 2026, from the npm registry and each project's docs:

Three facts the table cannot show change the decision. Vaul's README says "This repo is unmaintained", and no release has shipped since December 2024; its peer range still includes React 19, and the Wingo UI Drawer runs on it with React 19.3. react-spring-bottom-sheet's peer range stops at React 18. react-modal-sheet's README says it "doesn't include any built-in accessibility properties", so focus trapping and dialog semantics are yours to add.

If your project already uses Base UI, the default for new shadcn/ui projects since July 2026, use its Drawer: it is maintained and covers snap points, nesting and the keyboard (Drawer.VirtualKeyboardProvider). On Radix, vaul is still the most complete option, and the rest of this guide is about the gaps you cover around it.

How do vaul drawer snap points work?

Vaul drawer snap points are stops on the way up, listed from least to most visible: a number is a fraction of the screen height (0.45 is 45%), a string is pixels ("320px"). The sheet renders at full height and is translated down to the active point. Three details trip people up in vaul 1.1.2:

1. Fractions from 0 to 1. The type comment says "Array of numbers from 0 to 100", but the code multiplies each number by the window height, so 50 means fifty screens. Write 0.5.
2. Pixels only. A string goes through parseInt, so "30rem" becomes 30 pixels.
3. Hoist the array. Vaul re-runs its snap effect whenever snapPoints changes identity, so an inline literal re-snaps the sheet on every parent render.

Then decide what scrolls. Below the last point the body should stay still, so an upward swipe drags the sheet instead of scrolling a list the user can only half see. fadeFromIndex picks the point where the overlay starts to dim; it defaults to the last one, so a half-open sheet leaves the page bright.

Make the React bottom sheet modal when it holds a task. Pass modal={false} when the page behind must stay usable, like a results list over a map:

"use client";

import { useState } from "react";
import { Drawer, type DrawerSnapPoint } from "@/components/ui/drawer";

// fractions of the screen height, least visible first; one array for the app's lifetime
const SNAP_POINTS: DrawerSnapPoint[] = [0.45, 1];

type Apartment = { id: string; title: string; rent: string };

export function MapResults({ apartments }: { apartments: Apartment[] }) {
  const [snap, setSnap] = useState<DrawerSnapPoint | null>(SNAP_POINTS[0]);
  return (
    <Drawer
      defaultOpen
      modal={false}
      dismissible={false}
      snapPoints={SNAP_POINTS}
      activeSnapPoint={snap}
      onActiveSnapPointChange={setSnap}
      title="Apartments in Chicago"
      description={`${apartments.length} results in the map area`}
    >
      <ul className="flex flex-col gap-3">
        {apartments.map((a) => (
          <li key={a.id} className="flex justify-between gap-3 text-[15px]">
            <span className="truncate">{a.title}</span>
            <span className="font-semibold tabular-nums">{a.rent}</span>
          </li>
        ))}
      </ul>
    </Drawer>
  );
}

With snap points, dismissible={false} stops the sheet at its first point, so the list can never be dragged away behind the map. The Drawer keeps one array per distinct list of points even when you pass a literal, lets the body scroll only at the last point, and steps to the next point on a tap on the handle.

How does drag to dismiss decide when to close?

By distance or speed, measured when the finger lifts. Without snap points, vaul closes the sheet when you let go past 25% of its height (closeThreshold, default 0.25) or flick it faster than 0.4 pixels per millisecond; anything less eases back over 500ms on cubic-bezier(0.32, 0.72, 0, 1). With snap points it settles on the nearest point, a flick moves one point in its direction, and a flick faster than 2 pixels per millisecond closes the sheet or opens it fully. The harder part is when a drag should not start at all. Vaul 1.1.2 refuses one:

• from inside a scrollable element that is not at its top, so a long list scrolls first;
• for a moment after the content scrolled (scrollLockTimeout: 100ms in the code, although the type comment says 500ms);
• while text is selected, from a native <select>, or from anything inside [data-vaul-no-drag];
• in the first 500ms after opening.

Left and right drawers skip the scroll and timing checks. For content with its own horizontal gestures (a carousel, a map, a range slider) set handleOnly, so only the handle drags. And give every drag a visible alternative: Escape, a tap on the dimmed page and a close button. The Wingo UI Drawer leaves the close button off bottom sheets by default, so pass showClose (panels and dialogs always have one).

The demo below is a listings page. Filters opens a sheet with price, condition and category filters and a pinned button with the result count.

Live demo: Drawer. The original article embeds an interactive demo here (Tap Filters, then drag the sheet down: let go past a quarter of its height or flick it and it closes, a shorter drag settles back. Scroll the categories first: the sheet only drags once the list is back at the top). Try it live on wingo-ui.com or open the Drawer docs. Install: npx wingo-ui@latest add drawer

How do you nest bottom sheets?

Open the second sheet from inside the first and push the first one back, like iOS. In vaul that is Drawer.NestedRoot, rendered inside the parent's Drawer.Content; it throws when it has no parent drawer, and as the child opens it shrinks the parent 16px narrower, lifts it 16px and follows the child's drag. It moves the parent only from its own onOpenChange, so a child opened by setting open from state leaves the parent flat.

The Wingo UI Drawer detects nesting from context. A drawer rendered inside another drawer's content uses the nested root on its own and pushes the parent for controlled opens too:

"use client";

import type { ReactNode } from "react";
import { Button } from "@/components/ui/button";
import { Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerFooter, DrawerHeader, DrawerRoot, DrawerTrigger } from "@/components/ui/drawer";

export function DeliveryAddress({ addresses, newAddressForm }: { addresses: ReactNode; newAddressForm: ReactNode }) {
  return (
    <DrawerRoot>
      <DrawerTrigger asChild>
        <Button variant="soft" size="sm">Change</Button>
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader title="Delivery address" description="Arrives in 1-2 business days" />
        <DrawerBody>
          {addresses}
          {/* inside the first sheet's content, so it nests and pushes the first one back */}
          <Drawer
            title="New address"
            trigger={<Button variant="ghost" fullWidth>Add a new address</Button>}
            footer={
              <DrawerClose asChild>
                <Button size="lg" fullWidth>Save address</Button>
              </DrawerClose>
            }
          >
            {newAddressForm}
          </Drawer>
        </DrawerBody>
        <DrawerFooter>
          <DrawerClose asChild>
            <Button size="lg" fullWidth>Deliver here</Button>
          </DrawerClose>
        </DrawerFooter>
      </DrawerContent>
    </DrawerRoot>
  );
}

Stop at two levels. On a 390px screen a third sheet is a page, so navigate to one.

What happens when the keyboard opens inside a bottom sheet?

The keyboard covers the sheet unless something moves it. On Safari for iOS, and on Chrome for Android since version 108, the keyboard resizes only the visual viewport (Chrome's announcement), so an element at position: fixed; bottom: 0 stays behind it. Vaul's repositionInputs, on by default, listens to visualViewport resize events: while a field has focus it raises the sheet by the height the keyboard covers and shrinks it when it no longer fits above the keyboard.

Two rules make that work in practice:

• Do not focus a field on open. The Wingo UI Drawer focuses the sheet itself, so the keyboard does not cover half the sheet before anyone has read it; Tab moves on to the first control. When typing is the whole task, such as renaming a list, pass onOpenAutoFocus, call event.preventDefault() and focus the field yourself.
• Use 16px text in inputs (text-base md:text-sm). iOS Safari zooms into a focused field with smaller text.

Turn repositionInputs off when the sheet handles the keyboard itself, for example a chat composer that follows the keyboard with the Pro useKeyboardInset hook.

How do you keep a bottom sheet clear of the home indicator?

Let the page reach the screen edges with viewport-fit=cover (in Next.js, viewportFit: "cover" in the root layout's viewport export), then pad the part of the sheet that touches the bottom edge with max(env(safe-area-inset-bottom), 16px). The max() keeps 16px of air on devices that report an inset of 0. Pad only the last part: the footer when there is one, otherwise the scrolling body, so its last row can scroll above the indicator. Cap the height at 92dvh so a strip of the page stays visible to tap. On a plain vaul drawer:

"use client";

import type { ReactNode } from "react";
import { Drawer } from "vaul";

type SheetProps = { trigger: ReactNode; title: string; children: ReactNode; actions: ReactNode };

export function BottomSheet({ trigger, title, children, actions }: SheetProps) {
  return (
    <Drawer.Root>
      <Drawer.Trigger asChild>{trigger}</Drawer.Trigger>
      <Drawer.Portal>
        <Drawer.Overlay className="fixed inset-0 z-40 bg-black/40" />
        <Drawer.Content
          aria-describedby={undefined}
          className="fixed inset-x-0 bottom-0 z-50 flex max-h-[92dvh] flex-col rounded-t-[28px] bg-popover outline-none"
        >
          <Drawer.Handle className="mt-2.5" />
          <Drawer.Title className="px-5 pt-3 pb-2 text-[17px] font-semibold">{title}</Drawer.Title>
          <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-5">{children}</div>
          {/* the part that touches the bottom edge pads the home indicator */}
          <div className="flex flex-col gap-2 px-5 pt-3 pb-[max(env(safe-area-inset-bottom),16px)]">{actions}</div>
        </Drawer.Content>
      </Drawer.Portal>
    </Drawer.Root>
  );
}

The Wingo UI Drawer pads whichever part comes last. Its variant="floating" instead sits 8px above the safe area with every corner rounded, the look the Action Sheet uses for its iOS variant. The same insets for tab bars, FABs and toasts are in our Tailwind safe area insets tutorial.

Which bottom sheet should you use for each job?

There is no single bottom sheet UI React apps should use for everything. Pick by the job:

The Action Sheet also works imperatively: mount an ActionSheetProvider once, take const actionSheet = useActionSheet() in a component, and in a click handler await actionSheet.show({ actions }) resolves with the chosen action's id, or null on Cancel or a dismiss. An action whose onSelect returns a promise keeps the sheet open with a spinner in its row; the sheet closes when the promise resolves, and the row shakes and stays ready to retry when it rejects.

Live demo: Action Sheet. The original article embeds an interactive demo here (Tap the ⋯ button on the listing: the iOS sheet floats above the home indicator with Cancel in its own card. Delete listing shows a spinner in its row until its promise resolves). Try it live on wingo-ui.com or open the Action Sheet docs. Install: npx wingo-ui@latest add action-sheet

The Family Drawer keeps one floating sheet and animates its height between views, which suits a short flow like a menu that leads to a confirmation.

Live demo: Family Drawer. The original article embeds an interactive demo here (Tap Try it out and pick an option: the floating sheet morphs to the height of the new view. Drag it down or tap outside to close it). Try it live on wingo-ui.com or open the Family Drawer docs. Install: npx wingo-ui@latest add family-drawer

In the registry (release 1.7.0), 39 other items import the Drawer, including the Popover, Select, Dropdown Menu and Dialog, which open as bottom sheets below 768px. Every sheet in an app drags, snaps and pads the same way.

What should you do next?

Install the free Drawer with npx wingo-ui@latest add drawer, open your app at 390px and drag a sheet closed with its list scrolled halfway. For the switch between a centered card and a sheet, read the shadcn responsive dialog tutorial; for touch targets, safe areas and the rest of the phone rules, the mobile-first React components guide and the Mobile UI in React category. The Action Sheet is part of Wingo UI Pro.

Components in this post

• Drawer (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: npx wingo-ui@latest add drawer
• Family Drawer (Free): A floating bottom drawer that morphs smoothly between stacked views, inspired by the Family app. Install: npx wingo-ui@latest add family-drawer
• Action Sheet (Pro): The iOS action sheet: a short list of actions about one thing, with a title, red destructive rows and a separate Cancel, plus await show(). Install: npx wingo-ui@latest add action-sheet
• Sheet (Free): A panel that slides in from any edge on a spring: filters, a cart, an inspector or the phone navigation menu, swipeable to close on touch. Install: npx wingo-ui@latest add sheet

FAQ

Can I use @gorhom/bottom-sheet in a React web app?

Only through React Native Web: it is a React Native library that needs Reanimated and Gesture Handler. In a Next.js or Vite app that renders to the DOM, use vaul or Base UI's Drawer, which are built on accessible dialog primitives.

Is vaul still maintained?

No. As of October 2026 its README says the repo is unmaintained, and the last release is 1.1.2 from December 14, 2024. It still declares React 19 support; Base UI's Drawer is the maintained alternative.

Why do my vaul snap points not work with values like 50?

Vaul multiplies each number by the screen height, so numbers must be fractions from 0 to 1 (0.5 for half the screen), even though a type comment says 0 to 100. Strings are read as pixels, so write "320px", never rem.

How do I stop a vaul drawer from dragging when I swipe a carousel inside it?

Set handleOnly so only the handle drags the sheet, or add the data-vaul-no-drag attribute to the carousel's root element. Vaul already ignores drags that start on a native select or while text is selected.

Is the Wingo UI Drawer free?

Yes. The Drawer, Family Drawer and Sheet are free and the Action Sheet is Pro. npx wingo-ui@latest add drawer copies the component into your project with the Button, hooks and helpers it imports.

This article was originally published on the Wingo UI blog: React Bottom Sheet for the Web: Snap Points, Drag, Keyboard. The original has the live, interactive demos and is kept up to date.

Run npx shadcn@latest mcp init --client claude to add the shadcn MCP server to .mcp.json, install the shadcn skill with npx skills add shadcn/ui, and list every extra registry in components.json. Then add a short block to CLAUDE.md that says which registry owns which folder and which CLI installs and updates it, and name the registry in every prompt. The server finds components, the skill and the rules steer Claude, and the CLI writes the files.

Claude Code already knows shadcn/ui from its training data, and that is the problem. It writes the API it remembers, which may not match the files in your components/ui, and it has never seen the registries you added to components.json last month. A Claude Code shadcn setup that holds up has five parts: the shadcn MCP server so Claude can search real registries, the shadcn skill for project context, the registry list in components.json, a short rules file that says which registry owns which folder, and a CLI that writes the files. This tutorial sets up all five, adds a second registry, and ends with prompts shaped to get the right component installed.

Everything below was run in October 2026 against shadcn 4.21.4, the skills CLI 1.7.1 and our own registry, Wingo UI 1.7.0. What we say about Claude Code itself comes from its docs as of the same month. For the wider picture, read our component library MCP guide first.

What does a Claude Code shadcn setup need?

A server that searches registries, instructions that say when to use it, a list of registries and a CLI that installs:

A library's own MCP server is an optional sixth piece: the shadcn server returned no props in our tests, and a library server can. Ours joins shadcn's in the same .mcp.json through npx wingo-ui@latest agents install claude.

How do I add the shadcn MCP server to Claude Code?

Run one command in the project root, restart Claude Code and check /mcp:

npx shadcn@latest mcp init --client claude

It writes this entry to .mcp.json, then installs shadcn as a dev dependency:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

.mcp.json is Claude Code's project scope: commit it and the team gets the server, after each person approves it once. For a setup only you use, claude mcp add shadcn -- npx shadcn@latest mcp adds it in local scope, the default, instead.

Which tools does the shadcn MCP server give Claude?

Once the Claude Code shadcn MCP connection is up, Claude gets seven read-only tools. This is the list the server returned in 4.21.4:

• get_project_registries: the registries in components.json.
• list_items_in_registries and search_items_in_registries: browse or fuzzy-search, with paging.
• view_items_in_registries: name, description, type, file count and npm dependencies.
• get_item_examples_from_registries: demo code, found by names like dialog-demo.
• get_add_command_for_items: the npx shadcn@latest add command for items.
• get_audit_checklist: a checklist for after generating code.

Three details shape how you prompt it. The server never writes files: it hands Claude an add command, and every install is a Bash call you can read first. The server sends no instructions, and Claude Code's tool search loads only tool names and server instructions when a session starts, so the skill and your rules file have to say when to use it. And view_items_in_registries returned neither props nor source for @shadcn/button or our dialog; examples exist only where a registry publishes -demo items, which shadcn/ui does and we do not yet. For a third-party item, Claude learns the API from the installed file or the library's own docs.

One bug in 4.21.4: search results print each add command as [object Promise]. get_add_command_for_items returns the real one, npx shadcn@latest add @shadcn/button @wingo-ui/dialog in our test.

How do I add a second registry, private or Pro?

Add it under registries in components.json. A public registry needs only its URL template:

{
  "registries": {
    "@wingo-ui": "https://wingo-ui.com/r/{name}.json"
  }
}

A shadcn private registry takes headers, with the secret in an environment variable:

{
  "registries": {
    "@wingo-ui": {
      "url": "https://wingo-ui.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${WINGO_UI_API_KEY}" }
    }
  }
}

The shadcn CLI reads that variable from the environment or from .env.local; we confirmed both. When the key is set, agents install writes our own MCP entry in .mcp.json with the same ${WINGO_UI_API_KEY}, and Claude Code expands it from the environment it started in. Export the key in your shell profile and both servers see it.

Use the header form only when the variable is set. Without it, every call that touches @wingo-ui fails with MISSING_ENV_VARS: a search across @shadcn and @wingo-ui returned only that error, with no shadcn results either. Free Wingo UI items need no key, so keep the plain URL until you have one.

Then one search covers both registries. This is the real answer to search_items_in_registries for "login" with a limit of 4, the broken add-command lines removed:

Found 173 items matching "login" in registries @shadcn, @wingo-ui:

Showing items 1-4 of 173:

- login-page (registry:block) - The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. [@wingo-ui]
- login-01 (registry:block) - A simple login form. [@shadcn]
- login-05 (registry:block) - A simple email-only login page. [@shadcn]
- login-02 (registry:block) - A two column login page with a cover image. [@shadcn]

173 matches for one word is fuzzy matching at work (@shadcn alone returned 7), so ask for a small limit.

What happens when two registries both write components/ui/button.tsx?

Neither CLI replaces the other's file silently, and either answer breaks something. shadcn/ui and many shadcn-style libraries install into components/ui with the same file names and different APIs. When we added our Dialog to a project that already had the shadcn button, our CLI reported a conflict on components/ui/button.tsx, kept the shadcn file and still wrote the dialog and drawer next to it; the shadcn CLI asks before it overwrites. Keeping the shadcn button breaks the type-check, because our dialog and drawer render their close buttons with radius="full", a prop shadcn's Button does not have. Replacing it breaks every variant="default", "secondary" or "destructive" in your app, because our Button variants are solid, soft, outline, ghost and link (destructive is tone="danger").

Give the second library its own folder. Our CLI reads its paths from wingo-ui.json, so after npx wingo-ui@latest init, change the ui alias and keep the rest:

{
  "aliases": {
    "ui": "@/components/wingo",
    "blocks": "@/components/blocks",
    "hooks": "@/hooks",
    "lib": "@/lib",
    "utils": "@/lib/utils"
  }
}

npx wingo-ui@latest add dialog then wrote button.tsx, drawer.tsx and dialog.tsx into components/wingo beside the untouched shadcn button and rewrote their imports to @/components/wingo/.... init had already merged our design tokens into app/globals.css, and add appended the drawer's transitions. That is the second reason to install our items with our CLI: the shadcn-format JSON at /r/<slug>.json carries no tokens, so in a project without them, z-modal and shadow-modal on a shadcn-installed dialog resolve to nothing.

Should I install the Claude Code shadcn skill too?

Yes, if your project uses shadcn/ui components; if it also uses another library, scope the skill in your rules file. The skill is the official instruction set from the shadcn/ui repository:

npx skills add shadcn/ui --agent claude-code

The skills CLI wrote two skills into .claude/skills, shadcn and migrate-radix-to-base, and recorded both in skills-lock.json. Claude Code keeps only a skill's description in context until the skill is used, so the 19.5 KB SKILL.md costs little until a UI task starts. Its description matches any project with a components.json, so expect it on most UI work.

When it loads, it runs npx shadcn@latest info --json and puts your framework, Tailwind version, aliases, base library and installed components in front of Claude. Its allowed-tools line also lets Claude run any npx shadcn@latest command without asking for the rest of that turn, add --overwrite included. Three of its rules matter before you prompt:

• Name the registry. Ask for "a login block" without one and the skill tells Claude to ask you which registry to use.
• Docs first. Claude runs npx shadcn@latest docs <component> before using one. That command only knows shadcn/ui: docs dialog returned links to the shadcn/ui and Radix Dialog docs, and docs @wingo-ui/dialog answered that the component was not found in the shadcn registry.
• shadcn/ui composition. Forms use FieldGroup and Field, icons in buttons take data-icon, and since shadcn's Button has no loading prop, Claude composes a Spinner and disabled by hand.

All three are right for shadcn/ui files, and the last two are wrong for other registries. Our Button has a loading prop that shows a spinner in place of the label, keeps the width, sets aria-busy and ignores clicks, so a hand-built spinner duplicates it. In the demo below, pressing "Save changes" swaps the label for a spinner and "Saving" while the button keeps its width.

Live demo: Button. The original article embeds an interactive demo here (Click Save changes: the spinner takes the label's place, the width holds and the button ignores clicks until it settles). Try it live on wingo-ui.com or open the Button docs. Install: npx wingo-ui@latest add button

What should CLAUDE.md say?

Who owns which folder, which tools to search with, which CLI installs and updates, and where the shadcn skill's rules stop. Claude Code loads CLAUDE.md at the start of every session, so this block is always in context:

## UI components

- Two registries. `components/ui` is shadcn/ui (`@shadcn` in components.json). `components/wingo` is Wingo UI (versions in wingo-ui.json); import it from `@/components/wingo/<name>`.
- Before writing UI, search: the `shadcn` MCP tools for @shadcn and other registries, the `wingo-ui` MCP tools for Wingo UI. Never hand-write a component a registry has.
- Install shadcn items with `npx shadcn@latest add @shadcn/<name>` and Wingo UI items with `npx wingo-ui@latest add <slug>`. Never install a Wingo UI item with the shadcn CLI.
- Read the API of the file you import. The shadcn skill's rules and `shadcn docs` apply to `components/ui` only; for Wingo UI items call `get_component` and configure them through their props.
- Semantic tokens only, no hex colors. Check 390px and 1440px wide, in light and dark.
- Never pass `--overwrite` without asking me. Before any update, show me the diff or the release notes.

The first line answers what no tool can: which folder belongs to whom. It matters twice in this layout, because our own skill, which agents install writes, assumes the default folder and tells Claude that imports use @/components/ui/<name>. The fourth line keeps shadcn/ui patterns out of files with a different API. The last repeats the skill's own --overwrite rule, because the skill's permission grant covers that flag. On shadcn/ui alone, keep the search, install and overwrite lines. If Codex or Cursor work in the same repository, put these lines in AGENTS.md and import it from CLAUDE.md; our AGENTS.md vs CLAUDE.md comparison explains which file each agent reads.

Allow the read-only tools in .claude/settings.json and leave installs on ask:

{
  "permissions": {
    "allow": [
      "mcp__shadcn",
      "mcp__wingo-ui",
      "Bash(npx shadcn@latest search *)",
      "Bash(npx shadcn@latest view *)",
      "Bash(npx wingo-ui@latest outdated)"
    ]
  }
}

Which prompts get Claude to install the right component?

The ones that name the registry, ask for a search before an install, and say what to check at the end. Five prompts built that way:

1. Find before you build. "Search @shadcn and @wingo-ui for a modal that becomes a bottom sheet on phones. List the candidates with their registry and install command, and install nothing yet." Naming both registries satisfies the skill's rule, and "install nothing yet" keeps the first step read-only.
2. Build on one component's real API. "Add the Wingo UI dialog and input with the Wingo CLI, read their props with get_component, then build a profile dialog in app/settings/profile-dialog.tsx with a name field, Cancel and Save, a loading state on Save and an error if saving fails." Naming the source of the API steers Claude away from the shadcn/ui Dialog it remembers.
3. Start screens from a block. "Build /login from the Wingo UI login-page block. Wire onSignIn and onVerifyCode to our /api/auth routes, hide the social providers, and list every on* handler you left on its simulated default." The Login Page ships simulated handlers so its demo works, and each one you do not pass stays simulated: without onVerifyCode, the code views accept 123456.
4. Ask for updates as a report. "Check my Wingo UI components and my shadcn/ui button for upstream changes. Show me the notes and the diff, and change nothing."
5. End with a check. "Run get_audit_checklist, then type-check and lint the files you touched." The checklist is six generic lines; the type-check is what catches a wrong prop, such as variant="destructive" on our Button.

For prompt 2, this is the file a good run ends with, on the real APIs of the Dialog, the Button and the Input. We type-checked it against release 1.7.0:

// app/settings/profile-dialog.tsx
"use client";

import { useState } from "react";
import { Pencil } from "lucide-react";
// next to shadcn/ui these imports read @/components/wingo/...
import { Button } from "@/components/ui/button";
import { Dialog, DialogClose } from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";

type ProfileDialogProps = {
  initialName: string;
  onSave: (name: string) => Promise<void>;
};

export function ProfileDialog({ initialName, onSave }: ProfileDialogProps) {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState(initialName);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState("");

  function changeOpen(next: boolean) {
    // start from the saved name every time it opens
    if (next) {
      setName(initialName);
      setError("");
    }
    setOpen(next);
  }

  async function save() {
    setSaving(true);
    setError("");
    try {
      await onSave(name.trim());
      setOpen(false);
    } catch {
      setError("Your name was not saved. Try again.");
    } finally {
      setSaving(false);
    }
  }

  return (
    <Dialog
      open={open}
      onOpenChange={changeOpen}
      trigger={
        <Button variant="soft" leftIcon={<Pencil />}>
          Edit profile
        </Button>
      }
      title="Edit profile"
      description="Your name appears on invoices and in comments."
      icon={<Pencil />}
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Cancel</Button>
          </DialogClose>
          <Button tone="brand" loading={saving} loadingText="Saving" onClick={save}>
            Save
          </Button>
        </>
      }
    >
      <Input
        label="Full name"
        name="name"
        autoComplete="name"
        value={name}
        onValueChange={setName}
        error={error}
      />
    </Dialog>
  );
}

There is no media query in that file. Below 768px the same Dialog opens as a bottom sheet you can drag down to close, with the actions stacked full width at 48px and the primary on top; our shadcn responsive dialog tutorial explains how that switch avoids a hydration flash. The demo below is a listing card for a city bike in Brooklyn at $420, and its Edit button opens the same kind of dialog.

Live demo: Dialog. The original article embeds an interactive demo here (Click Edit, change the price and press Save: the button shows its loading state, then the dialog closes; on a phone the same dialog opens as a bottom sheet). Try it live on wingo-ui.com or open the Dialog docs. Install: npx wingo-ui@latest add dialog

How do I keep the installed components up to date?

Ask Claude for a report, then decide. The two CLIs treat edited files differently, which is why the rules file sends each folder to its own tool.

For shadcn/ui files, npx shadcn@latest add button --diff shows your file against the registry, and --overwrite replaces it, edits included. The skill tells Claude to merge by hand when a file has local changes. Our guide to updating shadcn components without losing edits has a git script that runs a real 3-way merge instead.

For Wingo UI files, the CLI recorded each item's version and kept a pristine copy at install, so it merges for you:

npx wingo-ui@latest outdated        # installed items vs the latest release
npx wingo-ui@latest diff dialog     # your file vs upstream
npx wingo-ui@latest update dialog   # 3-way merge that keeps your edits

With our MCP server connected, check_updates returns the same list with release notes, so prompt 4 works inside the session.

Where should I start?

On shadcn/ui alone: add the MCP server, install the skill, write the three rules lines, and name @shadcn in every prompt. If you want a second registry built for phones, the Dialog, Button and Input from this post are free; npx wingo-ui@latest agents install claude adds our MCP server and skill next to shadcn's, and the MCP server docs cover the setup. The Login Page block is part of Wingo UI Pro, on the pricing page. More guides like this one live under Building UI with AI agents.

Components in this post

• Button (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: npx wingo-ui@latest add button
• Dialog (Free): The modal for focused tasks: a spring-scaled card on desktop that becomes a bottom sheet on phones, with nesting and a scrolling body. Install: npx wingo-ui@latest add dialog
• Login Page (Pro): The sign-in screen of Northwind CRM: password, email link or code, Google / Apple / Microsoft, two-step codes and the whole password recovery. Install: npx wingo-ui@latest add login-page
• Input (Free): The single-line text field: icons and addons inside the box, a clear button, a loading spinner, a counter and floating labels. Install: npx wingo-ui@latest add input

FAQ

How do I install the shadcn MCP server in Claude Code?

Run npx shadcn@latest mcp init --client claude in the project root. It writes a shadcn entry to .mcp.json and installs shadcn as a dev dependency; restart Claude Code and run /mcp to check that the server connected.

What is the difference between the shadcn skill and the shadcn MCP server?

The MCP server gives Claude tools to list, search and view registry items and to get their add commands. The skill adds no tools: it injects your project config from shadcn info --json and the shadcn/ui composition rules into the session when Claude works on UI.

Does the shadcn MCP server install components by itself?

No. As of shadcn 4.21.4 its seven tools are read-only: it returns the npx shadcn@latest add command and Claude runs it in the terminal. That Bash call normally asks for your approval, but during a turn where the shadcn skill is active, the skill's allowed-tools line lets it run without asking.

Why does a shadcn MCP search fail with MISSING_ENV_VARS?

A registry in components.json uses an environment variable in its headers that is not set. The shadcn CLI then fails the whole call, other registries included. Export the variable or put it in .env.local, or use the plain URL form for public registries.

Can I use shadcn/ui and another registry in the same project?

Yes, but many shadcn-style libraries install into components/ui with the same file names, starting with button.tsx. Give the second library its own folder (Wingo UI reads it from aliases.ui in wingo-ui.json) so neither CLI has to overwrite the other's files.

This article was originally published on the Wingo UI blog: Claude Code shadcn Setup: MCP Server, Skill and CLAUDE.md. The original has the live, interactive demos and is kept up to date.

The best shadcn alternative depends on which part of shadcn/ui you want to replace. To keep owning the source, pick coss ui (free, on Base UI), Magic UI or Aceternity UI for animated marketing pages, or Wingo UI for mobile-first app components; to install a package instead, pick Mantine, MUI, Chakra UI or HeroUI; for a design system of your own, start from Base UI or React Aria. Most of these libraries leave the phone layout to you, so check what each one does on a 390px screen before you switch.

Picking among shadcn alternatives usually starts with how each library installs and how it looks. The questions that decide a project come later: what happens to the files you copied when upstream fixes a bug, whether the select you ship opens as something usable on a 390px phone, and whether Claude Code or Cursor can look up real props instead of guessing them. This guide answers those questions for 14 libraries, with prices, licenses and features checked in October 2026 and linked to the pages we read.

We build Wingo UI, one of the paid options below, so read this as a vendor's view with sources. It covers open source shadcn alternatives and paid ones, and it says plainly where another library is the better pick. More head to head comparisons live under Comparisons and alternatives.

What is the best alternative to shadcn UI?

There is no single best alternative to shadcn UI, because shadcn/ui is three things at once: a way to distribute code (a CLI that copies source files into your project), a set of primitives underneath (Base UI, Radix or React Aria), and a visual style. Decide which of the three you want to replace and the shortlist gets short:

• Keep the model, change the components. coss ui for free MIT components on Base UI, Magic UI or Aceternity UI for animated landing pages, Untitled UI React for a kit that matches the Untitled UI Figma file, Wingo UI for mobile-first app components with an MCP server and updates that merge into files you edited.
• Leave the model, install a package. Mantine for a free set with forms, dates and charts, MUI when you need the MUI X data grid and pickers, Chakra UI for style props, HeroUI for React Aria and Tailwind CSS v4 in an npm package, Ant Design for dense enterprise back offices.
• Keep the primitives, drop the look. Base UI, React Aria Components or Radix Primitives, styled by you.
• Step outside React. daisyUI, which is a set of Tailwind CSS class names that works with any framework.

If none of those reasons applies to you, the best option may be staying where you are, which the section near the end covers.

What changed in shadcn/ui in 2026?

The biggest change: since July 2026, new shadcn/ui projects start on Base UI instead of Radix. The July 2026 changelog entry made Base UI the default for npx shadcn init and for the docs, kept Radix fully supported behind npx shadcn init -b radix, and noted that projects created on shadcn/create were already picking Base UI over Radix 2 to 1. The same month, React Aria became a third base (--base aria).

Other changes that matter when you compare:

• The Drawer in Base UI projects now uses Base UI's drawer instead of Vaul. The Radix version still uses Vaul.
• June 2026 added components for chat interfaces, July 2026 a Toast built on Base UI, and September 2026 moved cn into its own package, so components import it from cn instead of @/lib/utils. What the new Toast means next to Sonner is in our Sonner alternatives comparison.
• On the agent side there is an MCP server that browses, searches and installs from every registry in components.json, and a skill (npx skills add shadcn/ui) that reads your project configuration before the agent writes code.

Two consequences follow. A "Radix plus Tailwind" description of shadcn/ui is out of date, and a registry written for Radix needs care in a new Base UI project. And the copy-the-source model has become a platform: registries from other vendors install through the same shadcn add command, so trying an alternative no longer means learning a new tool.

How do the shadcn alternatives compare?

The tables below are the short answer, checked in October 2026. "Mobile" lists only what each library's docs show for phones beyond responsive layout, and "Agents" what a coding agent can use. Prices are list prices on the day we checked; several vendors showed a discount from a higher price.

Libraries that put the source in your project

Packages and primitives

Two libraries are missing from the tables on purpose. Radix Primitives is still maintained and still the base of many registries, ours included; it appears in the section on headless primitives. Tailwind Plus, from the Tailwind CSS team, sells its components, templates and the Catalyst UI kit as a one-time purchase with lifetime access, but its product page sent us to a sign-in form when we checked, so we left it out rather than print prices we could not see.

Which alternatives keep the shadcn model?

coss ui, Magic UI, Aceternity UI, Untitled UI React and Wingo UI all put the source in your repository, and all but Untitled UI install through the shadcn CLI. They differ in what they cover and in what happens after the copy.

coss ui is the closest thing to shadcn/ui with a different design. Its registry components are MIT licensed, built on Base UI from the start, cover the app basics from Accordion and Dialog to Toast and Tooltip, and come with a migration guide from shadcn/ui and Radix. Its repository also keeps Origin UI, the Radix-based registry coss ui grew out of, as a legacy snapshot with limited support. If you liked shadcn/ui and want more components on the new default base for free, start here.

Magic UI and Aceternity UI are effect libraries for marketing pages: animated backgrounds, marquees, hero sections and full landing templates. They sit next to shadcn/ui more than they replace it, since neither covers the forms, menus and overlays an app needs. Magic UI's free components are MIT; Aceternity uses its own license, which says you cannot redistribute the source files, so read it before you publish them in a public repository.

Untitled UI React is the code side of the Untitled UI Figma kit, installed with its own CLI (npx untitledui@latest add) or from npm. The free base is MIT; the PRO tier is a one-time purchase per seat tier and adds hundreds of components, dashboards and page examples, drawers, modals and command menus included. It is a natural pick when your designers already work from the Untitled UI Figma file.

Wingo UI is ours. Release 1.7.0 has 326 items: 218 components, 72 blocks and page templates, 17 hooks and 19 helpers, of which 75 are free. Every component is built for apps people open on phones, as the mobile section below shows. Every visual aspect is a prop with a default, and the CLI merges new releases into files you have edited. The weak spots: it is younger and has a much smaller community than shadcn/ui, it is React only, it is built on Radix (so a Base UI project would carry two primitive libraries), and most items need a paid plan.

Which alternatives ship as an npm package?

Mantine, MUI, Chakra UI, HeroUI and Ant Design. You upgrade with npm update instead of merging files, and you customize through the library's theme and style APIs instead of editing the component source. That trade is right for many teams: someone else fixes the focus trap in the date picker, and you never see the file.

Mantine 9 is free and MIT across the board: components, hooks, a form library, dates and charts. It does not use Tailwind CSS; its own FAQ has a page on the limits of mixing in third-party styling. Its AI guide documents llms.txt, skills and an MCP server whose get_item_props tool returns a component's props or a hook's signature.

MUI is where you go for heavy data screens. The core Material UI library is MIT and free; the MUI X Data Grid, date range pickers, charts and tree view add advanced features in paid plans, listed at $299 (Pro) and $599 (Premium) per developer per year in October 2026. The default look is Material Design, which is a feature or a problem depending on your product.

Chakra UI 3 rebuilt the library on Ark UI and kept its style props. Its responsive object syntax reaches component props too: the Drawer docs show placement={{ mdDown: "bottom", md: "end" }}, which opens a bottom drawer on phones and a side panel from md. Chakra UI Pro sells blocks on top, from $299 one-time.

HeroUI 3 is the closest npm package to the shadcn stack: React Aria Components underneath, Tailwind CSS v4 for styling, MIT. Its Modal placement defaults to auto, which sits at the bottom of the screen below the sm breakpoint and centered above it, and its button styles make the default size 40px tall on phones and 36px from md up. A separate HeroUI Native library covers React Native, and a paid HeroUI Pro adds components such as a command palette and a data grid.

Ant Design 6 is built for enterprise back offices: dense tables, forms and admin layouts. Phones get a separate library, antd-mobile, so an app that serves both maintains two sets of components.

Should you use headless primitives instead?

Only if you are building your own design system and can own every style, state and animation. Headless libraries give you behavior and accessibility; everything you see is your code.

• Base UI reached v1.0.0 on December 11, 2025 and is now the default base under shadcn/ui. Its Drawer handles swipe to dismiss, the job shadcn/ui used Vaul for.
• React Aria Components from Adobe has the most thorough interaction layer we know of. usePress handles mouse, touch, keyboard and screen readers through one API, and useHover ignores the emulated mouse events that touch devices fire, which is the cause of hover styles that stick after a tap.
• Radix Primitives is still maintained and still under most of the shadcn ecosystem, including Wingo UI.

Picking a headless library also picks the base for everything you add later, since a registry built for one base may not drop cleanly into another.

Which shadcn alternatives work best on mobile?

Most of them leave the phone to you. They give you a drawer and a media query hook, and you wire the swap from popover or dialog to sheet one component at a time. Sorted by how much of that work the library does, from least to most:

1. Responsive CSS only. Magic UI and Aceternity UI (effects for landing pages) and Ant Design (a separate mobile library).
2. A recipe you copy per component. shadcn/ui, MUI and Mantine document a pattern that reads a media query and renders a different component or a full-screen variant.
3. A placement that changes by breakpoint. Chakra UI's drawer placement, daisyUI's modal-bottom sm:modal-middle and HeroUI's auto placement move the panel to the bottom of the screen on phones. Whether you can drag it away depends on the component.
4. Built into each component. Konsta UI, for mobile-only apps with an iOS or Material look, and Wingo UI, where the Popover, Select, Dropdown Menu, Dialog and date pickers open as draggable bottom sheets below 768px through a responsive prop that defaults to true.

Level 2 looks like this. It is an abridged copy of the responsive example in the shadcn/ui Drawer docs, where the form is shared as its own component and the overlay shell is written twice:

const isDesktop = useMediaQuery("(min-width: 768px)");

if (isDesktop) {
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      {/* trigger, header and <ProfileForm /> */}
    </Dialog>
  );
}

return (
  <Drawer open={open} onOpenChange={setOpen}>
    {/* the same trigger and header again, then <ProfileForm /> */}
  </Drawer>
);

That is fine for one dialog. It becomes a project when every popover, select, dropdown and date picker needs the same treatment, each with its shell written twice and each reading a hook that returns false on the server. Our mobile-first React components guide covers why that hook value is harmless for overlays and harmful for content, along with the other rules for phones.

The level 4 version of the same idea is one component. The free Drawer is a draggable bottom sheet on phones, and its desktop prop decides what it becomes from 768px: the same sheet ("sheet", the default), a side panel ("side") or a centered dialog ("dialog").

"use client";

import { SlidersHorizontal } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Drawer, DrawerClose } from "@/components/ui/drawer";

export function ListingFilters({ results }: { results: number }) {
  return (
    <Drawer
      trigger={
        <Button variant="soft" leftIcon={<SlidersHorizontal />}>
          Filters
        </Button>
      }
      title="Filters"
      description="New York · 1,240 listings"
      desktop="dialog"
      closeLabel="Close filters"
      footer={
        <DrawerClose asChild>
          <Button size="lg" fullWidth>
            Show {results} results
          </Button>
        </DrawerClose>
      }
    >
      <p className="text-sm text-muted-foreground">Price, condition and categories</p>
    </Drawer>
  );
}

Live demo: Drawer. The original article embeds an interactive demo here (Tap Filters: on a phone the sheet slides up and you can drag it down to close; on a wide screen the same component opens a centered dialog). Try it live on wingo-ui.com or open the Drawer docs. Install: npx wingo-ui@latest add drawer

On a phone the sheet has a drag handle and no close button; in the desktop dialog a close button appears in the corner, and closeLabel is its accessible name.

Touch targets follow the same split. HeroUI v3 makes its buttons taller below md, as noted above. Wingo UI's Button grows its medium size from 40px to 44px on coarse pointers and gives the small size a 44px hit area without changing how it looks. For the phone question alone, our best React component library for mobile comparison checks nine libraries at 390px, Ionic React and antd-mobile included, on sheets, touch targets, safe areas and gestures.

Which shadcn alternatives work best with coding agents?

In October 2026 most of them have an MCP server, so the useful question is what the server can do. We see three kinds:

• Documentation servers answer questions about components, props and examples, and npm still installs the package. MUI, Mantine (search_docs, get_item_props, get_api), Chakra UI (list_components, get_component_props, get_theme), Ant Design (eight tools behind antd mcp, antd_changelog among them), React Aria and HeroUI work this way.
• Install servers find items and put their source into your project. The shadcn MCP server does it through the shadcn CLI for any registry in components.json, and Untitled UI's server can browse, search and install its components. Magic UI's gives the agent direct access to its components.
• Servers that also check for updates. Ours answers searches and returns props with defaults, the design rules and the theme tokens without an account, and sends the source to an API key (a free account for free items, Pro for the rest). Its check_updates tool compares the versions in your wingo-ui.json with the latest release, so the agent hears about fixes before it edits a file that has one waiting.

Setting each one up takes one line:

# documentation servers: the agent reads props and examples, npm installs the package
claude mcp add mantine -- npx -y @mantine/mcp-server
claude mcp add chakra-ui -- npx -y @chakra-ui/react-mcp

# an install server for every registry in components.json
npx shadcn@latest mcp init --client claude

# the Wingo UI MCP server plus a rules file for the agent
npx wingo-ui@latest agents install claude

The server matters more for libraries whose source you own. With a package, an agent that guesses a prop gets a type error. With copied source, the agent can edit the component itself, so it needs the real API and the rules behind it. Our guide to component library MCP servers covers the tools, the rules file and the setup for Claude Code, Cursor and Codex. If you are choosing between a hosted generator and an agent in your repository, our v0 vs Claude Code comparison weighs code ownership, design consistency and cost across sign-in, pricing and settings screens.

How do you update components you copied?

With a package, you run npm update and read the changelog. With copied source, the merge is yours, and libraries differ in how much they help.

The shadcn CLI can preview: npx shadcn@latest add dialog --dry-run lists what would change and --diff shows the difference for a file. Bringing an upstream fix into a file you have edited is then a manual merge, or a job for your agent with the shadcn skill loaded. Every registry you install through the shadcn CLI behaves the same way. Our guide to updating shadcn components without losing edits turns that manual merge into a git 3-way merge.

Wingo UI's CLI records the version of everything it installs in wingo-ui.json and keeps the installed copy in .wingo-ui/base/, which lets it run a three-way merge, the same idea as git merge:

npx wingo-ui@latest outdated              # installed vs latest, and which files you edited
npx wingo-ui@latest diff drawer --base    # what you changed since installing
npx wingo-ui@latest update drawer         # untouched files are replaced, your edits are kept

When upstream and you changed the same lines, the file gets conflict markers and you choose, or you settle every conflict with --theirs or --ours. The updates docs cover the details. One caveat: files you install through the shadcn CLI from our registry carry no version record, so wingo-ui update cannot merge into them later.

Which shadcn alternatives include a data table?

MUI, Ant Design and Wingo UI ship a full data table; shadcn/ui gives you a guide instead. Its Data Table page explains that one data table component would lose the flexibility of headless UI, so it walks you through building your own on the Table component and TanStack Table v9. That is a good fit if your tables are all different. If you need the same admin table on twenty screens, the guide becomes code you maintain. Our TanStack Table v9 data table tutorial builds that code with filters, bulk actions and server pagination, and compares it with the ready-made tables.

The alternatives split three ways. MUI's X Data Grid has a free MIT version and adds its advanced features in the paid plans. Ant Design's Table has sorting, filters and pagination built in, and the other packages give you a styled table to build on. Wingo UI's Data Table is a Pro component on TanStack Table v9 with search, filters, sorting, bulk actions, pinning, resizing and virtualization, and below 768px each row becomes a card instead of a table that scrolls sideways:

"use client";

import { DataTable, createColumns } from "@/components/ui/data-table";

type Order = { id: string; customer: string; city: string; status: string; total: number };

const col = createColumns<Order>();
const columns = col([
  col.accessor("customer", { header: "Customer", filter: "text", mobile: "title" }),
  col.accessor("city", { header: "City", filter: "multi-select", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Refunded: { tone: "warning" }, Failed: { tone: "danger" } },
    filter: "multi-select",
  }),
  col.accessor("total", { header: "Total", type: "currency", footer: "sum" }),
]);

export function Orders({ orders }: { orders: Order[] }) {
  return (
    <DataTable
      data={orders}
      columns={columns}
      caption="Orders"
      locale="en-US"
      selectionMode="multiple"
      searchPlaceholder="Search orders"
      mobileLayout="cards"
    />
  );
}

Live demo: Data Table. The original article embeds an interactive demo here (Search for a client, toggle the Overdue chip, then sort or filter from the toolbar; on a phone each row becomes a card with a Load more button). Try it live on wingo-ui.com or open the Data Table docs. Install: npx wingo-ui@latest add data-table

The mobile key on a column decides where its value goes on the phone card: "title", "subtitle", "meta", "field" or "hidden". Rows need a unique id (or pass getRowId), because selection uses it. Switch mobileLayout to "scroll" when a table has to stay a table.

Which shadcn UI alternative for React fits your project?

Match the library to the job. These are our picks, including the many cases where the answer is not ours:

• Enterprise admin with heavy grids and date ranges: MUI with MUI X, the deepest set of data components in this list.
• Internal tools with complex forms, without Tailwind: Mantine. Free, MIT, with forms and dates built in.
• A design system of your own: Base UI or React Aria Components. React Aria if touch and screen reader behavior has to be exact.
• A free shadcn alternative on the new default base: coss ui.
• An npm package with the shadcn look and stack: HeroUI 3.
• Animated marketing pages: Magic UI or Aceternity UI, next to whatever you use for the app.
• Server-rendered pages with little JavaScript, or a stack beyond React: daisyUI.
• A mobile-only web app, or one wrapped in Capacitor, with a native iOS or Material look: Konsta UI.
• A product that people use on phones and desktops, built with coding agents, where you own the source and still want updates: Wingo UI.

When should you stay on shadcn/ui?

Stay when your app is used mostly on desktops, your team is happy to write its own responsive wrappers, and the biggest ecosystem matters more to you than any one feature. shadcn/ui is free and MIT licensed, its GitHub repository had about 125,000 stars on October 8, 2026, it supports three bases, and its CLI installs from a whole directory of community registries. Switching has a cost: every call site that uses a component's API changes, and a new library brings its own conventions for tokens, sizes and states.

You also do not have to choose. Because registries share one CLI, the realistic path for most teams is shadcn/ui as the base plus one or two registries for what it lacks.

How do you switch without a rewrite?

Replace one component at a time, starting with the ones that hurt most, and keep both libraries in the project while you do.

Three practical points for a move from shadcn/ui to Wingo UI, most of which apply to any registry:

1. File names collide. Both libraries write components/ui/button.tsx, dialog.tsx and drawer.tsx. Our CLI keeps an existing file that differs and tells you to rerun with --overwrite, so commit first and swap deliberately.
2. Call sites change. shadcn/ui's Button uses variant="destructive" and variant="secondary"; ours separates the role from the color, so those become tone="danger" and variant="soft".
3. Pick the right CLI for a Base UI project. Free items install from their URL with npx shadcn@latest add https://wingo-ui.com/r/button.json, and Pro items through the @wingo-ui registry in components.json. But shadcn projects created with a Base UI style rewrite asChild, which our components rely on, so in those projects use npx wingo-ui@latest add instead, as the installation docs explain.

To keep the new components close to your current look while you migrate, set app-wide defaults once instead of passing props everywhere. Our Button and Input default to radius="md", which gives the medium size 10px corners; if your current controls use 8px, "sm" matches them:

import { UIProvider } from "@/lib/ui-config";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider defaults={{ button: { radius: "sm" }, input: { radius: "sm" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}

UIProvider is a client component, so the root layout can stay a server component. Explicit props still win over these defaults, and the defaults win over the component's own. The Button below runs with the soft variant and a full radius set through props, so you can compare it with your current buttons in both themes.

Live demo: Button. The original article embeds an interactive demo here (Press the button: it dips on a quick spring and settles back; Tab to it for the focus ring, then switch the theme to compare light and dark). Try it live on wingo-ui.com or open the Button docs. Install: npx wingo-ui@latest add button

Where should you start?

Pick the one component that hurts most on a phone and try an alternative for that component alone. If it is an overlay, install the free Drawer with npx wingo-ui@latest add drawer (no account needed; it brings the Button and the media query hook along), put it behind one trigger people use on phones, and open it on your own device. The Data Table and the rest of the catalog are part of Wingo UI Pro, and the MCP server answers questions about every item without an account, so your agent can read the props before you decide.

Components in this post

• Button (Free): The button every screen starts with: five variants, six tones, three sizes plus icon sizes, and a loading state that never jumps. Install: npx wingo-ui@latest add button
• Drawer (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: npx wingo-ui@latest add drawer
• Data Table (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: npx wingo-ui@latest add data-table

FAQ

What is the best free alternative to shadcn/ui?

If you want to keep owning the source, coss ui is the closest match: MIT licensed, built on Base UI and installed through the shadcn CLI. If you would rather install a package, Mantine is MIT licensed, free and covers forms, dates and charts as well as the basic components.

Is shadcn/ui still built on Radix?

Not by default. Since July 2026, npx shadcn init starts new projects on Base UI, Radix stays fully supported with the -b radix flag, and React Aria is available as a third base with --base aria.

Which shadcn alternative works best on mobile?

Konsta UI if you want an iOS or Material look for a mobile-only web app, and Wingo UI if the same app runs on desktops and phones, because its popover, select, menus and dialog open as draggable bottom sheets below 768px by default. HeroUI, Chakra UI and daisyUI can move a modal or drawer to the bottom of the screen on phones; shadcn/ui, MUI and Mantine document a recipe you wire per component.

Can I use a shadcn alternative alongside shadcn/ui?

Yes. Registries such as coss ui, Magic UI, Aceternity UI and Wingo UI install through the same shadcn add command, so you can replace one component at a time. Watch for files with the same name, such as components/ui/button.tsx, and commit before each swap.

Do shadcn alternatives work with Claude Code and Cursor?

Most do. As of October 2026 shadcn/ui, MUI, Mantine, Chakra UI, HeroUI, Ant Design, React Aria, Magic UI, Untitled UI and Wingo UI publish MCP servers, and nearly all publish llms.txt. The servers differ: some answer documentation questions, some install source files, and Wingo UI's also checks your installed versions for updates.

This article was originally published on the Wingo UI blog: 14 shadcn Alternatives in 2026: Price, Mobile and MCP. The original has the live, interactive demos and is kept up to date.

Mobile-first React components are designed for a thumb on a 390px screen first and enhanced for a mouse after. The nine rules: open popovers, selects, menus and dialogs as bottom sheets below 768px; make targets 44px on coarse pointers; never hide a control behind hover; pad fixed bars with the safe-area insets; size full-height layouts in dvh, not vh; keep bottom bars out of the on-screen keyboard; turn table rows into cards; give every gesture a visible alternative; and switch layout with CSS breakpoints. Keep media query hooks for behavior only, because the server does not know the screen width.

Open a typical React app on a phone and the cracks show in the same places: a dropdown menu hanging off the edge of the screen, a 32px icon button you have to aim for, a checkout bar hidden behind the home indicator, a data table you scroll sideways to read one row. Mobile-first React components fix those problems once, inside the component, so every screen that uses them gets them right without a media query in the page. This is the rulebook we follow in Wingo UI, with the reason and the code for each rule. We build Wingo UI, so we are not neutral; outside facts link to their sources and are dated.

What makes a React component mobile-first?

A mobile-first component is designed for a thumb on a 360 to 390px screen with an on-screen keyboard, and then enhanced for a mouse and a wide window. Beyond reflowing its layout, the component changes how it behaves: which overlay it opens, how big its hit area is, what replaces hover, and where it sits relative to the notch and the keyboard.

The nine rules in one table, then a section for each:

If you are building a React mobile first UI from scratch, apply each rule in every component before adding the next one: people learn an interface from its most common pattern.

Why should a popover become a bottom sheet on a phone?

A popover anchored to a small trigger has nowhere good to go on a 390px screen, while a bottom sheet opens where the thumb already is. The finger that tapped the trigger covers it, the panel gets clipped or flipped above the trigger, and a tap that lands just outside it closes it. A sheet takes the full width, has room for 48px rows, can be dragged away, and keeps its actions in the bottom part of the screen, the part a thumb reaches without changing grip.

We render a bottom sheet below 768px for the popover, select, dropdown menu, context menu and dialog, by default. The exceptions matter as much as the rule:

• Tooltips never become sheets. Nothing hovers on a touch screen, so the text goes inline or behind a long press.
• Alert dialogs stay centered at every width. A short question that must be answered reads like an iOS alert.
• Suggestions under a text field stay attached to it, because a sheet would cover what you type, as in the Mention Input. The Combobox takes the other route: a full-height sheet with its own search box.

In Wingo UI the switch is a responsive prop that defaults to true on the Popover, Select, Dropdown Menu, Dialog and the date pickers. You write the component once:

"use client";

import { ChevronDown } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Popover, PopoverClose } from "@/components/ui/popover";

export function PriceFilter({ onApply }: { onApply: () => void }) {
  return (
    <Popover
      trigger={
        <Button variant="soft" rightIcon={<ChevronDown />}>
          Price
        </Button>
      }
      title="Price"
      description="Pick a range or type your own."
      footer={
        <PopoverClose asChild>
          <Button size="sm" onClick={onApply}>
            Apply
          </Button>
        </PopoverClose>
      }
    >
      <p className="text-muted-foreground">Between $500 and $1,500</p>
    </Popover>
  );
}

On a desktop that is a floating panel with a right-aligned Apply button. Below 768px the same JSX opens a bottom sheet with a handle and a full-width 48px Apply button. Pass responsive={false} when a panel has to stay anchored to a field.

The sheet underneath is the free Drawer, built on vaul. It follows your finger, closes when you let go past a quarter of its height or flick it, stops at snap points, and lets a long list scroll first and drag the sheet only once the list is back at the top. Opening it moves focus to the sheet itself instead of the first field, so the keyboard does not jump up over half the content. From 768px it stays a centered sheet, or becomes a side panel or a dialog, depending on the desktop prop.

Live demo: Drawer. The original article embeds an interactive demo here (Tap Filters: on a phone the sheet slides up and you can drag it down to close; on a wide screen this one opens as a side panel). Try it live on wingo-ui.com or open the Drawer docs. Install: npx wingo-ui@latest add drawer

The demo is a listings page: Filters opens a draggable bottom sheet below 768px and a panel from the right edge on wider screens, with the result count on a pinned button in both.

Two posts go deeper on this rule. The React bottom sheet guide covers snap points, drag to dismiss, nested sheets and the keyboard, and the shadcn responsive dialog tutorial builds the same card-to-sheet switch on stock shadcn/ui.

How do you switch between a sheet and a dialog without a hydration flash?

Use CSS breakpoints for anything visible on the first paint, and a media query hook only for behavior that starts after an interaction, such as which overlay opens. The server has no screen, so any hook that reads matchMedia has to return a guess during server rendering and hydration. When that guess drives visible layout, phones see the desktop layout first and then a jump.

The use-mobile hook that ships with shadcn/ui's sidebar starts as undefined, returns false, and flips in an effect (as of October 2026). Our free useMediaQuery uses the same 768px breakpoint, reads it through useSyncExternalStore and makes the server value a parameter. This is the core of it:

import { useCallback, useSyncExternalStore } from "react";

export function useMediaQuery(query: string, serverFallback = false) {
  const subscribe = useCallback(
    (onChange: () => void) => {
      const list = window.matchMedia(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query],
  );
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    // the server and the hydration render
    () => serverFallback,
  );
}

export const useIsMobile = () => useMediaQuery("(max-width: 767.98px)");

Both hooks say false on the server. That is harmless for overlays, because an overlay is closed during server rendering: by the time someone taps the trigger, the hook holds the real value. It is harmful for content:

// wrong: the server renders the table, phones swap to cards after hydration
const isMobile = useIsMobile();
return isMobile ? <InvoiceCards rows={rows} /> : <InvoiceTable rows={rows} />;

// right: both are in the HTML and CSS picks one before the first paint
return (
  <>
    <InvoiceTable rows={rows} className="hidden md:table" />
    <InvoiceCards rows={rows} className="md:hidden" />
  </>
);

This is the part of mobile first design React apps get wrong without noticing, because the wrong version looks fine when you drag a desktop window narrow after the page has loaded. The jump only shows when a phone loads the server-rendered page. Our guide to an SSR-safe React use mobile hook tests three common versions of the hook through hydration and sorts which jobs belong to CSS.

How big should touch targets be?

Make every target 44 by 44 CSS pixels on touch screens and keep at least 8px between neighbors. The standards disagree on the exact number; 44px meets the strictest web criterion (WCAG level AAA) and Apple's default control size:

The catch is the desktop. A 44px button everywhere makes a toolbar or a settings page look bloated next to a mouse pointer. Tailwind CSS v4 has a pointer-coarse variant that compiles to @media (pointer: coarse), so the size can follow the input device instead of the screen width. A tablet and a phone both get the bigger targets; a laptop with a trackpad does not.

For a text button the size is h-10 pointer-coarse:h-11: 40px with a mouse, 44px under a finger. An icon button that must stay small gets an invisible hit area instead:

import { Ellipsis } from "lucide-react";

// looks 32px, takes 44px taps on touch
export function MoreButton() {
  return (
    <button
      type="button"
      aria-label="More actions"
      className="relative grid size-8 touch-manipulation place-items-center [-webkit-tap-highlight-color:transparent] pointer-coarse:after:absolute pointer-coarse:after:-inset-1.5"
    >
      <Ellipsis className="size-4" />
    </button>
  );
}

The ::after trick adds 6px on every side of the 32px button without moving anything. touch-manipulation turns off double-tap zoom on the control, so taps register without the browser waiting for a second one, and the transparent tap highlight removes the gray box mobile browsers paint on a tapped element. Both live on the component itself, because a component copied into another project does not bring your global stylesheet along. The Button in Wingo UI is built this way: md is 40px with a mouse and 44px on touch, sm and icon-sm stay 32px and get the invisible hit area, and lg is 48px everywhere. The minimum touch target size guide compares what WCAG, Apple and Android require and shows how to test the hit areas.

Why do hover effects break on phones?

Touch screens have no hover, so anything that only appears on hover does not exist on a phone. In Tailwind CSS v4 the hover: variant only applies when the primary input can hover (@media (hover: hover)). That fixes the old sticky hover state after a tap, and it also means a hover-only control never shows up on touch at all.

The classic case is a row action that fades in when the pointer is over the row. The fix is a focus variant and a coarse-pointer variant:

import { Ellipsis } from "lucide-react";

export function ClientRow({ name }: { name: string }) {
  return (
    <li className="group/row flex h-12 items-center justify-between gap-3 px-4">
      {name}
      <button
        type="button"
        aria-label={`Actions for ${name}`}
        className="grid size-8 place-items-center opacity-0 transition-opacity group-hover/row:opacity-100 group-focus-within/row:opacity-100 pointer-coarse:opacity-100"
      >
        <Ellipsis className="size-4" />
      </button>
    </li>
  );
}

Hover reveals it for a mouse, focus reveals it for a keyboard, and on a coarse pointer it is always there. The Data Table puts the same classes on the wrapper of its row menu trigger, plus has-[[data-state=open]]:opacity-100: without it, the trigger fades out while its menu is open, as soon as the pointer moves from the row into the menu. The other two replacements for hover are a tap and a long press: a hover card opens as a sheet on the first tap, a tooltip shows on a long press, and a context menu opens as an action sheet when you hold a row.

How do you keep fixed bars clear of the notch and the home indicator?

Set viewport-fit=cover, then pad every element pinned to a screen edge with env(safe-area-inset-*), with a minimum for devices that report zero. cover scales the viewport to fill the whole display, notch and home indicator included, and MDN highly recommends the safe area inset variables with it so important content stays visible.

In the Next.js App Router the viewport meta tag comes from a viewport export in the root layout:

// app/layout.tsx
import type { Viewport } from "next";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
};

Then pad with an arbitrary value: pb-[max(env(safe-area-inset-bottom),12px)]. A plain pb-[env(safe-area-inset-bottom)] leaves buttons touching the screen edge on devices without a home indicator, where the inset is 0; max() keeps a little air.

The harder problem is two bars at once. A product page on a phone often has a tab bar at the bottom and a buy bar above it, and both want the safe area. The Bottom Tab Bar pads the home indicator and writes its height to a --bottom-bar-offset CSS variable. The Sticky CTA Bar sits at bottom: var(--bottom-bar-offset) and pads only the part of the safe area the tab bar does not already cover, so there is no double gap:

"use client";

import { House, Search, ShoppingBag, UserRound } from "lucide-react";
import { BottomTabBar, type BottomTabBarItem } from "@/components/ui/bottom-tab-bar";
import { StickyCtaBar } from "@/components/ui/sticky-cta-bar";

const tabs: BottomTabBarItem[] = [
  { label: "Home", href: "/", icon: <House /> },
  { label: "Search", href: "/search", icon: <Search /> },
  { label: "Cart", href: "/cart", icon: <ShoppingBag />, badge: 2 },
  { label: "Account", href: "/account", icon: <UserRound /> },
];

export function ProductChrome({ onAddToCart }: { onAddToCart: () => Promise<void> }) {
  return (
    <>
      <StickyCtaBar
        price={349}
        compareAtPrice={449}
        locale="en-US"
        actionLabel="Add to cart"
        tone="brand"
        hideFrom="md"
        onAction={onAddToCart}
      />
      <BottomTabBar items={tabs} className="md:hidden" hideOnScroll />
    </>
  );
}

The tab bar takes 3 to 5 tabs, each far larger than 44px. With hideOnScroll it follows your finger out of view on the way down and comes back on the way up, moved by a motion value so nothing re-renders per frame. The buy bar shows a spinner while the onAction promise runs without changing its width. The Tailwind safe area insets tutorial covers the utilities, a FAB stacked above the tab bar and where toasts go, and the React bottom navigation bar guide covers badges, the center action and when a sidebar fits better.

Live demo: Bottom Tab Bar. The original article embeds an interactive demo here (Tap the tabs, then tap the active one again to jump back to the top; the raised Add button opens a sheet). Try it live on wingo-ui.com or open the Bottom Tab Bar docs. Install: npx wingo-ui@latest add bottom-tab-bar

The demo is a small CRM with four tabs, an unread count on Inbox and a raised Add action. Open a client, then tap Clients again: the tab goes back to its first screen, the way iOS tab bars do.

Should you use 100vh, dvh or svh on mobile?

Use dvh for app shells and sheets, svh for blocks that must not change height while scrolling, and never vh. MDN defines vh as equal to lvh, the large viewport measured with the browser toolbars retracted. While the address bar is showing, 100vh (Tailwind's h-screen) is taller than the visible area, and the bottom of your layout, often the button that matters, sits under the toolbar.

dvh follows the toolbars as they expand and retract, which is what a full-height shell wants. MDN also warns that dynamic units can resize content while the user scrolls, so a hero section sized in dvh may twitch; svh is the stable choice there. Tailwind CSS v4 ships h-dvh, min-h-dvh, h-svh and h-lvh. In Wingo UI the App Shell uses min-h-dvh and bottom sheets cap at max-h-[92dvh], so a tall sheet keeps a strip of the page visible above it whatever the toolbars do. The 100vh mobile fix compares the three units in detail and builds both kinds of full-height shell.

What happens to bottom bars when the on-screen keyboard opens?

They end up behind the keyboard unless you move them. Since Chrome 108 on Android, the keyboard resizes only the visual viewport, which the Chrome team describes as matching Safari on iOS. An element with position: fixed; bottom: 0 is placed against the layout viewport, which still reaches the bottom of the screen, behind the keyboard.

There are two good answers. Hide the bar while a field has focus, which suits a checkout bar with a coupon field (the Sticky CTA Bar's default, keyboard="hide"). Or lift it by the height the keyboard covers, which suits a chat composer (keyboard="lift"). The lift comes from the visual viewport: the covered height is innerHeight - visualViewport.height - visualViewport.offsetTop while a text field has focus. The useKeyboardInset hook (Pro) measures it at most once per frame and exposes it as a motion value, so the bar moves without a re-render:

"use client";

import { motion, useTransform } from "motion/react";
import { useKeyboardInset } from "@/hooks/use-keyboard-inset";

export function Composer() {
  const { inset } = useKeyboardInset();
  const y = useTransform(inset, (value) => -value);
  return (
    <motion.form style={{ y }} className="fixed inset-x-0 bottom-0 bg-background px-4 pt-2 pb-[max(env(safe-area-inset-bottom),12px)]">
      <input
        aria-label="Message"
        inputMode="text"
        enterKeyHint="send"
        autoComplete="off"
        className="h-11 w-full rounded-full bg-foreground/5 px-4 text-base md:text-sm"
      />
    </motion.form>
  );
}

Two more keyboard rules. Give text inputs 16px text on phones (text-base md:text-sm): iOS Safari zooms the page into any focused field with smaller text and does not zoom back out. And set inputMode, enterKeyHint and autoComplete on every field, so the phone shows the right keyboard, the right return key label and the right autofill.

How should a data table work on a phone?

Below 768px, turn every row into a card: the primary field as the title, a status badge or an amount in the corner, two to four secondary fields as label and value pairs, and the row actions in a menu that opens as a sheet. Horizontal scrolling is acceptable only when the job is comparing columns, like a spreadsheet or a pricing matrix. For a list of invoices or clients it hides most of every row and makes people scroll in two directions to read one record.

The Data Table does this by default (mobileLayout="cards"). Each column can say where it goes on the card with a mobile role, and the table guesses sensibly when you do not (the first column is the title, the first badge or else the last number is the meta):

"use client";

import { Pencil } from "lucide-react";
import { DataTable, createColumns } from "@/components/ui/data-table";

type Invoice = { id: string; client: string; city: string; status: string; amount: number };

const col = createColumns<Invoice>();
const columns = col([
  col.accessor("client", { header: "Client", mobile: "title" }),
  col.accessor("city", { header: "City", mobile: "subtitle" }),
  col.accessor("status", {
    header: "Status",
    type: "badge",
    badge: { Paid: { tone: "success" }, Overdue: { tone: "danger" }, Draft: { tone: "neutral" } },
    mobile: "meta",
  }),
  col.accessor("amount", { header: "Amount", type: "currency" }),
  col.accessor("id", { header: "Invoice", mobile: "hidden" }),
]);

export function Invoices({ invoices }: { invoices: Invoice[] }) {
  return (
    <DataTable
      data={invoices}
      columns={columns}
      caption="Invoices"
      locale="en-US"
      selectionMode="multiple"
      rowActions={(row) => [{ label: "Edit", icon: <Pencil />, onSelect: () => console.log(row.id) }]}
    />
  );
}

On a phone you long press a card to start selecting, tap to add more, and the bulk actions float at the bottom. Sorting, filters and the row menu open as bottom sheets, and Load more appends rows instead of a pager with tiny page numbers. The table and the cards are both in the server HTML, hidden and shown with breakpoints, so a phone never sees the table first. The TanStack Table v9 data table tutorial builds filters, bulk actions and server pagination on TanStack directly, along with the phone layout.

Live demo: Data Table. The original article embeds an interactive demo here (On a phone every row is a card you can long press to select; on a wide screen you get the full table with sorting and column menus). Try it live on wingo-ui.com or open the Data Table docs. Install: npx wingo-ui@latest add data-table

The demo is a client list with search, quick filters, status badges and balances. Below 768px each row becomes a card with the client name as the title and the status in the corner. Which columns make it onto a card, and how sorting and bulk actions work without headers, are in the responsive table mobile guide.

Which gestures belong in a mobile web app?

Drag to dismiss, pull to refresh, swipe actions on rows and hold to confirm all belong, as long as each has a visible alternative and leaves native scrolling alone. Gestures are invisible until someone shows you, and people using a keyboard, a switch or a screen reader cannot perform them at all.

• Always a button path. Sheets close with Escape, a tap outside or a close button. Pull to refresh pairs with a refresh button. Swipe actions on a row also live in its menu.
• touch-action on draggable surfaces. touch-pan-y on something you swipe sideways keeps vertical scrolling native; touch-none is for surfaces you drag freely, like a signature pad or a slider thumb.
• overscroll-behavior: contain on scroll containers. It stops a scroll inside a sheet from chaining into the page, and keeps the browser's own pull to refresh from fighting yours.
• Motion values, not state. A drag that calls setState on every pointer move re-renders on every frame. Write the offset to a motion value and only commit state when the gesture ends.

Sortable lists and boards are where these rules collide with native scrolling; the dnd kit mobile tutorial sets up touch sensors that let a swipe still scroll the page.

The Pull To Refresh shows where the rules bend. It sets overscroll-behavior-y: contain on its scroller and moves the content with a motion value under rubberband resistance. It cannot use touch-action, because the list it wraps must keep scrolling natively, so it listens to touchmove with passive: false and cancels the scroll only for a downward pull at the very top. It ticks when the pull arms, spins until your promise settles (500ms at least, so it never flashes), and exposes the same refresh as an API for a button (the React pull to refresh guide covers the indicator styles, accessibility and long virtualized lists):

"use client";

import { useState, type ReactNode } from "react";
import { RotateCw } from "lucide-react";
import { Button } from "@/components/ui/button";
import { PullToRefresh, type PullToRefreshApi } from "@/components/ui/pull-to-refresh";

export function Feed({ reload, children }: { reload: () => Promise<void>; children: ReactNode }) {
  const [api, setApi] = useState<PullToRefreshApi>();
  return (
    <div className="flex h-dvh flex-col">
      <header className="flex h-14 items-center justify-end px-4">
        <Button variant="ghost" size="icon" radius="full" aria-label="Reload" onClick={() => api?.refresh()}>
          <RotateCw />
        </Button>
      </header>
      <PullToRefresh scroll="self" className="min-h-0 flex-1" setApi={setApi} onRefresh={reload}>
        {children}
      </PullToRefresh>
    </div>
  );
}

Hold to confirm is the gesture for actions that deserve more than a tap and less than a dialog, like deleting a client. The Haptic Button in mode="hold" fills while you hold a finger, the mouse button, Space or Enter, and runs onConfirm when the fill completes. Screen readers and voice control, which activate with a plain click and cannot hold, get a two-step path instead: the first activation announces "Activate again to confirm" and a second one within 4 seconds confirms.

"use client";

import { Trash2 } from "lucide-react";
import { HapticButton } from "@/components/ui/haptic-button";

export function DeleteClient({ onDelete }: { onDelete: () => Promise<void> }) {
  return (
    <HapticButton tone="danger" variant="soft" mode="hold" fullWidth leftIcon={<Trash2 />} onConfirm={onDelete}>
      Hold to delete
    </HapticButton>
  );
}

On Android the tick uses navigator.vibrate. Safari on iPhone has no Vibration API, so the haptics helper falls back to clicking a hidden native switch (<input type="checkbox" switch>). That played the system tick up to iOS 26.4; from iOS 26.5 WebKit ticks only for the user's own tap on the switch, so on a current iPhone the fill carries the feedback on its own. Desktops and mouse clicks stay silent. The Web Vibration API guide covers what still ticks on an iPhone and how to let people turn haptics off.

Does shadcn/ui handle mobile?

Partly. As of October 2026 the shadcn mobile story is one component and one pattern. The Drawer docs come in a Base UI version, which now uses Base UI's drawer instead of Vaul, and a Radix version, which is still built on Vaul. Both include a Responsive section that renders a Dialog on desktop and a Drawer on mobile; the example decides with useMediaQuery("(min-width: 768px)") and shares one form between both branches. The Popover docs describe no mobile behavior, and Select and Dropdown Menu stay floating panels at every width unless you write a wrapper for each.

That suits a library meant as a minimal, unopinionated starting point. shadcn/ui is free and MIT licensed, its GitHub repository shows about 125k stars (as of October 2026), and its docs let you choose between Base UI, Radix and React Aria primitives. If your app is used mostly on desktops, or you want to write and own every responsive wrapper yourself, it is the better choice. Our comparison of the best React component libraries for mobile checks shadcn/ui and eight others at 390px.

If most of your users arrive on phones, the wrappers add up: every overlay needs the swap, every control needs the coarse-pointer size, every fixed bar needs the safe area, and every one of them has to avoid the hydration flash. Wingo UI makes those decisions inside each component, so the defaults are already mobile-first and you opt out per instance.

Which components does a React mobile web app need?

A React mobile web app usually needs overlays that become sheets, a tab bar for the primary navigation, a bottom action bar on product and checkout pages, lists with swipe actions, and a table that becomes cards. Here is the set in Wingo UI (registry 1.7.0, 326 items as of October 2026), with what each one does on a phone:

The whole Mobile category has 15 components, all built to these rules, with reduced motion support and designed light and dark themes.

How do you test mobile-first React components?

Test at 390 by 844 and 360 by 780 with touch enabled, then on a real iPhone for the parts emulators get wrong. Chrome's device mode switches the pointer to coarse, which is enough to see pointer-coarse styles and the sheets. It does not reproduce the iOS keyboard, the focus zoom, the home indicator or the toolbar resizing, so those need a phone.

For automated checks, Playwright can emulate a touch phone per test file:

import { expect, test } from "@playwright/test";

test.use({ viewport: { width: 390, height: 844 }, hasTouch: true, isMobile: true });

test("filters open as a bottom sheet on a phone", async ({ page }) => {
  await page.goto("/listings");
  await page.getByRole("button", { name: "Filters" }).tap();
  await expect(page.getByRole("dialog", { name: "Filters" })).toBeVisible();
});

Run the same pass in light and dark and with reduced motion turned on. A sheet handle or a hairline drawn at a low opacity can be clear in one theme and vanish in the other, and under reduced motion every overlay still has to open and close, only with a shorter slide or a fade.

Which guides go deeper on each rule?

Each of these posts in Mobile UI in React takes one rule or one component further:

• Shadcn responsive dialog: a centered card on desktop and a bottom sheet on phones, with the content written once.
• React bottom sheet for the web: snap points, drag to dismiss, nested sheets and the keyboard on vaul.
• Minimum touch target size: the WCAG, iOS and Android numbers, and 44px on touch in Tailwind without a bloated desktop.
• Tailwind safe area insets: bottom bars, FABs and toasts clear of the notch and the home indicator.
• 100vh on mobile: when to use dvh, svh or lvh, and full-height shells that do not jump.
• React bottom navigation bar: a tab bar with badges, a center action and hide on scroll.
• React pull to refresh: a custom refresh in a PWA that does not fight the browser's own.
• Web Vibration API: the haptic feedback a page can trigger on Android and iPhone.
• React PWA install prompt: an install prompt for Chrome, Edge and iPhone, and when not to ask.
• Responsive tables on mobile: when rows become cards, which columns survive, and sorting and bulk actions without headers.
• React segmented control: the iOS thumb you can drag, radio semantics, and when tabs or a toggle group fit better.
• React wheel picker: iOS wheels for times and dates on a native snapping scroller, with a typed field on desktop.

Where should you start?

Start with the overlays, because they are the most visible mobile failure and the cheapest to fix. Install the free Popover with npx wingo-ui@latest add popover (it brings the Drawer, the Button and the media query hook along), swap it in for one panel that people open on phones, and try it on your own device. The tab bar, sticky CTA bar, pull to refresh, haptic button and data table are part of Wingo UI Pro.

Components in this post

• Drawer (Free): The library's bottom sheet on vaul: drag to dismiss, snap points, nesting, and a side panel or dialog on desktop. Install: npx wingo-ui@latest add drawer
• Popover (Free): Rich floating content anchored to a trigger, like a quick filter, form or share panel, that becomes a bottom sheet on phones. Install: npx wingo-ui@latest add popover
• Bottom Tab Bar (Pro): The phone's primary navigation: 3 to 5 tabs at the thumb with an animated pill, badges, a raised center action and hide on scroll. Install: npx wingo-ui@latest add bottom-tab-bar
• Pull To Refresh (Pro): Pull a list down past its top to reload it, with rubberband resistance, an arrow, iOS spokes or a Material ring, and a haptic tick. Install: npx wingo-ui@latest add pull-to-refresh
• Sticky CTA Bar (Pro): The bottom action bar of product, listing and checkout pages on phones: the price on one side, the main action on the other. Install: npx wingo-ui@latest add sticky-cta-bar
• Data Table (Pro): The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. Install: npx wingo-ui@latest add data-table
• Haptic Button (Pro): A button that answers like a native control: spring press, touch ripple, a haptic tick, a long-press action and a hold-to-confirm mode. Install: npx wingo-ui@latest add haptic-button

FAQ

What is a mobile-first React component?

A component designed for touch, a narrow screen and an on-screen keyboard first, then enhanced for a mouse and a wide window. On a phone it changes its behavior as well as its layout: it opens a bottom sheet instead of a popover, keeps 44px hit areas and has no hover-only controls.

How big should buttons be in a mobile web app?

WCAG 2.2 asks for 24 by 24 CSS pixels at level AA and 44 by 44 at level AAA. Apple's guidelines use 44 by 44 points as the default iOS control size and Android recommends 48 by 48 dp. A practical rule for the web is 44px on coarse pointers with 8px between targets.

Should I use a useIsMobile hook or CSS media queries?

Use CSS breakpoints for anything visible on the first paint, because the server cannot know the screen width and a hook returns a guess there. Use the hook for behavior that starts after an interaction, such as opening a bottom sheet instead of a popover.

Does shadcn/ui have a bottom sheet for mobile?

Yes, the Drawer. As of October 2026 its Base UI version is built on Base UI's drawer and its Radix version on Vaul, and the docs show a responsive example that renders a Dialog on desktop and a Drawer on mobile. Popover, Select and Dropdown Menu do not switch to a sheet on their own.

Why do hover effects not work on phones?

Touch screens have no hover, and in Tailwind CSS v4 the hover variant only applies when the primary input can hover, so a control that only appears on hover never shows up on a phone. Reveal it on focus and on coarse pointers as well, or replace the hover with a tap or a long press.

Which Wingo UI mobile components are free?

The Drawer, Sheet, Popover, Dialog, Select, Dropdown Menu, Segmented Control, Button and the useMediaQuery hook are free, and the Popover, Dialog, Select and Dropdown Menu open as bottom sheets below 768px by default. The 15 components of the Mobile category (tab bar, sticky CTA bar, pull to refresh, haptic button and more) and the Data Table are Pro.

This article was originally published on the Wingo UI blog: Mobile-First React Components: 9 Rules With Code. The original has the live, interactive demos and is kept up to date.