DEV Community: Wingo UI

React Bottom Sheet for the Web: Snap Points, Drag, Keyboard

Serban Dan Rusu — Thu, 22 Oct 2026 15:00:00 +0000

TL;DR

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:

Library	Built on	Snap points	Nested sheets	Latest release
vaul	Radix Dialog	Fractions or px strings	`Drawer.NestedRoot`	1.1.2, Dec 14, 2024
Base UI Drawer	Base UI Dialog	Fractions, px or rem	Yes, styled with CSS variables	@base-ui/react 1.8.0, Sep 4, 2026
react-modal-sheet	Motion	Fractions or px, including 0 (closed) and 1	Not documented	5.6.0, Mar 27, 2026
react-spring-bottom-sheet	react-spring, react-use-gesture	A function of the content's min and max height	Not documented	3.4.1, Jun 1, 2022

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:

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.
Pixels only. A string goes through parseInt, so "30rem" becomes 30 pixels.
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:

Component	Use it for	Built on	Access
Drawer	Forms, filters, pickers, results over a map; a side panel or a dialog from 768px (`desktop`)	vaul	Free
Action Sheet	A short list of actions about one thing, with a separate Cancel and `await show()`	Drawer	Pro
Family Drawer	A floating sheet that morphs between views, such as a menu and a confirmation	vaul	Free
Sheet	A side panel on desktop that becomes a bottom sheet on phones (`mobileSide="bottom"`)	Radix Dialog and motion	Free

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.

Claude Code shadcn Setup: MCP Server, Skill and CLAUDE.md

Serban Dan Rusu — Thu, 22 Oct 2026 07:00:00 +0000

TL;DR

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:

Piece	Job	How you add it
shadcn MCP server	Searches every registry in `components.json`, returns add commands	`npx shadcn@latest mcp init --client claude`
shadcn skill	Project config and shadcn/ui composition rules	`npx skills add shadcn/ui`
`components.json`	The registries to search, with auth headers	Edit by hand
`CLAUDE.md` block	Which registry owns which folder and which CLI installs it	Six lines by hand
The CLI	Writes files, installs npm packages	`npx shadcn@latest add` or a library's own

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:

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.
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.
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.
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."
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.

Tailwind v4 Design Tokens: Colors, Dark Mode and Contrast

Serban Dan Rusu — Wed, 21 Oct 2026 15:00:00 +0000

TL;DR

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:

Namespace	Utilities it creates	What we keep there
`--color-*`	`bg-`, `text-`, `border-`, `ring-`, `fill-*`	surfaces, text levels, tones, borders, the focus ring
`--shadow-*`	`shadow-*`	three elevation levels
`--radius-*`	`rounded-*`	a legacy scale that new code avoids (see the radius section)
`--z-index-*`	`z-*`	seven stacking layers
`--ease-`, `--transition-duration-`	`ease-`, `duration-`	motion curves and durations
`--font-*`	`font-*`	font families
`--spacing`	`p-`, `m-`, `gap-`, `w-`, `h-*`	the 4px grid (`0.25rem`)

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

Token	Light	Dark	Use
`background`	`#FFFFFF`	`#000000`	the page
`canvas`	`#F6F7F9`	`#0E0E10`	the page of an app (dashboards, admin), under white panels
`card`	`#EBEBEB`	`#121212`	flat gray tiles with no shadow
`surface`	`#FFFFFF` with `shadow-raised`	`#1A1A1A`	raised panels: list groups, stat cards, forms
`popover`	`#FFFFFF` with `shadow-floating`	`#262626`	everything that floats: menus, selects, dialogs, sheets, toasts
`primary`	`#000000`	`#FAFAFA`	the neutral solid fill and tooltips

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

Level	Class	Use	Lowest ratio in our token pairs
Primary	`text-foreground`	titles, values, labels	10.60:1 (light card)
Secondary	`text-muted-foreground`	descriptions, helper text, timestamps	4.62:1 (light card)
Disabled	`text-foreground/45`	disabled labels only	none required
Tone text	`text-success-soft-foreground` and its siblings	errors, deltas, links	5.28:1 (brand on the light card)

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

Class	Value	Use
`z-dropdown`	1000	in-flow panels that are not portaled
`z-sticky`	1100	sticky headers, tab bars, CTA bars
`z-overlay`	1200	the dimmed backdrop
`z-modal`	1300	dialogs, sheets, drawers
`z-popover`	1400	portaled menus, selects, popovers
`z-toast`	1500	toasts
`z-tooltip`	1600	tooltips, always on top

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.

14 shadcn Alternatives in 2026: Price, Mobile and MCP

Serban Dan Rusu — Wed, 21 Oct 2026 07:00:00 +0000

TL;DR

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

Library	Model and base	License	Price	Mobile	Agents
shadcn/ui	CLI copies source; Base UI (default), Radix or React Aria	MIT	Free	Drawer, a Dialog plus Drawer recipe, Sidebar with its own mobile state	MCP server, skill, llms.txt
coss ui	shadcn registry (`@coss`); Base UI	MIT	Free	Drawer with swipe, snap points and nesting	llms.txt, agent skills
Magic UI	shadcn registry (`@magicui`); Motion	MIT (free), paid license (Pro)	Free; Pro $199 one-time	Landing page effects; no sheet, popover or menu in the catalog	MCP server, llms.txt
Aceternity UI	shadcn registry (`@aceternity`); Motion	Aceternity License	Free; $169 a year or $199 lifetime; Team $1,590 for 10 people	Effects and blocks; some blocks document a mobile menu	llms.txt; prompts for v0 and Lovable on paid plans
Untitled UI React	Own CLI or npm; React Aria, Tailwind CSS v4	MIT (free base), PRO license	Free; PRO from $349 one-time for one user	Drawers and modals are PRO	MCP server, llms.txt
Wingo UI	Own CLI or shadcn registry (`@wingo-ui`); Radix, vaul, Motion	Per-developer license; 75 items free	Free; Pro $8 a month, $80 a year or $150 lifetime	Popover, select, menus and dialog open as bottom sheets below 768px; 44px targets on touch; table rows become cards	MCP server, rules for 5 agents, llms.txt, update checks

Packages and primitives

Library	Model and base	License	Price	Mobile	Agents
Mantine 9	npm; own CSS, no Tailwind	MIT	Free	Modal goes full screen on small screens with `use-media-query` (a docs recipe)	MCP server, skills, llms.txt
MUI (Material UI 9)	npm; Emotion	MIT core	Free; MUI X Pro $299 or Premium $599 per developer a year	SwipeableDrawer; Dialog goes full screen with `useMediaQuery` (a docs recipe)	MCP server, llms.txt
Chakra UI 3	npm; Ark UI, Emotion	MIT	Free; Chakra UI Pro blocks $299 one-time	Drawer placement takes breakpoints, such as bottom on phones and end from `md`	MCP server, llms.txt
HeroUI 3	npm; React Aria, Tailwind CSS v4	MIT	Free; HeroUI Pro sold separately	Modal placement `auto` sits at the bottom on mobile and centered on desktop; a separate React Native library	MCP server, agent skills, llms.txt
Ant Design 6	npm; own design language	MIT	Free	Built for enterprise back offices; phones get a separate library, antd-mobile	MCP server (`antd mcp`), llms.txt
daisyUI 5	Tailwind CSS plugin, class names only	MIT	Free; Blueprint MCP $22 a month or $600 lifetime	`modal-bottom sm:modal-middle` puts a modal at the bottom on phones; Dock for bottom navigation	llms.txt, skill; Blueprint MCP (paid)
Konsta UI 5	npm for React, Vue and Svelte; Tailwind CSS	MIT	Free	Mobile only: iOS and Material sheets, tab bars and toolbars	None found
Base UI 1.8	npm; unstyled	MIT	Free	Drawer with swipe to dismiss	llms.txt
React Aria Components	npm; unstyled	Apache-2.0	Free	Press and hover events normalized for touch	MCP server, agent skills, llms.txt

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:

Responsive CSS only. Magic UI and Aceternity UI (effects for landing pages) and Ant Design (a separate mobile library).
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.
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.
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:

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.
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".
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.

React Form Components: Accessible Fields, Zod and Mobile

Serban Dan Rusu — Tue, 20 Oct 2026 15:00:00 +0000

TL;DR

Good React form components share one anatomy: a label tied to the control, one message row that shows the hint or the error, and a counter when there is a limit, with the ids and aria attributes wired for you. Connect them to react-hook-form with register for native inputs and Controller for everything else, and validate with one zod schema once a field has been left. On phones, every control needs 16px text, the right keypad, 44px targets and a bottom sheet instead of a popover.

Every product ships the same handful of forms: sign up, checkout, settings, a filter panel, a support request. The controls differ, the bugs repeat. A label that is not tied to its input, an error that shows up only as a red border, a date picker that opens a small popover under your thumb, a custom select that the browser's autofill skips. This guide treats React form components as one set: which controls a product needs, the anatomy they should share, how to wire them to react-hook-form and zod, and what each one should do on a phone. The examples use Wingo UI, the library we build, so we are not neutral; outside facts link to their sources and are dated.

Which form controls does a product actually need?

The fifteen kinds of input in the table below cover the forms most products ship. Pick each one by what the person is entering, then check what it does on a phone. Most React input components look alike on a desktop. They split apart at 390px, where a popover has no room and a 32px target is too small for a thumb.

What people enter	Component	On a phone
Short text, email, URL	Input (Free)	16px text, keypad from the `type`, 44px box
Long text	Textarea (Free)	Grows line by line, return makes a new line
One of 2 to 5 visible options	Radio Group, Segmented Control (Free)	44px targets, a radio's whole row is one
One of a known list	Select (Free)	Bottom sheet with 48px rows
One of thousands, or from a server	Combobox (Pro)	Full-height sheet with its own search box
Several of a list	Multi-select (Pro)	Sheet with a "Done (3)" footer
Consent to terms	Checkbox (Free)	The whole row is a 44px target
A setting that applies at once	Switch (Free)	Drags like the iOS switch
A number or an amount	Number Input, Currency Input (Pro)	Numeric or decimal keypad, 44px steppers or amount chips
A date	Date Picker (Pro)	No keyboard: a sheet with 44px days
A time of day	Time Picker (Pro)	Wheels in a sheet
A phone number	Phone Input (Pro)	Phone keypad, country list in a sheet
A one-time code	OTP Input (Free)	Numeric keypad, code autofill
A password	Password Input (Pro)	44px reveal button
Files and photos	File Upload (Pro)	"Tap to choose files", an optional camera button

In the catalog these sit in two categories, Inputs with 36 items and Forms with 8, as of release 1.7.0. Two choices in this table are easy to get wrong, so here is where we land.

Choosing one option is three different controls. If people should compare the options at a glance (shipping speed, plan, size), show them all with a radio group or a segmented control; a select hides the choice behind a tap and saves nothing at four options. A select fits a known list that people can scan: states, categories, a few hundred time zones. A combobox fits when typing is faster than scrolling, the list comes from a server, or a free text answer is allowed.

Numbers are the other trap. A native type="number" field ignores maxLength (MDN lists the attribute only for text, search, url, tel, email and password inputs), accepts exponent input such as 1e5, and in some desktop browsers a scroll over the focused field changes its value. Our Input renders type="number" as a text field with a decimal keypad, so maxLength works and a scroll never changes the value.

What anatomy should every form field share?

Every field should have the same three parts in the same order: a label above the control, the control's box, and one message row under it. The message row shows either the hint or the error, never both, and a counter at its end when the field has a limit. In accessible form fields, the parts people forget are the ones nobody sees: the ids, the live region and what a screen reader hears.

Label. A real <label> with htmlFor pointing at the control's id, so clicking it focuses the field and screen readers name the control. The required mark after it is hidden from screen readers, because the control itself carries required. When most fields are required, mark the few optional ones instead.
Hint. Helper text under the box, linked with aria-describedby, so it is read after the label.
Error. It replaces the hint. The control's aria-describedby switches to the error's id, aria-invalid turns on, and the box gets a red ring plus an icon and the text. WCAG 2.2 success criterion 3.3.1 (Level A) requires that an automatically detected error is identified and "described to the user in text", so a red border alone fails.
Counter. "12 / 70" at the end of the message row, amber from 90% and red at the limit. The visible counter is hidden from screen readers, which instead hear "7 characters left" once 10% or less remains, half a second after typing stops. Reading the count on every keystroke is noise.

Swapping the hint for the error, instead of stacking the error under it, means a field with a hint barely changes height when the error appears. The row opens and closes with a short collapse animation and the hint crossfades into the error, so the fields under it glide instead of jumping. The row stays mounted as a polite live region, which means a new error is announced once, without stealing focus.

In Wingo UI the anatomy is the free Field. You can wrap any native control in it, and your own components can join it with one hook:

"use client";

import type { ComponentProps } from "react";
import { FIELD_INPUT, Field, FieldAddon, FieldBox, FieldControl, useFieldControl } from "@/components/ui/field";

// any native control: Field draws the label and messages, FieldControl wires the ids and aria onto the input
export function PriceField({ error }: { error?: string }) {
  return (
    <Field label="Price" description="The final price, tax included." error={error} required>
      <FieldBox>
        <FieldControl>
          <input name="price" inputMode="decimal" placeholder="0" autoComplete="off" className={FIELD_INPUT} />
        </FieldControl>
        <FieldAddon>USD</FieldAddon>
      </FieldBox>
    </Field>
  );
}

type PlainInputProps = ComponentProps<"input"> & { label?: string; description?: string; error?: string };

// your own control: one hook, and it works alone or inside a <Field>
export function PlainInput({ id, label, description, error, required, disabled, readOnly, ...props }: PlainInputProps) {
  // the flags go through the hook: controlProps sets id, required, disabled and readOnly on the input
  const field = useFieldControl({ id, label, description, error, required, disabled, readOnly });
  return field.wrap(
    <FieldBox invalid={field.invalid} disabled={field.disabled} readOnly={field.readOnly}>
      <input {...props} {...field.controlProps} className={FIELD_INPUT} />
    </FieldBox>,
  );
}

FieldControl puts the Field's id, aria-describedby, aria-invalid and aria-required on its child, and the child's own props win. useFieldControl returns the same ids and flags for a custom control, plus wrap(), which draws the label and message row around the control when it has its own label or error, and does nothing when a parent Field already does. Pass required, disabled and readOnly through the hook, not straight onto the input: controlProps always carries those keys, so spreading it after your own props would reset them to undefined.

Live demo: Field. The original article embeds an interactive demo here (Press Continue with a title under 10 characters: the error replaces the hint and the fields below glide down; type and it slides away again). Try it live on wingo-ui.com or open the Field docs. Install: npx wingo-ui@latest add field

The demo is a listing form with a 70 character title, a required price with a USD suffix and a city. The counter turns amber near the limit and the Continue button moves focus to the first field that needs fixing.

Libraries differ in how much of this wiring they do for you. As of October 2026, the shadcn/ui Field is a set of layout parts: you connect FieldLabel htmlFor to the input's id yourself, put data-invalid on the Field and aria-invalid on the control, and pass messages to FieldError, which also accepts an errors array from react-hook-form. React Aria's useField goes the other way and "takes care of creating ids for each element and associating them with the correct ARIA attributes." Our Field sits closer to React Aria: the control reads the ids and flags from context. The explicit shadcn approach has one real advantage: there is no hidden context to debug, and if your team already lives in shadcn/ui it is a fine choice. We chose context because 31 of our controls take the same error prop and have to produce the same markup every time.

Why should every control take label, description and error props?

Because a form then reads as a flat list of fields, and swapping one control for another never changes the wiring. In Wingo UI, 31 controls as of release 1.7.0 (Input, Textarea, Select, Combobox, Phone Input, the date pickers, Checkbox, Switch, Radio Group, Slider and the rest) take label, description and error directly, most of them also required, invalid, disabled and readOnly, and render the Field anatomy themselves:

"use client";

import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";
import { Input } from "@/components/ui/input";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select } from "@/components/ui/select";

const STATES = [
  { value: "CA", label: "California" },
  { value: "NY", label: "New York" },
  { value: "TX", label: "Texas" },
];

export function SameAnatomy() {
  const [title, setTitle] = useState("");
  return (
    <div className="flex flex-col gap-4">
      <Input
        label="Listing title"
        description="Brand, model and condition."
        value={title}
        onValueChange={setTitle}
        error={title && title.length < 10 ? "The title needs at least 10 characters." : undefined}
        showCount
        maxLength={70}
        required
      />
      <Select label="State" options={STATES} description="We ship to these states only." required />
      <PhoneInput label="Phone" defaultCountry="US" description="Only for delivery updates." />
      <DatePicker label="Delivery date" locale="en-US" error="We do not deliver on Sundays." />
    </div>
  );
}

Four different controls, one shape. Anything the Field takes beyond those props (an optional mark, a label action such as "Forgot your password?", a horizontal layout with a label column) goes through fieldProps, which Input, Select, Phone Input, Date Picker and most other controls accept. Sections of a form go in a FieldGroup, which is a real <fieldset> with a <legend>, so a screen reader announces "Shipping address" before the first field of the group. A disabled FieldGroup disables every field inside it, and its columns prop gives one column on phones and two from 640px.

Two details in this anatomy save real bugs. A click on a Select's label focuses the trigger without clicking it, so the word "State" never pops a list open. And the name prop on each of these four controls submits a value through a native or hidden input, which matters more than it sounds; there is a section on it below.

How do you wire react-hook-form and zod to these components?

Use register for controls that render a native input and pass the native onChange, onBlur and ref through, and Controller for everything else. Validate with one zod schema whose rules share one message set, and show errors once a field has been left. There is no special set of React Hook Form components to install: if a component forwards those three things to its focusable element, RHF can drive it.

The form-validation lib packages the form glue our blocks share: createValidators() returns zod rules with one set of messages (text, name, email, password, phone, url, otp, accept for a ticked checkbox, number, plus Romanian cui, iban and postalCode), useZodForm(schema) is useForm with the zod resolver and our timing, and fieldError(form, "email") turns a field's error into the string a component's error prop takes. Here is a delivery request form with seven fields:

"use client";

import { Controller } from "react-hook-form";
import { z } from "zod";
import { addDays, startOfToday } from "date-fns";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { DatePicker } from "@/components/ui/date-picker";
import { Input } from "@/components/ui/input";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select, type SelectOption } from "@/components/ui/select";
import { Textarea } from "@/components/ui/textarea";
import { createValidators, fieldError, useZodForm } from "@/lib/form-validation";

const v = createValidators();

const STATES: SelectOption[] = [
  { value: "CA", label: "California", keywords: ["CA"] },
  { value: "NY", label: "New York", keywords: ["NY"] },
  { value: "TX", label: "Texas", keywords: ["TX"] },
  { value: "WA", label: "Washington", keywords: ["WA"] },
];

const schema = z.object({
  name: v.name(),
  email: v.email(),
  phone: v.phone({ country: "US" }),
  state: v.text(),
  deliveryDate: z.date({ error: v.messages.required }),
  notes: v.text({ required: false, max: 200 }),
  terms: v.accept(),
});

export type DeliveryRequest = z.output<typeof schema>;

export function DeliveryForm({ onSave }: { onSave: (values: DeliveryRequest) => Promise<void> }) {
  const form = useZodForm(schema, {
    defaultValues: { name: "", email: "", phone: "", state: "", notes: "", terms: false },
  });

  return (
    <form onSubmit={form.handleSubmit(onSave)} noValidate className="flex flex-col gap-4">
      {/* native inputs inside: register is enough */}
      <Input label="Full name" autoComplete="name" required {...form.register("name")} error={fieldError(form, "name")} />
      <Input
        label="Email"
        type="email"
        autoComplete="email"
        required
        {...form.register("email")}
        error={fieldError(form, "email")}
      />

      {/* everything else: Controller, with the ref so a failed submit can focus it */}
      <Controller
        control={form.control}
        name="phone"
        render={({ field }) => (
          <PhoneInput
            label="Phone"
            defaultCountry="US"
            preferredCountries={["US", "CA"]}
            required
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={(e164) => field.onChange(e164)}
            onBlur={field.onBlur}
            error={fieldError(form, "phone")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="state"
        render={({ field }) => (
          <Select
            label="State"
            placeholder="Choose the state"
            options={STATES}
            required
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={field.onChange}
            onBlur={field.onBlur}
            error={fieldError(form, "state")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="deliveryDate"
        render={({ field }) => (
          <DatePicker
            label="Delivery date"
            locale="en-US"
            min={addDays(startOfToday(), 1)}
            disabled={{ dayOfWeek: [0] }}
            required
            ref={field.ref}
            name={field.name}
            value={field.value ?? null}
            onValueChange={(date) => field.onChange(date ?? undefined)}
            onBlur={field.onBlur}
            error={fieldError(form, "deliveryDate")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="notes"
        render={({ field }) => (
          <Textarea
            label="Notes for the driver"
            maxLength={200}
            showCount
            ref={field.ref}
            name={field.name}
            value={field.value}
            onValueChange={field.onChange}
            onBlur={field.onBlur}
            error={fieldError(form, "notes")}
          />
        )}
      />
      <Controller
        control={form.control}
        name="terms"
        render={({ field }) => (
          <Checkbox
            label="I accept the delivery terms"
            ref={field.ref}
            name={field.name}
            checked={field.value === true}
            onCheckedChange={(checked) => field.onChange(checked === true)}
            onBlur={field.onBlur}
            error={fieldError(form, "terms")}
          />
        )}
      />
      <Button type="submit" size="lg" fullWidth loading={form.formState.isSubmitting}>
        Request delivery
      </Button>
    </form>
  );
}

Install the pieces with one command; the CLI brings react-hook-form, @hookform/resolvers, zod, libphonenumber-js and date-fns along:

npx wingo-ui@latest add form-validation input select phone-input date-picker textarea checkbox

The phone input, the date picker and the form-validation lib are Pro: run npx wingo-ui@latest login once with a Pro account, or the CLI stops and tells you to sign in. The code uses zod 4 and react-hook-form 7. A few lines in it carry more weight than they look.

Why validate once a field is left?

useZodForm sets mode: "onTouched" and reValidateMode: "onChange". The React Hook Form docs describe onTouched as validation that "is initially triggered on the first blur event. After that, it is triggered on every change event." So nobody hears that their email is invalid after typing one letter, and once an error shows, it clears on the keystroke that fixes it. The same docs warn that mode: "onChange" "often comes with a significant impact on performance", which is a second reason to avoid it on long forms.

Why pass field.ref to every Controller?

shouldFocusError is on by default, so a failed submit moves focus to the first field with an error, but only if RHF holds a ref to something focusable. The Controller docs say to assign field.ref "to allow hook form to focus the error input". In these components ref is a plain prop (React 19, no forwardRef) and it lands on the element a person would focus: the Select's trigger button, the Phone Input's number input, the Date Picker's text input, the Checkbox's button. Our React 19 forwardRef migration guide shows how to move your own fields to that pattern.

When is register not enough?

When the value is anything other than the string in a native input: an E.164 phone number, a Date, a boolean, a value picked from a list. Also when a text field shows a counter. Input and Textarea keep their length in their own state. They pick up a native form reset, but a value that RHF writes straight into the DOM with setValue() or reset(values) reaches the counter only when the field gets focus again. The notes field above goes through Controller for that reason, even though a native textarea sits inside it.

What about the date and the phone number?

The date picker reports null when cleared, so the form stores undefined instead and z.date({ error }) fails with the required message. A typed date reaches the form only once it is complete and allowed, so a typed Sunday never does. The phone input reports an E.164 string such as +12015550123 once the number is possible and an empty string before that. v.phone({ country: "US" }) checks it with libphonenumber-js. The country only matters for values without a calling code, such as a number typed into a plain Input, and it defaults to RO, so set it on a US form.

noValidate on the form turns off the browser's own bubbles, so the zod messages are the only ones people see. Without it, an empty field with required makes the browser block the submit with its own tooltip, and handleSubmit never runs to show your messages.

Live demo: Form validation. The original article embeds an interactive demo here (Submit the empty form: every error shows at once and focus jumps to the first one; fix a field and its error clears as you type). Try it live on wingo-ui.com or open the Form validation docs. Install: npx wingo-ui@latest add form-validation

The demo is a sign-up form built on the same lib: name, email, phone, an optional company tax ID, a password with a strength rule and a terms checkbox.

Should the server validate the same schema?

Yes, always: the client schema is a convenience for people, and anything that reaches your server action or API route has to be checked again. The Next.js forms guide suggests parsing the submitted values with a schema library such as zod inside the Server Action. One catch with our lib today: lib/form-validation.ts starts with "use client" because it holds the useZodForm hook, so server code cannot call createValidators() from it. Write the server schema with zod directly, or, since the file is your source after install, move the rules into a module without the directive.

Do you need react-hook-form at all?

Not for a short form. If every control submits through a real input with a name, the browser's FormData already holds clean values, required fields block the submit natively, a form reset restores the defaults and autofill works. That is why the controls in this guide render something native when you pass name:

Select renders a hidden native <select>, so FormData, required, form reset and browser autofill work. MDN notes that browsers may require a name or id and an owning form before they offer autofill, which is exactly what a select built from divs lacks. Pass autoComplete="address-level1" (the state, in a US address) and the browser can fill it from a saved address.
Phone Input renders a hidden input with the E.164 number, while the visible input shows the formatted national digits.
Date Picker renders a hidden input with the local ISO date (2026-10-23, or 2026-10-23T14:30 with a time), never shifted to UTC, which avoids the off by one day bug that toISOString() causes east of UTC.
Checkbox submits its value through Radix's hidden input while checked; Input and Textarea are native elements.

"use client";

import type { FormEvent } from "react";
import { Button } from "@/components/ui/button";
import { DatePicker } from "@/components/ui/date-picker";
import { PhoneInput } from "@/components/ui/phone-input";
import { Select } from "@/components/ui/select";

const STATES = [
  { value: "CA", label: "California" },
  { value: "NY", label: "New York" },
  { value: "TX", label: "Texas" },
];

export function QuoteForm({ onQuote }: { onQuote: (values: Record<string, FormDataEntryValue>) => void }) {
  const submit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    // { phone: "+12015550123", state: "NY", pickup: "2026-10-23" }
    onQuote(Object.fromEntries(new FormData(event.currentTarget)));
  };

  return (
    <form onSubmit={submit} className="flex flex-col gap-4">
      <PhoneInput name="phone" label="Phone" defaultCountry="US" required />
      <Select name="state" label="State" options={STATES} autoComplete="address-level1" required />
      <DatePicker name="pickup" label="Pickup date" locale="en-US" />
      <Button type="submit">Get a quote</Button>
    </form>
  );
}

The same hidden inputs are what a Server Action receives when you pass it to <form action>, because the action is called with the form's FormData. Our rule of thumb: plain FormData for forms of up to five or six fields with simple rules; react-hook-form once you need cross-field rules (a password and its confirmation, which withMatch in the lib handles), errors that update while typing, dirty tracking for a "You have unsaved changes" prompt, or lists of fields people add and remove.

How should each control behave on a phone?

Fields you type into get 16px text, the right keypad and the right Enter key. Fields you choose from open a bottom sheet instead of a popover. Nothing you tap has a hit area under 44px. The broader rulebook is in our guide to mobile-first React components; here is how it applies control by control.

Text fields: 16px, the keypad and the Enter key

Safari on iOS zooms the page when you focus a field whose text is smaller than 16px, and it does not zoom back out on blur (Rick Strahl's write-up has the details). The fix is the font size. Avoid maximum-scale=1 in the viewport meta tag: the same write-up notes that Android honors it and blocks pinch zoom, which hurts the people who rely on zooming. Every Wingo UI field box starts at text-base (16px) and switches to its desktop size from 768px up: text-base md:text-sm gives the md box 14px there.

The keypad follows type and inputMode: email adds the @ key, tel shows the phone pad, decimal shows digits and a separator. autoComplete with the right token (name, email, tel-national, new-password, postal-code) lets the browser fill the field, and enterKeyHint="next" on every field but the last ("done" there) labels the Enter key with what it will do. The md box is 40px with a mouse and 44px on touch screens through Tailwind's pointer-coarse variant, and the clear button keeps a 44px hit area even though it looks small.

Select and combobox: a sheet, and a keyboard that waits

Below 768px the Select opens a bottom sheet titled with the field's label, with 48px rows and the chosen row scrolled into view. A tap picks and closes. Lists of more than eight options get a search row at the top, but on a touch screen it waits for a tap before it takes focus, so the keyboard does not cover half the list you were about to scroll. The Combobox does the opposite on purpose: a tap opens a full-height sheet with the keyboard already up, because typing is the whole point of a combobox. Pass responsive={false} to keep the popover on phones, for example inside a sheet that is already full screen.

Dates and times: no keyboard

On a desktop, typing a date is faster than clicking one. The Date Picker reads "09232026" as 09/23/2026, "+3" as three days from today and "tomorrow" as tomorrow, and it formats the text the way the locale writes it. On a phone the field never raises the keyboard. A tap opens a sheet with one month of 44px days you can swipe between, plus a row of chips when you turn on presets (Today, Tomorrow, Next week, or your own). With withTime, the time field in the sheet opens its own wheel sheet. The Time Picker uses the same wheels, which snap like the iOS picker and give a short vibration tick per row where the browser supports the Vibration API.

Phone numbers: one clean value

The Phone Input raises the phone keypad, formats the number as the country writes it and keeps the caret after the digit you typed. Pasting or autofilling a number that starts with +44 or 0044 switches the country by itself. The flag button opens the country list, which is a bottom sheet with search on phones, and you can search by country name, ISO code or calling code. Whatever the person types, your form receives one E.164 string.

Live demo: Phone Input. The original article embeds an interactive demo here (Type a US number, then type or paste one that starts with +44: the flag switches to the United Kingdom, and the readout shows the clean value the form submits). Try it live on wingo-ui.com or open the Phone Input docs. Install: npx wingo-ui@latest add phone-input

One-time codes: autofill first

The OTP Input puts autocomplete="one-time-code" on its first slot, which MDN describes as the token for "a one-time password (OTP) for verifying user identity", so the browser can offer a code it received by text message. Slots raise the numeric keypad, a pasted code fills every slot at once, and Backspace clears a slot before it steps back.

It is also the one control in this guide that does not join the Field anatomy: it renders a row of single-character inputs, each named "Digit 1 of 6" and so on, and its error state is a red ring and a shake. Give the row a group name and put the error in text under it with FieldMessage, which works outside a Field:

"use client";

import { useState } from "react";
import { FieldMessage } from "@/components/ui/field";
import OtpInput, { type OtpStatus } from "@/components/ui/otp-input";

export function VerifyPhone({ phone, verify }: { phone: string; verify: (code: string) => Promise<boolean> }) {
  const [status, setStatus] = useState<OtpStatus>("idle");

  return (
    <div className="flex flex-col gap-3">
      <p id="otp-title" className="text-sm text-muted-foreground">
        Enter the 6 digit code we sent to {phone}.
      </p>
      <OtpInput
        role="group"
        aria-labelledby="otp-title"
        length={6}
        status={status}
        autoFocus
        onChange={() => setStatus("idle")}
        onComplete={async (code) => setStatus((await verify(code)) ? "success" : "error")}
      />
      <FieldMessage error={status === "error" ? "That code is not right. Check the latest text message." : undefined} />
    </div>
  );
}

We skip react-hook-form here. A code screen has one value and one rule, and the answer comes from the server, so onComplete and a status are all the state it needs. When you do need it, our React OTP input guide wires the code into react-hook-form and zod, explains why SMS autofill fails silently and adds a resend timer.

Numbers and money

The Number Input and the Currency Input read numbers the way the locale writes them: 1,234.5 in English, 1.234,5 in Romanian. The Number Input raises the numeric keypad, or the decimal one when step or decimals allows decimals, refuses keystrokes that can never become a valid number (a minus when min is 0 or more), and has steppers with a 44px hit area on touch. The Currency Input pads the cents on blur ("1.234,5" becomes "1.234,50") and shows quick amounts as chips through presets, which beat typing for tips and donations.

Test negative numbers on a real phone: MDN notes that with the numeric and decimal input modes, "devices may or may not show a minus key". If yours does not, pass inputMode="text" to the Number Input or rely on the steppers.

When should a form show its errors?

Show an error after the person leaves the field, update it live while they fix it, and on submit show every error at once and move focus to the first. That is the onTouched timing from above, and it fits almost every form. A few rules around it:

Never on load. An empty required field is not an error until someone has had a chance to fill it.
Keep the submit button enabled. A disabled button gives no reason, and Tab skips it, so keyboard users cannot even reach it. Let the submit fail and show the errors.
Check slow things without blocking. An Input with loading shows a spinner at the end of the box (in place of the trailing icon, if it has one), sets aria-busy and stays editable, so a username check runs while the person keeps typing.
Write errors as instructions. "Enter a valid email address" tells people what to do; "Invalid input" makes them guess. Most of the lib's English messages follow that pattern, and createValidators(VALIDATION_MESSAGES_RO) swaps in the Romanian set in one line.

What should a React form components library give you?

A React form components library earns its place when it removes the wiring you would otherwise repeat in every field, and lets you change what it got wrong. Our checklist, which you can apply to any library, ours included (for prices and licenses, see our shadcn/ui alternatives comparison):

One anatomy for every control, with the label, hint, error and counter ids wired for you, and a hook to bring your own controls into it.
Native form participation. A name that ends up in FormData, required that blocks the submit, a form reset that restores defaults, and autofill that reaches custom selects.
Controlled and uncontrolled modes, and a ref that lands on the element a person would focus, so a form library can focus the first error.
Phone behavior built into the same component: 16px text, keypads, 44px targets, bottom sheets below 768px. A separate mobile component doubles every form.
Source you own. Wingo UI copies the files into your project, like shadcn/ui, so you can change a label, a timing or a schema rule without waiting for a release, and npx wingo-ui@latest update merges our later fixes into the files you edited. The same 3-way merge done by hand with git, for files from the shadcn CLI, is in our guide to updating shadcn components without losing edits.

Field, Input, Textarea, Select, Checkbox, Switch, Radio Group, Segmented Control and the OTP input are free. The phone input, the date and time pickers, Combobox, Multi-select, the number and currency inputs and the form-validation lib are part of Pro, which costs $8 a month, $80 a year or $150 once as of October 2026 (see Wingo UI Pro pricing).

Which component guides go deeper?

These posts in the component guides category take one field, one rule or one component further:

React OTP input: paste, SMS autofill, react-hook-form with zod and a resend timer.
Romanian CUI validation: the company tax ID check digit, a zod rule and a lookup that proves the company exists.
IBAN validation in JavaScript: the mod 97 check, why a regex is not enough and a field that formats as you type.
Romanian CNP validator: decoding and validating a personal numeric code, and whether to store it at all.
TanStack Table v9 data table: filters, bulk actions, pinning and server pagination, with cards on phones.
React command palette: Cmd+K with nested pages, async results and a full-height sheet on phones.
dnd kit on mobile: touch drag that still lets the page scroll, and a tap path for people who cannot drag.
Updating shadcn components: pulling upstream fixes into files you already edited.

Where should you start?

Install the free anatomy and the controls most forms need, then build one real form with them:

npx wingo-ui@latest add field input textarea select checkbox

The command copies the source files into your project, installs the npm packages they import and records the versions, so later updates can merge into your edits. In a project without a wingo-ui.json, run npx wingo-ui@latest init first. Open the Field docs for the playground and every prop, and add the phone, date and validation pieces when your forms need them.

Components in this post

Field (Free): The wrapper every form control shares: label, hint, animated error and counter, fieldsets, and the one box recipe all inputs use. Install: npx wingo-ui@latest add field
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
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
OTP Input (Free): A one-time-code input whose characters roll into place behind a caret that slides from slot to slot. Install: npx wingo-ui@latest add otp-input
Phone Input (Pro): A phone number field with a searchable country picker, formatting as you type, validation and one clean E.164 value out. Install: npx wingo-ui@latest add phone-input
Date Picker (Pro): A date field to type in your locale or pick from a calendar popover, with presets, limits and an optional time; a sheet on phones. Install: npx wingo-ui@latest add date-picker
Form validation (Pro): Zod rules with one set of messages (English and Romanian), react-hook-form glue and a pretend request, for the forms of blocks. Install: npx wingo-ui@latest add form-validation
Textarea (Free): Multi-line text that grows with what you write, with a counter, an optional resize handle, a toolbar slot and mod+enter to submit. Install: npx wingo-ui@latest add textarea
Checkbox (Free): A box that is on, off or mixed with a check that draws itself, a label row that is the whole target, cards, and groups with select all. Install: npx wingo-ui@latest add checkbox

FAQ

Do I need react-hook-form to build forms in React?

No. A short form works with native inputs, name attributes and FormData, and Wingo UI's Input, Textarea, Select, Checkbox, Phone Input and Date Picker all submit their value through a native or hidden input once they have a name. React Hook Form pays off once you need per-field validation timing, cross-field rules, dirty state or field arrays.

How do I use react-hook-form with custom components?

Use register when the component renders a native input and passes onChange, onBlur and ref through to it, like a text input. Use Controller for anything whose value is not a string in a native input (a select, a date, a phone number, a checkbox), and pass field.ref so a failed submit can focus it.

How do I make form fields accessible in React?

Tie every label to its control with htmlFor and id, point aria-describedby at the hint or, while it shows, the error, and set aria-invalid on the invalid control. Describe each error in text instead of color alone, announce it through a polite live region, and move focus to the first invalid field when a submit fails.

Why does my iPhone zoom in when I tap an input?

Safari on iOS zooms the page when the focused field's text is smaller than 16px. Give inputs 16px text on phones and go smaller from a wider breakpoint if you want, instead of turning off pinch zoom in the viewport meta tag.

Should I use a select, a radio group or a combobox?

Use a radio group or a segmented control for two to five options people should compare at a glance, a select for a known list up to a few hundred options, and a combobox when the list is huge, comes from a server or accepts free text.

Which Wingo UI form components are free?

Field, Input, Textarea, Select, Checkbox, Switch, Radio Group, Segmented Control, Search Input, Listbox and the OTP input are free. The phone input, the date and time pickers, Combobox, Multi-select, the number, currency, password and email inputs, File Upload and the form-validation lib are Pro.

This article was originally published on the Wingo UI blog: React Form Components: Accessible Fields, Zod and Mobile. The original has the live, interactive demos and is kept up to date.

Component Library MCP: Make Agents Use Real Components

Serban Dan Rusu — Tue, 20 Oct 2026 07:00:00 +0000

TL;DR

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:

Server	Runs as	What the agent gets	Writes files into your project
shadcn MCP	`npx shadcn@latest mcp` (local)	Browse, search and install items from every registry in `components.json`, private ones included	Yes, through the shadcn CLI
MUI MCP	`npx -y @mui/mcp@latest` (local, stdio)	Official Material UI docs and code examples, with links to real pages	No, Material UI is an npm package
React Suite MCP	`npx -y @rsuite/mcp@latest` (local)	`get_component_props`, `list_components`, `list_hooks`, `search_components`	No, React Suite is an npm package
Wingo UI MCP	`https://wingo-ui.com/mcp` (remote, Streamable HTTP) or `npx -y wingo-ui@latest mcp` (local)	Search, props with defaults, usage, blocks, design rules, theme tokens, update checks, changelog	Yes, through the Wingo UI CLI

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:

Piece	What it answers	How often it changes	In Wingo UI
MCP server	What exists, its props and usage, the design rules, which versions are current	Every release	`https://wingo-ui.com/mcp`, 10 tools and 1 prompt
Rules file	When to call which tool, how to install, what never to do	Rarely	A marked block in `CLAUDE.md`, `AGENTS.md` or `GEMINI.md`, a Cursor rule, a Claude Code skill
llms.txt and Markdown docs	The same facts as plain text for agents without MCP	Every release	`/llms.txt`, a file per category, a `.md` twin of every docs page
Registry and CLI	The actual files, their dependencies and a version record	Every release	`/r/<slug>.json` in the shadcn format, `npx wingo-ui@latest add`

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:

Agent	MCP config	Rules
Claude Code	`.mcp.json`	`.claude/skills/wingo-ui/SKILL.md` and a marked block in `CLAUDE.md`
Codex	`~/.codex/config.toml`	A marked block in `AGENTS.md`
Gemini CLI	`.gemini/settings.json`	A marked block in `GEMINI.md`
Grok	`.mcp.json`	A marked block in `AGENTS.md`
Cursor	`.cursor/mcp.json`	`.cursor/rules/wingo-ui.mdc`

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:

check_updates with the items from wingo-ui.json, and a one-line report of what changed upstream.
search_components with "sign in page" and the kind block. On our server the first hit is login-page.
get_block for login-page: the props, the components it composes and the install command.
search_components with "orders table with filters", then get_component for data-table with includeSource: false.
get_design_rules for the forms and mobile topics.
One install for everything: npx wingo-ui@latest add login-page data-table (Button, Input and the rest come along as dependencies).
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.

Mobile-First React Components: 9 Rules With Code

Serban Dan Rusu — Mon, 19 Oct 2026 19:41:35 +0000

TL;DR

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:

Rule	On a phone	Why
Overlays	Popovers, selects, menus and dialogs open as bottom sheets below 768px	An anchored panel has no room and sits under the thumb
Touch targets	44px on coarse pointers, 8px apart	A finger is less precise than a cursor
Hover	Nothing is hover-only	Touch screens have no hover
Safe areas	Fixed bars pad `env(safe-area-inset-*)`	The notch and the home indicator cover content
Height	`dvh` or `svh`, never `vh`	`100vh` is taller than the visible screen
Keyboard	Bottom bars hide or ride above it, inputs use 16px text	Fixed bars end up behind the keyboard
Tables	Rows become cards	Sideways scrolling hides most of every row
Gestures	Every gesture has a visible alternative	Gestures are invisible, and not everyone can perform them
Layout and behavior	CSS breakpoints for layout, a hook for behavior	The server does not know the screen width

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:

Source (as of October 2026)	Size	Status
WCAG 2.2, 2.5.8 Target Size (Minimum)	24 by 24 CSS px, or enough spacing	Level AA
WCAG 2.2, 2.5.5 Target Size (Enhanced)	44 by 44 CSS px	Level AAA
Apple Human Interface Guidelines	44 by 44 pt default on iOS, 28 by 28 pt minimum	Guideline
Android accessibility guide	48 by 48 dp	Recommendation

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:

Component	Job on a phone	Access
Drawer	The bottom sheet: drag to dismiss, snap points, nesting	Free
Popover, Select, Dropdown Menu, Dialog	Open as bottom sheets below 768px	Free
Segmented Control	A few options on a thumb you can drag	Free
Bottom Tab Bar	3 to 5 primary destinations at the thumb	Pro
Sticky CTA Bar	Price and the main action, above the tab bar	Pro
Pull To Refresh	Reload a list with a pull, or a button	Pro
List	Grouped rows with swipe actions and drag to reorder	Pro
Data Table	Rows as cards, long press to select	Pro
Haptic Button	Press feedback, haptics and hold to confirm	Pro
Large Title Header	An iOS large title that collapses into a bar	Pro
Action Sheet	A short list of actions about one thing	Pro
Picker Wheel	iOS wheels for times and dates	Pro

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.