templates/plate-template/.agents/skills/components/SKILL.md
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.
<button>, <nav>, <ul>) for built-in accessibilityaria-label, aria-current, aria-live) for proper announcementsARIA enhances semantic HTML for assistive technologies. Key rules:
Common Attributes:
role="button", role="navigation", role="alert")aria-checked, aria-expanded, aria-selected)aria-label, aria-describedby, aria-controls, aria-required, aria-invalid)Complex interactive components require specific accessibility patterns. For detailed implementations, consult WAI-ARIA Authoring Practices.
Modal/Dialog:
role="dialog", aria-modal="true", aria-labelledbyDropdown Menu:
role="menu" on container, role="menuitem" on itemsaria-haspopup="true", aria-expanded, aria-controlsTabs:
role="tablist" on container, role="tab" on buttons, role="tabpanel" on panelsaria-selected, aria-controls, aria-labelledbytabIndex={0/-1})Forms:
<label htmlFor> paired with input idaria-required, aria-invalid, aria-describedby for validationrole="alert"<fieldset> and <legend>:focus-visible for keyboard-only focus indicatorsdocument.activeElement before opening overlays, restore on closeAnnounce dynamic content changes to screen readers:
aria-live="polite" (waits), aria-live="assertive" (interrupts), role="alert" for errorsrole="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax, aria-label<meta name="viewport" content="width=device-width, initial-scale=1">)<label>, not disappearing placeholdersaria-label or visually hidden textaria-disabled instead of disabled to keep focusability and explain whyURL: /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.
asChildWhen 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>
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.
asChild prop in your component interfaces...props to receive merged behaviorasChild expects exactly one child element, not multipleURL: /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.
<Video src="https://www.youtube.com/watch?v=4KvbVq3Eg5w" />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.
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>
);
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} />;
The Trigger component is the element that opens the accordion when activated. It is responsible for:
asChild)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>
);
The Content component is the element that contains the accordion content. It is responsible for:
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>
);
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>
);
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.
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></AccordionRoot>
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>
For components with structured content areas, use semantic names that describe their purpose:
Header - Top section containing titles or controlsBody - Main content areaFooter - Bottom section for actions or metadata<DialogHeader>
</DialogHeader>
<DialogBody>
</DialogBody>
<DialogFooter>
</DialogFooter>
Components that provide information or context use descriptive suffixes:
Title - Primary heading or labelDescription - Supporting text or explanatory content<CardTitle>Project Statistics</CardTitle>
<CardDescription>
View your project's performance over time
</CardDescription>
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.
Add data-state attributes to expose component state:
Add data-slot attributes for stable component identification:
data-slot="submit-button")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 handlersA 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:
data-state (Tailwind arbitrary variants)data-slot with has-[] and [&_] selectorsURL: /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.
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:
Expectations:
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:
Expectations:
Patterns are a specific composition of primitives or components that are used to solve a specific UI/UX problem.
Examples:
Expectations.
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:
Expectations.
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:
Expectations:
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:
Expectations:
A helper exported for developer ergonomics or composition; not rendered UI.
Examples:
Expectations.
The public configuration surface of a component. Props are stable, typed, and documented with defaults and a11y ramifications.
Placeholders for caller-provided structure or content.
<Component.Slot> subcomponents.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.
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.
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.
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).
Implements behavior and accessibility without prescribing appearance. Requires the consumer to supply styling.
Ships with default visual design (CSS classes, inline styles, or tokens) but remains override-friendly (className merge, CSS vars, theming).
Discrete, documented style or behavior permutations exposed via props (e.g., size="sm|md|lg", tone="neutral|destructive"). Variants are not separate components.
Named, platform-agnostic values (e.g., --color-bg, --radius-md, --space-2) that parameterize visual design and support theming.
WAI-ARIA attributes that communicate semantics (role="menu"), state (aria-checked), and relationships (aria-controls, aria-labelledby).
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.
Rules for initial focus, roving focus, focus trapping, and focus return on teardown.
The component/library is published to a package registry (e.g., npm) and imported via a bundler. Favors versioned updates and dependency management.
Source code is integrated directly into the consumer's repository (often via a CLI). Favors ownership, customization, and zero extraneous runtime.
A curated index of artifacts (primitives, components, blocks, templates) with metadata, previews, and install/copy instructions. A registry is not necessarily a package manager.
Use this decision flow to name and place an artifact:
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:
--background, --foreground, --primary, etc.)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 <Author name="Hayden Bleasel" image="https://github.com/haydenbleasel.png" href="https://x.com/haydenbleasel" /> and <Author name="shadcn" image="https://github.com/shadcn.png" href="https://x.com/shadcn" />, 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.
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.
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.
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>
asThe 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>
There are two main approaches to implementing polymorphic components: a manual implementation and using Radix UI's Slot component.
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:
as prop with a default element typeRadix 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"
data-variant={variant}
data-size={size}
className={cn(itemVariants({ variant, size, className }))}
{...props}
/>
);
}
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:
as vs asChildas 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 |
Use as prop when:
Use asChild + Slot when:
<Container as="nav">, <Container as="main">, <Container as="aside">)<Text as="h1">, <Text as="p">, <Text as="label">)<Button as="a" href="/"> vs <Button as="button">)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).
as: Element = 'article' not 'div')<Box as="nav" aria-label="...">)anyURL: /principles
title: Core Principles description: When building modern UI components, it's important to keep these core principles in mind.
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.”)
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.
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.
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.
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.
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 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 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>
);
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>
);
};
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.
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:
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:
Every component should extend the native HTML attributes of the element it wraps. This ensures users have full control over the underlying HTML element.
export type CardRootProps = React.ComponentProps<'div'> & {
// Add your custom props here
variant?: 'default' | 'outlined';
};
export const CardRoot = ({ variant = 'default', ...props }: CardRootProps) => <div {...props} />;
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'>;
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>;
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} />;
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.
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" />
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;
};
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;
};