Button Variants

Preview

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

npx shadcn@latest add https://ds.interlace.tools/r/button-variants.json

npx shadcn@latest add @interlace/button-variants

Import

Single named export.

import { buttonVariants } from '@/components/ui/button-variants';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

buttonVariants({ variant, size })
    ├─ variant  default | destructive | outline | secondary | ghost | link
    └─ size     default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg
Defaults are `variant: 'default'`, `size: 'default'`. `pagination.tsx` is
the in-repo example of styling an element rather than nesting a Button: its
`<a>` takes `buttonVariants({ variant, size })` directly. (It reaches the
function through `button.js`, which re-exports it — that path is
`'use client'`; import from this module to keep a server tree server-side.)

Variants

Closed prop unions enforced by class-variance-authority. See Storybook's Variants story for the rendered matrix.

• variant
  • defaultdefault
  • destructive
  • outline
  • secondary
  • ghost
  • link
• size
  • defaultdefault
  • xs
  • sm
  • lg
  • icon
  • icon-xs
  • icon-sm
  • icon-lg

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour

Native element semantics — no interaction layer to get wrong.

Focus ring (WCAG 2.2 SC 2.4.13)

Inherited from the preflight focus contract shipped in @interlace/theme.

Reduced motion

No animation to gate.

ARIA in the source

• aria-invalid

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

Dependencies

Base UI primitive

Native / no Base UI dependency

Lucide icons

none

NPM dependencies

• class-variance-authority

Registry dependencies

• @interlace/theme

Source

The full implementation — components/ui/button-variants.ts once installed.

import { cva, type VariantProps } from 'class-variance-authority';

// @interlace/button-variants v1.3.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/button-variants
// What changed since: https://ds.interlace.tools/c/button-variants#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — buttonVariants
 *
 * The cva variant map that `button.tsx` imports — variant × size class strings
 * and nothing else. Pure CVA: no React, no client APIs, so a server component
 * can style a plain `<a>` with `buttonVariants({ variant, size })`.
 *
 * This is not a component. It exports a function and a type, renders nothing,
 * and has no props, no slots and no DOM — which is exactly why it is a
 * separate module from the `'use client'` Button that consumes it.
 *
 * ## Anatomy
 *

…123 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.