// Sidebar ``` ### 2. Component Reusability One component can serve multiple purposes without creating variants: ```tsx // Text component used for different elements Page Title Body paragraph Inline text Form label ``` ### 3. Accessibility Improvements Choose elements that provide the best accessibility for each context: ```tsx // Link that looks like a button // Button that submits a form // Heading with button styles ``` ### 4. Style System Integration Maintain consistent styling while changing elements: ```tsx const Card = styled.div` padding: 1rem; border-radius: 8px; background: white; box-shadow: 0 2px 4px rgba(0,0,0,0.1); `; // Same styles, different elements Article content Section content List item content ``` ## Common Use Cases ### Typography Components Create flexible text components: ```tsx function Text({ as: Element = 'span', variant = 'body', ...props }) { const className = cn( 'text-base', variant === 'heading' && 'text-2xl font-bold', variant === 'body' && 'text-base', variant === 'caption' && 'text-sm text-gray-600', props.className ); return ; } // Usage Title Paragraph Caption ``` ### Layout Components Build semantic layouts: ```tsx function Flex({ as: Element = 'div', ...props }) { return ( ); } // Semantic HTML ``` ### Interactive Elements Handle different interaction types: ```tsx function Clickable({ as: Element = 'button', ...props }) { const isButton = Element === 'button'; const isAnchor = Element === 'a'; return ( ); } // Various clickable elements Button Link Div Button ``` ## TypeScript Best Practices ### Generic Component Types Create fully type-safe polymorphic components: ```tsx type PolymorphicRef = React.ComponentPropsWithRef["ref"]; type PolymorphicProps = Props & Omit, keyof Props> & { as?: E; }; // Component with full type safety function Component({ as, ...props }: PolymorphicProps) { const Element = as || "div"; return ; } ``` ### Inferring Props Automatically infer props based on the element: ```tsx // Props are inferred from the element type Home // ✅ href is valid Home // ❌ TS error: href not valid on div Submit // ✅ type is valid Submit // ❌ TS error ``` ### Discriminated Unions Use discriminated unions for element-specific props: ```tsx type ButtonProps = | { as: "button"; type?: "submit" | "button" | "reset" } | { as: "a"; href: string; target?: string } | { as: "div"; role: "button"; tabIndex: number }; function Button(props: ButtonProps & { children: React.ReactNode }) { const Element = props.as; return ; } ``` ## Best Practices ### 1. Default to Semantic Elements Choose meaningful defaults that represent the most common use case: ```tsx // ✅ Good defaults function Article({ as: Element = "article", ...props }) {} function Navigation({ as: Element = "nav", ...props }) {} function Heading({ as: Element = "h2", ...props }) {} // ❌ Too generic function Component({ as: Element = "div", ...props }) {} ``` ### 2. Document Valid Elements Clearly specify which elements are supported: ```tsx interface BoxProps { /** * The HTML element to render as * @default 'div' * @example 'section', 'article', 'aside', 'main' */ as?: "div" | "section" | "article" | "aside" | "main" | "header" | "footer"; } ``` ### 3. Validate Element Appropriateness Warn when inappropriate elements are used: ```tsx function Button({ as: Element = "button", ...props }) { if (__DEV__ && Element === "div" && !props.role) { console.warn( 'Button: When using as="div", provide role="button" for accessibility', ); } return ; } ``` ### 4. Handle Event Handlers Properly Ensure event handlers work across different elements: ```tsx function Interactive({ as: Element = "button", onClick, ...props }) { const handleKeyDown = (e: React.KeyboardEvent) => { if (Element !== "button" && (e.key === "Enter" || e.key === " ")) { onClick?.(e as any); } }; return ( ); } ``` ## Common Pitfalls ### Invalid HTML Nesting Be careful about HTML nesting rules: ```tsx // ❌ Invalid - button inside button // ❌ Invalid - div inside p Invalid nesting // ✅ Valid nesting Valid nesting ``` ### Missing Accessibility Attributes Remember to add appropriate ARIA attributes: ```tsx // ❌ Missing accessibility // ✅ Proper accessibility ``` ### Type Safety Loss Avoid using overly permissive types: ```tsx // ❌ Too permissive - no type safety function Component({ as: Element = "div", ...props }: any) { return ; } // ✅ Type safe function Component({ as, ...props }: PolymorphicProps) { const Element = as || "div"; return ; } ``` ### Performance Considerations Be aware of re-render implications: ```tsx // ❌ Creates new component on every render function Parent() { const CustomDiv = (props) =>

; return ; } // ✅ Stable component reference const CustomDiv = (props) =>

; function Parent() { return ; } ``` --- title: Core Principles description: When building modern UI components, it's important to keep these core principles in mind. type: conceptual summary: The foundational values behind the specification including composability, accessibility, customizability, performance, and transparency. prerequisites: - /definitions related: - /composition - /accessibility --- # Core Principles ## 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. `

); }; ``` ## 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: ```tsx title="stepper.tsx" type StepperProps = { value: number; setValue: (value: number) => void; }; export const Stepper = ({ value, setValue }: StepperProps) => (

{value}

); ``` ## 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](https://www.radix-ui.com/) maintain an internal utility for merging controllable and uncontrolled state called [`use-controllable-state`](https://github.com/radix-ui/primitives/tree/main/packages/react/use-controllable-state). While not intended for public use, registries like [Kibo UI](https://www.kibo-ui.com) have implemented this utility to build their own Radix-like components. Let's install the hook: npm pnpm yarn bun ```bash npm install @radix-ui/react-use-controllable-state ``` ```bash pnpm add @radix-ui/react-use-controllable-state ``` ```bash yarn add @radix-ui/react-use-controllable-state ``` ```bash bun add @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: ```tsx title="stepper.tsx" 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 (

{value}

); }; ``` --- title: Styling description: Conditional and composable styling with Tailwind classes. type: guide summary: Using tailwind-merge, clsx, the cn utility, and Class Variance Authority for conditional and composable component styling. prerequisites: - /composition related: - /design-tokens - /data-attributes --- # Styling Modern component libraries need flexible styling systems that can handle complex requirements without sacrificing developer experience. The combination of Tailwind CSS with intelligent class merging has emerged as a powerful pattern for building customizable components. This approach solves the fundamental tension between providing sensible defaults and allowing complete customization - a challenge that has plagued component libraries for years. ## The problem with traditional styling Traditional CSS approaches often lead to specificity wars, style conflicts, and unpredictable overrides. When you pass `className="bg-blue-500"` to a component that already has `bg-red-500`, which one wins? Without proper handling, both classes apply and the result depends on a lot of factors - CSS source order, the specificity of the classes, the bundler's class merging algorithm, etc. ## Merging classes intelligently The `tailwind-merge` library solves this by understanding Tailwind's class structure and intelligently resolving conflicts. When two classes target the same CSS property, it keeps only the last one. ```tsx title="Without tailwind-merge" // Both bg-red-500 and bg-blue-500 apply - unpredictable result

{title}