# Shadcn Syntax Button > Use when adding, customising, or debugging a shadcn ui Button, choosing between the six built-in variants (default / destructive / outline / secondary / ghost / link), choosing between the size variants (default / sm / lg / icon plus the v4-only xs / icon-xs / icon-sm / icon-lg), using the `asChild` Slot pattern to wrap a Next.js Link, a react-router Link, or any other custom anchor as the rendered button element, typing a Button-derived component with `VariantProps`, building an icon-only button, building a loading button with a spinner, understanding the focus-ring difference between Tailwind v3 and v4 output, or diagnosing why a Button renders unstyled, ignores `className`, or crashes the page after `asChild` is added. Prevents the canonical Button-level failures : passing multiple children inside ` ``` `variant` and `size` are independent props. Both default to `"default"`. Both are typed by `VariantProps` so autocomplete reflects exactly the keys in the local `buttonVariants` cva definition. ### Variant decision table | User intent | Variant | Reason | |-------------|---------|--------| | Primary call-to-action ("Save", "Submit", "Continue") | `default` | Filled primary background ; highest visual weight | | Irreversible / destructive action ("Delete", "Discard", "Reset") | `destructive` | Red fill signals risk ; pairs with confirmation dialog | | Secondary action next to a primary ("Cancel", "Skip", "Back") | `outline` or `secondary` | Lower weight than `default` ; `outline` reads as "alternate", `secondary` reads as "muted-primary" | | Tertiary action inside a busy UI (toolbar, table row) | `ghost` | No background until hover ; minimal chrome | | Action that semantically IS a link (navigation, "Forgot password?") | `link` | Reads as text-link ; pairs with `asChild` + `` | ALWAYS pick variant by user intent, NEVER by visual mood. If the action is destructive, `variant="destructive"` is non-optional, even if the surrounding design feels muted. ### Size decision table | User intent | Size | Notes | |-------------|------|-------| | Default form / dialog button | `default` | 36px height (v4) ; pairs with `Input` of identical height | | Compact toolbar / table action | `sm` | 32px height ; gap-1.5 ; rounded-md | | Hero / marketing CTA | `lg` | 40px height ; px-6 | | Icon-only button (toolbar, dialog close, table action) | `icon` | square 36px (v4) ; mandates a single icon child | | Tailwind-v4-only : xs / icon-xs / icon-sm / icon-lg | `xs`, `icon-xs`, `icon-sm`, `icon-lg` | Extra granularity introduced in v4 ; NEVER assume these exist in a v3 project | ALWAYS use `size="icon"` when the visible content is a single icon. NEVER drop an icon into `size="default"` : padding will dominate and accessibility-target rules become awkward. ### Four invariants 1. ALWAYS import from the local alias `@/components/ui/button`. NEVER from `shadcn-ui` or `@shadcn/ui`. (See `shadcn-core-architecture` for the copy-not-install rationale.) 2. ALWAYS pass exactly ONE child element when `asChild` is true. NEVER two siblings ; Slot.Root crashes. 3. ALWAYS let `className` pass through unchanged. NEVER concatenate by hand : the Button source already calls `cn(buttonVariants({ variant, size, className }))`, which routes through twMerge so caller classes win conflicts. 4. ALWAYS treat Button as RSC-safe : the file has no `"use client"` directive in either v3 or v4 form. NEVER add one just because the file uses an `asChild` boolean. ## Decision Tree 1 : Which variant? ``` Q1. Is this the primary action of the surface (form, dialog, page hero)? yes -> variant="default" no -> Q2 Q2. Is this action destructive, irreversible, or data-losing? yes -> variant="destructive" (ALWAYS pair with a confirmation Dialog) no -> Q3 Q3. Is this action a secondary peer of a primary button (Cancel / Back / Skip)? yes -> Q3a no -> Q4 Q3a. Should the secondary read as "alternate path" -> variant="outline" Should the secondary read as "muted primary" -> variant="secondary" Q4. Is this a tertiary action embedded inside a busy region (table row, toolbar, command palette, sidebar item)? yes -> variant="ghost" no -> Q5 Q5. Is the action SEMANTICALLY a link (navigation, "Forgot password?", "Privacy policy", external URL)? yes -> variant="link" + asChild + / no -> reconsider : default or outline is almost certainly right ``` ## Decision Tree 2 : `asChild` or no `asChild`? ``` Q1. Does the consumer need a NON-button element to be rendered (an , a Next.js , a react-router , a custom forwardRef component)? no -> NEVER use asChild ; just render ``` ## Decision Tree 3 : Icon-button or labelled button with an icon? ``` Q1. Is the visible content ONLY an icon (no text)? yes -> size="icon" + lucide icon child + ALWAYS provide an accessible name via aria-label no -> Q2 Q2. Is the button text-with-leading-or-trailing icon? yes -> size="default" (or sm/lg) ; drop the icon AND the label as siblings inside the Button ; the cva base layer includes `gap-2` and `[&_svg]:size-4` so the icon spaces and sizes automatically no -> reconsider : you have neither an icon nor a label ``` ## Patterns ### Pattern 1 : Variant catalogue (verbatim from the canonical source) The six variant values, with verbatim classes from `apps/v4/registry/new-york-v4/ui/button.tsx` : | Variant | Verbatim classes | |---------|------------------| | `default` | `bg-primary text-primary-foreground hover:bg-primary/90` | | `destructive` | `bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40` | | `outline` | `border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50` | | `secondary` | `bg-secondary text-secondary-foreground hover:bg-secondary/80` | | `ghost` | `hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50` | | `link` | `text-primary underline-offset-4 hover:underline` | ALWAYS reference these by `variant=` prop. NEVER hand-copy the class strings : if shadcn upgrades them via the registry, your hand-copy diverges silently. ### Pattern 2 : Size catalogue (verbatim, v4 only) | Size | Verbatim classes | Use | |------|------------------|-----| | `default` | `h-9 px-4 py-2 has-[>svg]:px-3` | Default form / dialog button | | `xs` | `h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3` | Tiny inline action (v4 only) | | `sm` | `h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5` | Compact toolbar / table action | | `lg` | `h-10 rounded-md px-6 has-[>svg]:px-4` | Hero / marketing CTA | | `icon` | `size-9` | Icon-only square button | | `icon-xs` | `size-6 rounded-md [&_svg:not([class*='size-'])]:size-3` | Tiny icon-only (v4 only) | | `icon-sm` | `size-8` | Small icon-only (v4 only) | | `icon-lg` | `size-10` | Large icon-only (v4 only) | For the legacy v3 size set, only `default / sm / lg / icon` exist, with different exact pixel values (see Pattern 5). ### Pattern 3 : `asChild` Slot pattern The canonical (v4) Button source contains exactly this pivot : ```tsx import { Slot } from "radix-ui" // ... function Button({ asChild = false, ...props }) { const Comp = asChild ? Slot.Root : "button" return } ``` When `asChild` is true, the component RENDERS THE CHILD ELEMENT and merges its props (className, ref, event handlers, data attributes) onto that child. The result is a fully styled Button with a different underlying tag. Canonical use : wrap a navigation primitive so the button styling lives on the link. ```tsx // Next.js (App Router, v15+) import Link from "next/link" ``` ```tsx // react-router-dom (v6 or v7 / React Router v7 rebrand) import { Link } from "react-router-dom" ``` ALWAYS exactly ONE child element inside ` ``` ## Section : Tailwind v3 vs Tailwind v4 ring utility shadcn's Button ships two different focus-ring incantations depending on the registry style and the Tailwind version of the consumer project. Both are taken verbatim from the official registry source ; treat them as a single divergence point and emit the correct one. ### v3 (default registry style, `apps/v4/public/r/styles/default/button.json`) ``` focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 ``` Uses the v3 ring API : `ring-2` (a 2px ring) + `ring-offset-2` (a 2px offset) + named `ring-ring` token. The Button component is a `React.forwardRef` and exports a `ButtonProps` interface. ### v4 (new-york-v4 registry style, `apps/v4/registry/new-york-v4/ui/button.tsx`) ``` outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 ``` Uses the v4 ring API : `ring-[3px]` (a 3px ring via the arbitrary-value syntax), no `ring-offset`, a `border-ring` border-colour-shift on focus, and `ring-ring/50` (the ring colour at 50% opacity). The Button is now a plain function component (no `React.forwardRef`, React 19 forwards refs implicitly) typed as `React.ComponentProps<"button">`. ALWAYS emit the variant that matches the consumer project's Tailwind version. To check : read `package.json` for `tailwindcss` (the major version), or read the consumer's `globals.css` for `@import "tailwindcss"` (v4) versus `@tailwind base / components / utilities` (v3). NEVER mix the two ring incantations in one file ; the v3 ring uses ring-offset, the v4 ring uses a border shift, and they layer poorly when combined. ## Section : Icon button + Loading button patterns ### Icon-only button (lucide-react icon) ```tsx import { Plus } from "lucide-react" ``` The cva base layer includes `[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4`, so a lucide icon auto-sizes to 16px (size-4) without any explicit size prop. ALWAYS provide `aria-label` when the visible text is empty ; screen readers have no label otherwise. ### Loading button (spinner + disabled state) ```tsx import { Loader2 } from "lucide-react" function SubmitButton({ isPending }: { isPending: boolean }) { return ( ) } ``` The cva base layer also includes `disabled:pointer-events-none disabled:opacity-50`, so the visual disabled state is automatic. NEVER add a manual `cursor-not-allowed` class on top : the existing `disabled:pointer-events-none` removes hover and pointer events entirely, and Tailwind v4 sets `cursor: default` on buttons by default anyway (see `shadcn-errors-tailwind-v3-v4-migration` for cursor-pointer-on-button workarounds). ## Section : RSC compatibility Button is RSC-safe in both v3 and v4 form. The component file does NOT carry a `"use client"` directive, and it has no client-only React features (no `useState`, no `useEffect`, no DOM refs that the consumer's caller would need to use during render). ALWAYS import `Button` directly into a Server Component without wrapping it in a `"use client"` boundary. The button receives event handlers as props from the calling component (so the CALLER may need `"use client"` if the handler closes over client state), but Button itself does not. NEVER add `"use client"` to `components/ui/button.tsx`. Doing so unnecessarily marks every importing module as a client module and breaks the RSC bundle split documented in `shadcn-impl-rsc-vs-client-boundaries`. ## Anti-patterns (summary ; full catalogue in references/anti-patterns.md) NEVER do these : 1. NEVER pass multiple children to `` with `