React Component Development Skill

React Component Development

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

Core Principles

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

Component Template

import { 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

| Prop | Type | Purpose | |------|------|---------| | className | string | Style composition | | children | ReactNode | Content (when applicable) | | ...rest | native props | Forward all valid HTML attributes |

Variant Props

// 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:

type 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

// From DOM element
forwardRef<HTMLDivElement, Props>

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

File Organization

components/
└── 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

export { 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

// 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

const 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

// 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

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

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

Event Handlers

Prop Naming

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

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

Composing Handlers

const 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

describe("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

// 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

// 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

// Bad
<Button primary large disabled loading>

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

Quick Reference

| Pattern | When | |---------|------| | forwardRef | Wrapping DOM elements | | ComponentPropsWithoutRef<"tag"> | Inheriting native props | | cn() | Merging classNames | | as const | Literal type inference | | useImperativeHandle | Custom ref APIs (rare) | | React.Children | Manipulating children (avoid if possible) |

Agent Skills: React Component Development

Skill Files