---

name: react-component-dev description: Build React components with proper patterns, accessibility, and composition. Use when creating new components, refactoring existing ones, or reviewing component architecture. Covers forwardRef, prop design, accessibility, file organization, and testing approaches.

React Component Development

Patterns for building composable, accessible, well-structured React components.

Core Principles

1. Composition over configuration - Props enable customization, not enumerate options
2. Forwarding refs - Components that render DOM elements forward refs
3. Accessibility first - Keyboard, screen readers, reduced motion
4. Predictable APIs - Consistent prop patterns across components

Component Template

Copyimport { forwardRef, type ComponentPropsWithoutRef } from "react"
import { cn } from "@/lib/utils"

type ButtonProps = ComponentPropsWithoutRef<"button"> & {
  variant?: "default" | "outline" | "ghost"
  size?: "sm" | "md" | "lg"
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = "default", size = "md", ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={cn(
          "base-styles",
          variantStyles[variant],
          sizeStyles[size],
          className
        )}
        {...props}
      />
    )
  }
)
Button.displayName = "Button"

export { Button, type ButtonProps }

Prop Design

Always Include

Variant Props

Copy// Good: Union of literal types
variant?: "default" | "destructive" | "outline"

// Bad: Boolean props that multiply
isPrimary?: boolean
isDestructive?: boolean
isOutline?: boolean

Render Props / Slots

For complex customization:

Copytype DialogProps = {
  trigger?: ReactNode
  title: ReactNode
  description?: ReactNode
  children: ReactNode
  footer?: ReactNode
}

forwardRef Patterns

When to Use

• Component renders a single DOM element
• Component wraps another forwardRef component
• Users might need to call .focus(), measure, or attach refs

When to Skip

• Component renders multiple root elements
• Component is purely logic (hooks)
• Internal-only component never exposed to consumers

Extracting Ref Type

Copy// From DOM element
forwardRef<HTMLDivElement, Props>

// From another component
forwardRef<ComponentRef<typeof OtherComponent>, Props>

File Organization

Copycomponents/
└── button/
    ├── index.ts              # Re-export: export { Button } from "./button"
    ├── button.tsx            # Implementation
    ├── button.test.tsx       # Tests
    └── use-button-state.ts   # Complex state logic (if needed)

index.ts Pattern

Copyexport { Button, type ButtonProps } from "./button"

Keep index.ts as pure re-exports. No logic.

Accessibility Checklist

Keyboard

• All interactive elements focusable
• Focus order matches visual order
• Focus visible (outline or ring)
• Escape closes modals/dropdowns
• Enter/Space activates buttons
• Arrow keys for menu navigation

ARIA

Copy// Buttons with icons only
<button aria-label="Close dialog">
  <XIcon aria-hidden="true" />
</button>

// Loading states
<button disabled aria-busy={isLoading}>
  {isLoading ? <Spinner /> : "Submit"}
</button>

// Expandable content
<button aria-expanded={isOpen} aria-controls="panel-id">
  Toggle
</button>

Reduced Motion

Copyconst prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)")

// Or in CSS
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}

State Management

Local State

Use useState for:

• UI state (open/closed, selected)
• Form inputs (controlled)
• Ephemeral data (hover, focus)

Derived State

Copy// Bad: useEffect to sync
const [fullName, setFullName] = useState("")
useEffect(() => {
  setFullName(`${firstName} ${lastName}`)
}, [firstName, lastName])

// Good: useMemo
const fullName = useMemo(
  () => `${firstName} ${lastName}`,
  [firstName, lastName]
)

// Best: Just compute it (if cheap)
const fullName = `${firstName} ${lastName}`

Complex State

Copy// useReducer for multi-field updates
const [state, dispatch] = useReducer(reducer, initialState)

// Or extract to custom hook
const dialog = useDialogState()

Event Handlers

Prop Naming

Copy// Internal handler
const handleClick = () => { ... }

// Prop callbacks: on[Event]
type Props = {
  onClick?: () => void
  onOpenChange?: (open: boolean) => void
  onValueChange?: (value: string) => void
}

Composing Handlers

Copyconst Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ onClick, ...props }, ref) => {
    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
      // Internal logic
      trackClick()
      // Call user's handler
      onClick?.(e)
    }

    return <button ref={ref} onClick={handleClick} {...props} />
  }
)

Testing Approach

What to Test

• User interactions (click, type, submit)
• Accessibility (keyboard nav, ARIA states)
• Conditional rendering
• Error states

What NOT to Test

• Implementation details (internal state values)
• Styling (unless critical to function)
• Third-party library internals

Test Structure

Copydescribe("Button", () => {
  it("calls onClick when clicked", async () => {
    const handleClick = vi.fn()
    render(<Button onClick={handleClick}>Click me</Button>)

    await userEvent.click(screen.getByRole("button"))

    expect(handleClick).toHaveBeenCalledOnce()
  })

  it("is disabled when disabled prop is true", () => {
    render(<Button disabled>Disabled</Button>)

    expect(screen.getByRole("button")).toBeDisabled()
  })
})

Anti-Patterns

Prop Drilling

Copy// Bad: Passing props through many layers
<Parent value={x} onChange={y}>
  <Child value={x} onChange={y}>
    <GrandChild value={x} onChange={y} />

// Better: Context for deep trees
<ValueContext.Provider value={{ x, onChange: y }}>
  <Parent>
    <Child>
      <GrandChild /> {/* useContext inside */}

Premature Abstraction

Copy// Bad: Generic component nobody asked for
<FlexContainer direction="column" gap={4} align="center" justify="between">

// Good: Specific component for the use case
<CardHeader>

Boolean Prop Explosion

Copy// Bad
<Button primary large disabled loading>

// Good
<Button variant="primary" size="lg" disabled isLoading>

Quick Reference