components

description	React component architecture for creating composable, accessible components with data attributes. Use when creating/updating composable components, not for higher-level feature/page components.
name	components
metadata	{"skiller":{"source":".agents/rules/components.mdc"}}

Accessibility

URL: /accessibility

title: Accessibility description: Building components that are usable by everyone, including users with disabilities who rely on assistive technologies.

Accessibility (a11y) is not an optional feature—it's a fundamental requirement for modern web components. Every component must be usable by everyone, including people with visual, motor, auditory, or cognitive disabilities.

This guide is a non-exhaustive list of accessibility principles and patterns that you should follow when building components. It's not a comprehensive guide, but it should give you a sense of the types of issues you should be aware of.

If you use a linter with strong accessibility rules like Ultracite, these types of issues will likely be caught automatically, but it's still important to understand the principles.

Core Principles

1. Semantic HTML First - Use native elements (<button>, <nav>, <ul>) for built-in accessibility
2. Keyboard Navigation - Support Tab, Arrow keys, Home/End, Escape, Enter/Space for all interactions
3. Screen Reader Support - Use ARIA attributes (aria-label, aria-current, aria-live) for proper announcements
4. Visual Accessibility - Ensure focus indicators, sufficient contrast (4.5:1), and responsive text sizing

ARIA Patterns

ARIA enhances semantic HTML for assistive technologies. Key rules:

1. Use semantic HTML first, ARIA only when necessary
2. Don't override native semantics
3. All interactive elements need keyboard access and accessible names

Common Attributes:

• Roles - Define element type (role="button", role="navigation", role="alert")
• States - Describe current state (aria-checked, aria-expanded, aria-selected)
• Properties - Provide context (aria-label, aria-describedby, aria-controls, aria-required, aria-invalid)

Component Patterns

Complex interactive components require specific accessibility patterns. For detailed implementations, consult WAI-ARIA Authoring Practices.

Modal/Dialog:

• role="dialog", aria-modal="true", aria-labelledby
• Trap focus with Tab, close with Escape
• Store and restore previous focus
• Prevent body scroll when open

Dropdown Menu:

• role="menu" on container, role="menuitem" on items
• aria-haspopup="true", aria-expanded, aria-controls
• Arrow keys navigate, Enter/Space select, Escape closes

Tabs:

• role="tablist" on container, role="tab" on buttons, role="tabpanel" on panels
• aria-selected, aria-controls, aria-labelledby
• Arrow Left/Right navigate, Home/End jump to first/last
• Only active tab is focusable (tabIndex={0/-1})

Forms:

• <label htmlFor> paired with input id
• aria-required, aria-invalid, aria-describedby for validation
• Error messages with role="alert"
• Group related inputs with <fieldset> and <legend>

Focus Management

• Focus Visible - Use :focus-visible for keyboard-only focus indicators
• Focus Trapping - Trap Tab/Shift+Tab within modals by cycling between first and last focusable elements
• Focus Restoration - Store document.activeElement before opening overlays, restore on close

Live Regions

Announce dynamic content changes to screen readers:

• Status Messages - aria-live="polite" (waits), aria-live="assertive" (interrupts), role="alert" for errors
• Progress - role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax, aria-label

Color and Contrast

• Contrast Ratios - Normal text: 4.5:1, Large text (≥18pt/14pt bold): 3:1, Non-text (icons, borders): 3:1
• Color Independence - Never use color alone; combine with text, icons, or ARIA attributes

Mobile Accessibility

• Touch Targets - Minimum 44×44px (iOS) or 48×48dp (Android)
• Viewport - Allow zoom (<meta name="viewport" content="width=device-width, initial-scale=1">)

Common Pitfalls

1. Placeholder as Label - Use persistent <label>, not disappearing placeholders
2. Empty Buttons - Icon buttons need aria-label or visually hidden text
3. Disabled Elements - Use aria-disabled instead of disabled to keep focusability and explain why

asChild

URL: /as-child

title: asChild description: How to use the asChild prop to render a custom element within the component.

The asChild prop is a powerful pattern in modern React component libraries. Popularized by Radix UI and adopted by shadcn/ui, this pattern allows you to replace default markup with custom elements while maintaining the component's functionality.

Understanding asChild

When asChild is true, instead of rendering its default DOM element, the component merges its props, behaviors, and event handlers with its immediate child element.

// Without asChild: Creates wrapper
<Dialog.Trigger><button>Open</button></Dialog.Trigger>
// Output: <button data-state="closed"><button>Open</button></button>

// With asChild: Merges props
<Dialog.Trigger asChild><button>Open</button></Dialog.Trigger>
// Output: <button data-state="closed">Open</button>

How It Works

Uses React.cloneElement to clone the child and merge props (including event handlers) from both parent and child components. The enhanced child is returned with combined functionality.

Key Benefits

1. Semantic HTML - Use the most appropriate element (links for navigation, buttons for actions)
2. Clean DOM Structure - Eliminates wrapper elements and "wrapper hell"
3. Design System Integration - Works seamlessly with existing component libraries
4. Component Composition - Compose multiple behaviors onto a single element

Common Use Cases

• Custom Triggers - Replace default triggers with custom components or links
• Accessible Navigation - Maintain semantic navigation elements
• Form Integration - Integrate with form libraries while preserving functionality

Best Practices

1. Maintain Accessibility - Ensure child elements have proper semantics and ARIA attributes
2. Document Support - Use JSDoc to document the asChild prop in your component interfaces
3. Test Forwarding - Verify props are properly forwarded to child components
4. Handle Edge Cases - Consider conditional rendering and dynamic children

Common Pitfalls

1. Not Spreading Props - Child components must spread ...props to receive merged behavior
2. Multiple Children - asChild expects exactly one child element, not multiple
3. Fragment Children - Fragments are not valid, use actual HTML elements

Composition

URL: /composition

title: Composition description: The foundation of building modern UI components.

Composition, or composability, is the foundation of building modern UI components. It is one of the most powerful techniques for creating flexible, reusable components that can handle complex requirements without sacrificing API clarity.

Instead of cramming all functionality into a single component with dozens of props, composition distributes responsibility across multiple cooperating components.

Fernando gave a great talk about this at React Universe Conf 2025, where he shared his approach to rebuilding Slack's Message Composer as a composable component.

Making a component composable

To make a component composable, you need to break it down into smaller, more focused components. For example, let's take this Accordion component:

import { Accordion } from '@/components/ui/accordion';

const data = [
  {
    title: 'Accordion 1',
    content: 'Accordion 1 content',
  },
  {
    title: 'Accordion 2',
    content: 'Accordion 2 content',
  },
  {
    title: 'Accordion 3',
    content: 'Accordion 3 content',
  },
];

return <Accordion data={data} />;

While this Accordion component might seem simple, it's handling too many responsibilities. It's responsible for rendering the container, trigger and content; as well as handling the accordion state and data.

Customizing the styling of this component is difficult because it's tightly coupled. It likely requires global CSS overrides. Additionally, adding new functionality or tweaking the behavior requires modifying the component source code.

To solve this, we can break this down into smaller, more focused components.

1. Root Component

First, let's focus on the container - the component that holds everything together i.e. the trigger and content. This container doesn't need to know about the data, but it does need to keep track of the open state.

However, we also want this state to be accessible by child components. So, let's use the Context API to create a context for the open state.

Finally, to allow for modification of the div element, we'll extend the default HTML attributes.

We'll call this component the "Root" component.

type AccordionProps = React.ComponentProps<'div'> & {
  open: boolean;
  setOpen: (open: boolean) => void;
};

const AccordionContext = createContext<AccordionProps>({
  open: false,
  setOpen: () => {},
});

export type AccordionRootProps = React.ComponentProps<'div'> & {
  open: boolean;
  setOpen: (open: boolean) => void;
};

export const Root = ({ children, open, setOpen, ...props }: AccordionRootProps) => (
  <AccordionContext.Provider value={{ open, setOpen }}>
    <div {...props}>{children}</div>
  </AccordionContext.Provider>
);

2. Item Component

The Item component is the element that contains the accordion item. It is simply a wrapper for each item in the accordion.

export type AccordionItemProps = React.ComponentProps<'div'>;

export const Item = (props: AccordionItemProps) => <div {...props} />;

3. Trigger Component

The Trigger component is the element that opens the accordion when activated. It is responsible for:

• Rendering as a button by default (can be customized with asChild)
• Handling click events to open the accordion
• Managing focus when accordion closes
• Providing proper ARIA attributes

Let's add this component to our Accordion component.

export type AccordionTriggerProps = React.ComponentProps<'button'> & {
  asChild?: boolean;
};

export const Trigger = ({ asChild, ...props }: AccordionTriggerProps) => (
  <AccordionContext.Consumer>
    {({ open, setOpen }) => <button onClick={() => setOpen(!open)} {...props} />}
  </AccordionContext.Consumer>
);

4. Content Component

The Content component is the element that contains the accordion content. It is responsible for:

• Rendering the content when the accordion is open
• Providing proper ARIA attributes

Let's add this component to our Accordion component.

export type AccordionContentProps = React.ComponentProps<'div'> & {
  asChild?: boolean;
};

export const Content = ({ asChild, ...props }: AccordionContentProps) => (
  <AccordionContext.Consumer>{({ open }) => <div {...props} />}</AccordionContext.Consumer>
);

5. Putting it all together

Now that we have all the components, we can put them together in our original file.

import * as Accordion from '@/components/ui/accordion';

const data = [
  {
    title: 'Accordion 1',
    content: 'Accordion 1 content',
  },
  {
    title: 'Accordion 2',
    content: 'Accordion 2 content',
  },
  {
    title: 'Accordion 3',
    content: 'Accordion 3 content',
  },
];

return (
  <Accordion.Root open={false} setOpen={() => {}}>
    {data.map((item) => (
      <Accordion.Item key={item.title}>
        <Accordion.Trigger>{item.title}</Accordion.Trigger>
        <Accordion.Content>{item.content}</Accordion.Content>
      </Accordion.Item>
    ))}
  </Accordion.Root>
);

Naming Conventions

When building composable components, consistent naming conventions are crucial for creating intuitive and predictable APIs. Both shadcn/ui and Radix UI follow established patterns that have become the de facto standard in the React ecosystem.

Root Components

The Root component serves as the main container that wraps all other sub-components. It typically manages shared state and context by providing a context to all child components.

<AccordionRoot>{/* Child components */}</AccordionRoot>

Interactive Elements

Interactive components that trigger actions or toggle states use descriptive names:

• Trigger - The element that initiates an action (opening, closing, toggling)
• Content - The element that contains the main content being shown/hidden

<CollapsibleTrigger>Click to expand</CollapsibleTrigger>
<CollapsibleContent>
  Hidden content revealed here
</CollapsibleContent>

Content Structure

For components with structured content areas, use semantic names that describe their purpose:

• Header - Top section containing titles or controls
• Body - Main content area
• Footer - Bottom section for actions or metadata

<DialogHeader>
  {/* Form title */}
</DialogHeader>
<DialogBody>
  {/* Form content */}
</DialogBody>
<DialogFooter>
  {/* Form footer */}
</DialogFooter>

Informational Components

Components that provide information or context use descriptive suffixes:

• Title - Primary heading or label
• Description - Supporting text or explanatory content

<CardTitle>Project Statistics</CardTitle>
<CardDescription>
  View your project's performance over time
</CardDescription>

Data Attributes

URL: /data-attributes

title: Data Attributes description: Add data attributes to expose component state and enable flexible styling.

Data attributes provide a way to expose component state and structure to consumers for styling. Use two patterns: data-state for visual states and data-slot for component identification.

When Creating Components

Add data-state attributes to expose component state:

• Visual states (open/closed, active/inactive, loading)
• Layout states (orientation, side, alignment)
• Interaction states (disabled, hover, focus when styling children)

Add data-slot attributes for stable component identification:

• Use kebab-case naming (data-slot="submit-button")
• Name reflects purpose, not implementation
• Provides stable selectors that won't break when internals change

Decision Framework

When creating a component, choose the appropriate API:

• data-state - For states that affect styling (open/closed, loading, disabled)
• data-slot - For component identity (stable targeting, parent-child relationships)
• props - For variants, sizes, behavior configuration, and event handlers

A well-designed component combines all three: props for variants/behavior, data-state for conditional styling, and data-slot for stable targeting.

For comprehensive usage patterns and examples, see the Data Attribute Styling Patterns section in react.mdc, which covers:

• Styling with data-state (Tailwind arbitrary variants)
• Radix UI data attributes
• Using data-slot with has-[] and [&_] selectors
• Global CSS patterns
• Naming conventions and best practices

Definitions

URL: /definitions

title: Definitions description: This page establishes precise terminology used throughout the specification. Terms are intentionally framework agnostic, but we will use React for examples.

1. Artifact Taxonomy

1.1 Primitive

A primitive (or, unstyled component) is the lowest‑level building block that provides behavior and accessibility without any styling.

Primitives are completely headless (i.e. unstyled) and encapsulate semantics, focus management, keyboard interaction, layering/portals, ARIA wiring, measurement, and similar concerns. They provide the behavioral foundation but require styling to become finished UI.

Examples:

• Radix UI Primitives (Dialog, Popover, Tooltip, etc.)
• React Aria Components
• Base UI
• Headless UI

Expectations:

• Completely unstyled (headless).
• Single responsibility; composable into styled components.
• Ships with exhaustive a11y behavior for its role.
• Versioning favors stability; breaking changes are rare and documented.

The terms primitive and component are typically used interchangeably across the web, but they are not the same.

1.2 Component

A component is a styled, reusable UI unit that adds visual design to primitives or composes multiple elements to create complete, functional interface elements.

Components are still relatively low-level but include styling, making them immediately usable in applications. They typically wrap unstyled primitives with default visual design while remaining customizable.

Examples:

• shadcn/ui components (styled wrappers of Radix primitives)
• Material UI components
• Ant Design components

Expectations:

• Clear props API; supports controlled and uncontrolled usage where applicable.
• Includes default styling but remains override-friendly (classes, tokens, slots).
• Fully keyboard accessible and screen-reader friendly (inherits from primitives).
• Composable (children/slots, render props, or compound subcomponents).
• May be built from primitives or implement behavior directly with styling.

1.3 Pattern

Patterns are a specific composition of primitives or components that are used to solve a specific UI/UX problem.

Examples:

• Form validation with inline errors
• Confirming destructive actions
• Typeahead search
• Optimistic UI

Expectations.

• Describes behavior, a11y, keyboard map, and failure modes.
• May include reference implementations in multiple frameworks.

1.4 Block

An opinionated, production-ready composition of components that solves a concrete interface use case (often product-specific) with content scaffolding. Blocks trade generality for speed of adoption.

Examples:

• Pricing table
• Auth screens
• Onboarding stepper
• AI chat panel
• Billing settings form

Expectations.

• Strong defaults, copy-paste friendly, easily branded/themed.
• Minimal logic beyond layout and orchestration; domain logic is stubbed via handlers.
• Accepts data via props; never hides data behind fetches without a documented adapter.

Blocks are typically not reusable like a component. You don't import them, but they typically import components and primitives. This makes them good candidates for a [Registry](/registry) distribution method.

1.5 Page

A complete, single-route view composed of multiple blocks arranged to serve a specific user-facing purpose. Pages combine blocks into a cohesive layout that represents one destination in an application.

Examples:

• Landing page (hero block + features block + pricing block + footer block)
• Product detail page (image gallery block + product info block + reviews block)
• Dashboard page (stats block + chart block + activity feed block)

Expectations:

• Combines multiple blocks into a unified layout for a single route.
• Focuses on layout and block orchestration rather than component-level details.
• May include page-specific logic for data coordination between blocks.
• Self-contained for a single URL/route; not intended to be reused across routes.

1.6 Template

A multi-page collection or full-site scaffold that bundles pages, routing configuration, shared layouts, global providers, and project structure. Templates are complete starting points for entire applications or major application sections.

Examples:

• TailwindCSS Templates
• shadcnblocks Templates (full application shells)
• "SaaS starter" (auth pages + dashboard pages + settings pages + marketing pages)
• "E-commerce template" (storefront + product pages + checkout flow + admin pages)

Expectations:

• Includes multiple pages with routing/navigation structure.
• Provides global configuration (theme providers, auth context, layout shells).
• Opinionated project structure with clear conventions.
• Designed as a comprehensive starting point; fork and customize rather than import as dependency.
• May include build configuration, deployment setup, and development tooling.

1.7 Utility (Non-visual)

A helper exported for developer ergonomics or composition; not rendered UI.

Examples:

• React hooks (useControllableState, useId)
• Class utilities
• Keybinding helpers
• Focus scopes

Expectations.

• Side-effect free (except where explicitly documented).
• Testable in isolation; supports tree-shaking.

2. API and Composition Vocabulary

2.1 Props API

The public configuration surface of a component. Props are stable, typed, and documented with defaults and a11y ramifications.

2.2 Children / Slots

Placeholders for caller-provided structure or content.

• Children (implicit slot). JSX between opening/closing tags.
• Named slots. Props like icon, footer, or <Component.Slot> subcomponents.
• Slot forwarding. Passing DOM attributes/className/refs through to the underlying element.

2.3 Render Prop (Function-as-Child)

A function child used to delegate rendering while the parent supplies state/data.

<ParentComponent data={data}>
  {(item) => <ChildComponent key={item.id} {...item} />}
</ParentComponent>

Use when the parent must own data/behavior but the consumer must fully control markup.

2.4 Controlled vs. Uncontrolled

Controlled and uncontrolled are terms used to describe the state of a component.

Controlled components have their value driven by props, and typically emit an onChange event (source of truth is the parent). Uncontrolled components hold internal state; and may expose a defaultValue and imperative reset.

Many inputs should support both. Learn more about controlled and uncontrolled state.

2.5 Provider / Context

A top-level component that supplies shared state/configuration to a subtree (e.g., theme, locale, active tab id). Providers are explicitly documented with required placement.

2.6 Portal

Rendering UI outside the DOM hierarchy to manage layering/stacking context (e.g., modals, popovers, toasts), while preserving a11y (focus trap, aria-modal, inert background).

3. Styling and Theming Vocabulary

3.1 Headless

Implements behavior and accessibility without prescribing appearance. Requires the consumer to supply styling.

3.2 Styled

Ships with default visual design (CSS classes, inline styles, or tokens) but remains override-friendly (className merge, CSS vars, theming).

3.3 Variants

Discrete, documented style or behavior permutations exposed via props (e.g., size="sm|md|lg", tone="neutral|destructive"). Variants are not separate components.

3.4 Design Tokens

Named, platform-agnostic values (e.g., --color-bg, --radius-md, --space-2) that parameterize visual design and support theming.

4. Accessibility Vocabulary

4.1 Role / State / Property

WAI-ARIA attributes that communicate semantics (role="menu"), state (aria-checked), and relationships (aria-controls, aria-labelledby).

4.2 Keyboard Map

The documented set of keyboard interactions for a widget (e.g., Tab, Arrow keys, Home/End, Escape). Every interactive component declares and implements a keyboard map.

4.3 Focus Management

Rules for initial focus, roving focus, focus trapping, and focus return on teardown.

5. Distribution Vocabulary

5.1 Package (Registry Distribution)

The component/library is published to a package registry (e.g., npm) and imported via a bundler. Favors versioned updates and dependency management.

5.2 Copy-and-Paste (Source Distribution)

Source code is integrated directly into the consumer's repository (often via a CLI). Favors ownership, customization, and zero extraneous runtime.

5.3 Registry (Catalog)

A curated index of artifacts (primitives, components, blocks, templates) with metadata, previews, and install/copy instructions. A registry is not necessarily a package manager.

6. Classification Heuristics

Use this decision flow to name and place an artifact:

1. Does it encapsulate a single behavior or a11y concern, with no styling? → Primitive
2. Is it a styled, reusable UI element that adds visual design to primitives or composes multiple elements? → Component
3. Does it solve a concrete product use case with opinionated composition and copy? → Block
4. Does it scaffold a page/flow with routing/providers and replaceable regions? → Template
5. Is it documentation of a recurring solution, independent of implementation? → Pattern
6. Is it non-visual logic for ergonomics/composition? → Utility

7. Non-Goals and Clarifications

• Web Components vs. "Components." In this spec, "component" refers to a reusable UI unit (examples in React). It does not imply the HTML Custom Elements standard unless explicitly stated. Equivalent principles apply across frameworks.
• Widgets. The term “widget” is avoided due to ambiguity; use component (general) or pattern (documentation-only solution).
• Themes vs. Styles. A theme is a parameterization of styles (via tokens). Styles are the concrete presentation. Components should support themes; blocks/templates may ship opinionated styles plus theming hooks.

Design Tokens

URL: /design-tokens

title: Design Tokens description: How semantic naming conventions and design tokens create a flexible, maintainable theming system.

Design tokens are semantic CSS variables that separate theme, context, and usage concerns. Rather than hardcoding colors, use a semantic naming convention that creates layers of abstraction between what something is and how it looks.

This architectural decision creates a maintainable, flexible system that scales across applications.

For practical implementation and examples, see the Design Tokens section in react.mdc, which covers:

• Variable architecture and structure
• Common token patterns (--background, --foreground, --primary, etc.)
• Theme switching (light/dark modes)
• Usage in components

Overview

URL: /

title: Overview description: components.build is an open-source standard for building modern, composable and accessible UI components.

Modern web applications are built on reusable UI components and how we design, build, and share them is important. This specification aims to establish a formal, open standard for building open-source UI components for the modern web.

It is co-authored by and , with contributions from the open-source community and informed by popular projects in the React ecosystem.

The goal is to help open-source maintainers and senior front-end engineers create components that are composable, accessible, and easy to adopt across projects.

What is this specification?

This spec is not a tutorial or course on React, nor a promotion for any specific component library or registry. Instead, it provides high-level guidelines, best practices, and a common terminology for designing UI components.

By following this specification, developers can ensure their components are consistent with modern expectations and can integrate smoothly into any codebase.

Who is this for?

We're writing this for open-source maintainers and experienced front-end engineers who build and distribute component libraries or design systems. We assume you are familiar with JavaScript/TypeScript and React.

All examples will use React (with JSX/TSX) for concreteness, but we hope the fundamental concepts apply to other frameworks like Vue, Svelte, or Angular.

In other words, we hope this spec’s philosophy is framework-agnostic – whether you build with React or another library, you should emphasize the same principles of composition, accessibility, and maintainability.

Polymorphism

URL: /polymorphism

title: Polymorphism description: How to use the as prop to change the rendered HTML element while preserving component functionality.

The as prop is a fundamental pattern in modern React component libraries that allows you to change the underlying HTML element or component that gets rendered.

Popularized by libraries like Styled Components, Emotion, and Chakra UI, this pattern provides flexibility in choosing semantic HTML while maintaining component styling and behavior.

The as prop enables polymorphic components - components that can render as different element types while preserving their core functionality:

<Button as="a" href="/home">
  Go Home
</Button>

<Button as="button" type="submit">
  Submit Form
</Button>

<Button as="div" role="button" tabIndex={0}>
  Custom Element
</Button>

Understanding as

The as prop allows you to override the default element type of a component. Instead of being locked into a specific HTML element, you can adapt the component to render as any valid HTML tag or even another React component.

<Box>Content</Box>              // Renders as default (div)
<Box as="section">Content</Box>  // Renders as <section>
<Box as="nav">Content</Box>      // Renders as <nav>

Implementation Methods

There are two main approaches to implementing polymorphic components: a manual implementation and using Radix UI's Slot component.

Manual Implementation

The as prop implementation uses dynamic component rendering:

// Simplified implementation
function Component({ as: Element = 'div', children, ...props }) {
  return <Element {...props}>{children}</Element>;
}

// More complete implementation with TypeScript
type PolymorphicProps<E extends React.ElementType> = {
  as?: E;
  children?: React.ReactNode;
} & React.ComponentPropsWithoutRef<E>;

function Component<E extends React.ElementType = 'div'>({
  as,
  children,
  ...props
}: PolymorphicProps<E>) {
  const Element = as || 'div';
  return <Element {...props}>{children}</Element>;
}

The component:

1. Accepts an as prop with a default element type
2. Uses the provided element or fallback to default
3. Spreads all other props to the rendered element
4. Maintains type safety with TypeScript generics

Using Radix UI Slot

Radix UI provides a Slot component that offers a more powerful alternative to the as prop pattern. Instead of just changing the element type, Slot merges props with the child component, enabling composition patterns.

First, install the package:

npm install @radix-ui/react-slot

The asChild pattern uses a boolean prop instead of specifying the element type:

import { Slot } from '@radix-ui/react-slot';
import { cva, type VariantProps } from 'class-variance-authority';

const itemVariants = cva('rounded-lg border p-4', {
  variants: {
    variant: {
      default: 'bg-white',
      primary: 'bg-blue-500 text-white',
    },
    size: {
      default: 'h-10 px-4',
      sm: 'h-8 px-3',
      lg: 'h-12 px-6',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
});

function Item({
  className,
  variant = 'default',
  size = 'default',
  asChild = false,
  ...props
}: React.ComponentProps<'div'> & VariantProps<typeof itemVariants> & { asChild?: boolean }) {
  const Comp = asChild ? Slot : 'div';
  return (
    <Comp
      data-slot="item"
      =
      =
      = , ,  }))}
      {}
    />
  );
}

Now you can use it in two ways:

// Default: renders as a div
<Item variant="primary">Content</Item>

// With asChild: merges props with child component
<Item variant="primary" asChild>
  <a href="/home">Link with Item styles</a>
</Item>

The Slot component:

1. Clones the child element
2. Merges the component's props (className, data attributes, etc.) with the child's props
3. Forwards refs correctly
4. Handles event handler composition

Comparison: as vs asChild

as prop (manual implementation):

// Explicit element type
<Button as="a" href="/home">Link Button</Button>
<Button as="button" type="submit">Submit Button</Button>

// Simple, predictable API
// Limited to element types

asChild with Slot:

// Implicit from child
<Button asChild>
  <a href="/home">Link Button</a>
</Button>

<Button asChild>
  <button type="submit">Submit Button</button>
</Button>

// More flexible composition
// Works with any component
// Better prop merging

Key differences:

Feature	as prop	asChild + Slot
API Style	<Button as="a">	<Button asChild><a /></Button>
Element Type	Specified in prop	Inferred from child
Component Composition	Limited	Full support
Prop Merging	Basic spread	Intelligent merging
Ref Forwarding	Manual setup needed	Built-in
Event Handlers	May conflict	Composed correctly
Library Size	No dependency	Requires @radix-ui/react-slot

When to Use Each Approach

Use as prop when:

• You want a simpler API surface
• You're primarily switching between HTML elements
• You want to avoid additional dependencies
• The component is simple and doesn't need complex prop merging

Use asChild + Slot when:

• You need to compose with other components
• You want automatic prop merging behavior
• You're building a component library similar to Radix UI or shadcn/ui
• You need reliable ref forwarding across different component types

Key Benefits

1. Semantic HTML Flexibility - Use the most appropriate element (<Container as="nav">, <Container as="main">, <Container as="aside">)
2. Component Reusability - One component serves multiple purposes (<Text as="h1">, <Text as="p">, <Text as="label">)
3. Accessibility - Choose elements with best a11y for context (<Button as="a" href="/"> vs <Button as="button">)
4. Style System Integration - Maintain consistent styling while changing elements

Common Use Cases

• Typography - Flexible text components that can render as headings, paragraphs, labels, etc.
• Layout - Semantic layout components (Flex, Grid, Stack) that adapt to semantic containers
• Interactive - Components that handle buttons, links, and custom interactive elements with proper accessibility

TypeScript Best Practices

Use generic types for full type safety:

type PolymorphicProps<E extends React.ElementType, Props = {}> = Props &
  Omit<React.ComponentPropsWithoutRef<E>, keyof Props> & { as?: E };

function Component<E extends React.ElementType = 'div'>({
  as,
  ...props
}: PolymorphicProps<E, { customProp?: string }>) {
  const Element = as || 'div';
  return <Element {...props} />;
}

This enables automatic prop inference (<Component as="a" href="/"> validates href, but <Component as="div" href="/"> errors).

Best Practices

1. Default to semantic elements - Choose meaningful defaults (as: Element = 'article' not 'div')
2. Document valid elements - Use JSDoc and TypeScript unions to specify supported elements
3. Validate element appropriateness - Warn in development when accessibility attributes are missing
4. Handle event handlers properly - Add keyboard support when using non-button elements as clickable

Common Pitfalls

1. Invalid HTML nesting - Avoid invalid combinations (button in button, div in p)
2. Missing accessibility - Add ARIA labels when using semantic elements (<Box as="nav" aria-label="...">)
3. Type safety loss - Use generic types, not any
4. Performance - Don't create components inline, define them outside the render function

Core Principles

URL: /principles

title: Core Principles description: When building modern UI components, it's important to keep these core principles in mind.

Composability and Reusability

Favor composition over inheritance – build components that can be combined and nested to create more complex UIs, rather than relying on deep class hierarchies.

Composable components expose a clear API (via props/slots) that allows developers to customize behavior and appearance by plugging in child elements or callbacks.

This makes components highly reusable in different contexts. (React’s design reinforces this: “Props and composition give you all the flexibility you need to customize a component’s look and behavior in an explicit and safe way.”)

Accessible by Default

Components must be usable by all users. Use semantic HTML elements appropriate to the component’s role (e.g. <button> for clickable actions, <ul>/<li> for lists, etc.) and augment with WAI-ARIA attributes when necessary.

Ensure keyboard navigation and focus management are supported (for example, arrow-key navigation in menus, focus traps in modals). Each component should adhere to accessibility standards and guidelines out of the box.

This means providing proper ARIA roles/states and testing with screen readers. Accessibility is not optional – it’s a baseline feature of every component.

Customizability and Theming

A component should be easy to restyle or adapt to different design requirements. Avoid hard-coding visual styles that cannot be overridden.

Provide mechanisms for theming and styling, such as CSS variables, clearly documented class names, or style props. Ideally, components come with sensible default styling but allow developers to customize appearance with minimal effort (for example, by passing a className or using design tokens).

This principle ensures components can fit into any brand or design system without “fighting” against default styles.

Lightweight and Performant

Components should be as lean as possible in terms of assets and dependencies. Avoid bloating a component with large library dependencies or overly complex logic, especially if that logic isn’t always needed.

Strive for good performance (both rendering and interaction) by minimizing unnecessary re-renders and using efficient algorithms for heavy tasks. If a component is data-intensive (like a large list or table), consider patterns like virtualization or incremental rendering, but keep such features optional.

Lightweight components are easier to maintain and faster for end users.

Transparency and Code Ownership

In open-source, consumers often benefit from having full visibility and control of component code. This spec encourages an “open-source first” mindset: components should not be black boxes.

When developers import or copy your component, they should be able to inspect how it works and modify it if needed. This principle underlies the emerging “copy-and-paste” distribution model (discussed later) where developers integrate component code directly into their projects.

By giving users ownership of the code, you increase trust and allow deeper customization.

Even if you distribute via a package, embrace transparency by providing source maps, readable code, and thorough documentation.

State

URL: /state

title: State description: How to manage state in a component, as well as merging controllable and uncontrolled state.

Building flexible components that work in both controlled and uncontrolled modes is a hallmark of professional components.

Uncontrolled State

Uncontrolled state is when the component manages its own state internally. This is the default usage pattern for most components.

For example, here's a simple Stepper component that manages its own state internally:

import { useState } from 'react';

export const Stepper = () => {
  const [value, setValue] = useState(0);

  return (
    <div>
      <p>{value}</p>
      <button onClick={() => setValue(value + 1)}>Increment</button>
    </div>
  );
};

Controlled State

Controlled state is when the component's state is managed by the parent component. Rather than keeping track of the state internally, we delegate this responsibility to the parent component.

Let's rework the Stepper component to be controlled by the parent component:

type StepperProps = {
  value: number;
  setValue: (value: number) => void;
};

export const Stepper = ({ value, setValue }: StepperProps) => (
  <div>
    <p>{value}</p>
    <button onClick={() => setValue(value + 1)}>Increment</button>
  </div>
);

Merging states

The best components support both controlled and uncontrolled state. This allows the component to be used in a variety of scenarios, and to be easily customized.

Radix UI maintain an internal utility for merging controllable and uncontrolled state called use-controllable-state. While not intended for public use, registries like Kibo UI have implemented this utility to build their own Radix-like components.

Let's install the hook:

npm install @radix-ui/react-use-controllable-state

This lightweight hook gives you the same state management patterns used internally by Radix UI's component library, ensuring your components behave consistently with industry standards.

The hook accepts three main parameters and returns a tuple with the current value and setter. Let's use it to merge the controlled and uncontrolled state of the Stepper component:

import { useControllableState } from '@radix-ui/react-use-controllable-state';

type StepperProps = {
  value: number;
  defaultValue: number;
  onValueChange: (value: number) => void;
};

export const Stepper = ({ value: controlledValue, defaultValue, onValueChange }: StepperProps) => {
  const [value, setValue] = useControllableState({
    prop: controlledValue, // The controlled value prop
    defaultProp: defaultValue, // Default value for uncontrolled mode
    onChange: onValueChange, // Called when value changes
  });

  return (
    <div>
      <p>{value}</p>
      <button onClick={() => setValue(value + 1)}>Increment</button>
    </div>
  );
};

Types

URL: /types

title: Types description: Extending the browser's native HTML elements for maximum customization.

When building reusable components, proper typing is essential for creating flexible, customizable, and type-safe interfaces. By following established patterns for component types, you can ensure your components are both powerful and easy to use.

Single Element Wrapping

Each exported component should ideally wrap a single HTML or JSX element. This principle is fundamental to creating composable, customizable components.

When a component wraps multiple elements, it becomes difficult to customize specific parts without prop drilling or complex APIs. Consider this anti-pattern:

const Card = ({ title, description, footer, ...props }) => (
  <div {...props}>
    <div className="card-header">
      <h2>{title}</h2>
      <p>{description}</p>
    </div>
    <div className="card-footer">{footer}</div>
  </div>
);

As we discussed in Composition, this approach creates several problems:

• You can't customize the header styling without adding more props
• You can't control the HTML elements used for title and description
• You're forced into a specific DOM structure

Instead, each layer should be its own component. This allows you to customize each layer independently, and to control the exact HTML elements used for the title and description.

The benefits of this approach are:

• Maximum customization - Users can style and modify each layer independently
• No prop drilling - Props go directly to the element that needs them
• Semantic HTML - Users can see and control the exact DOM structure
• Better accessibility - Direct control over ARIA attributes and semantic elements
• Simpler mental model - One component = one element

Extending HTML Attributes

Every component should extend the native HTML attributes of the element it wraps. This ensures users have full control over the underlying HTML element.

Basic Pattern

export type CardRootProps = React.ComponentProps<'div'> & {
  // Add your custom props here
  variant?: 'default' | 'outlined';
};

export const CardRoot = ({ variant = 'default', ...props }: CardRootProps) => <div {...props} />;

Common HTML Attribute Types

React provides type definitions for all HTML elements. Use the appropriate one for your component:

// For div elements
type DivProps = React.ComponentProps<'div'>;

// For button elements
type ButtonProps = React.ComponentProps<'button'>;

// For input elements
type InputProps = React.ComponentProps<'input'>;

// For form elements
type FormProps = React.ComponentProps<'form'>;

// For anchor elements
type LinkProps = React.ComponentProps<'a'>;

Handling Different Element Types

When a component can render as different elements, use generics or union types:

// Using discriminated unions
export type ButtonProps =
  | (React.ComponentProps<'button'> & { asChild?: false })
  | (React.ComponentProps<'div'> & { asChild: true });

// Or with a polymorphic approach
export type PolymorphicProps<T extends React.ElementType> = {
  as?: T;
} & React.ComponentPropsWithoutRef<T>;

Extending custom components

If you're extending an existing component, you can use the ComponentProps type to get the props of the component.

import type { ComponentProps } from 'react';

export type ShareButtonProps = ComponentProps<'button'>;

export const ShareButton = (props: ShareButtonProps) => <button {...props} />;

Exporting Types

Always export your component prop types. This makes them accessible to consumers for various use cases.

Exporting types enables several important patterns:

// 1. Extracting specific prop types
import type { CardRootProps } from '@/components/ui/card';
const variant = CardRootProps['variant'];

// 2. Extending components
export type ExtendedCardProps = CardRootProps & {
  isLoading?: boolean;
};

// 3. Creating wrapper components
const MyCard = (props: CardRootProps) => (
  <CardRoot {...props} className={cn('my-custom-class', props.className)} />
);

// 4. Type-safe prop forwarding
function useCardProps(): Partial<CardRootProps> {
  return {
    variant: 'outlined',
    className: 'custom-card',
  };
}

Your exported types should be named <ComponentName>Props. This is a convention that helps other developers understand the purpose of the type.

Best Practices

1. Always Spread Props Last

Ensure users can override any default props:

// ✅ Good - user props override defaults
<div className="default-class" {...props} />

// ❌ Bad - defaults override user props
<div {...props} className="default-class" />

2. Avoid Prop Name Conflicts

Don't use prop names that conflict with HTML attributes unless intentionally overriding:

// ❌ Bad - conflicts with HTML title attribute
export type CardProps = React.ComponentProps<'div'> & {
  title: string; // This conflicts with the HTML title attribute
};

// ✅ Good - use a different name
export type CardProps = React.ComponentProps<'div'> & {
  heading: string;
};

3. Document Custom Props

Add JSDoc comments to custom props for better developer experience:

export type DialogProps = React.ComponentProps<'div'> & {
  /** Whether the dialog is currently open */
  open: boolean;
  /** Callback when the dialog requests to be closed */
  onOpenChange: (open: boolean) => void;
  /** Whether to render the dialog in a portal */
  modal?: boolean;
};