# React Patterns

> Guide React component architecture — composition patterns, custom hooks, props design, state management, and error boundaries. Use this skill whenever the user is designing React components, refactoring component structure, creating custom hooks, deciding how to manage state, working with context providers, building form components, or asking about React best practices and patterns. Also trigger when the user mentions component composition, render props, compound components, controlled vs uncontrolled components, or lifting state.

- Skill: `shiven0504/react-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shiven0504/react-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shiven0504/react-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Shiven0504 (https://skillmd.com/u/shiven0504)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shiven0504/react-patterns

---


# React Component Patterns

Help users write well-structured React components with clean composition, proper state management, and maintainable patterns. Assumes Next.js + Tailwind CSS environment.

## Component Composition

### Prefer composition over props overload

Instead of a component with many conditional props, compose smaller focused components together.

**Avoid — prop-heavy monolith:**
```tsx
<Card
  title="Revenue"
  subtitle="Monthly"
  icon="chart"
  showBorder
  variant="highlighted"
  headerAction={<Button>Export</Button>}
  footer={<Link>View details</Link>}
/>
```

**Prefer — composable parts:**
```tsx
<Card>
  <Card.Header>
    <Card.Title>Revenue</Card.Title>
    <Card.Subtitle>Monthly</Card.Subtitle>
    <Button>Export</Button>
  </Card.Header>
  <Card.Body>
    <RevenueChart data={data} />
  </Card.Body>
  <Card.Footer>
    <Link href="/revenue">View details</Link>
  </Card.Footer>
</Card>
```

### Compound Components

Use compound components when a group of components share implicit state and always work together (tabs, accordions, selects, menus).

```tsx
"use client"
import { createContext, useContext, useState, type ReactNode } from 'react'

type TabsContextType = { activeTab: string; setActiveTab: (id: string) => void }
const TabsContext = createContext<TabsContextType | null>(null)

function useTabs() {
  const ctx = useContext(TabsContext)
  if (!ctx) throw new Error('Tab components must be used within <Tabs>')
  return ctx
}

function Tabs({ defaultTab, children }: { defaultTab: string; children: ReactNode }) {
  const [activeTab, setActiveTab] = useState(defaultTab)
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      <div>{children}</div>
    </TabsContext.Provider>
  )
}

function TabList({ children }: { children: ReactNode }) {
  return <div className="flex gap-1 border-b border-gray-200">{children}</div>
}

function Tab({ id, children }: { id: string; children: ReactNode }) {
  const { activeTab, setActiveTab } = useTabs()
  return (
    <button
      onClick={() => setActiveTab(id)}
      className={`px-4 py-2 text-sm font-medium border-b-2 -mb-px transition-colors ${
        activeTab === id
          ? 'border-blue-600 text-blue-600'
          : 'border-transparent text-gray-500 hover:text-gray-700'
      }`}
    >
      {children}
    </button>
  )
}

function TabPanel({ id, children }: { id: string; children: ReactNode }) {
  const { activeTab } = useTabs()
  if (activeTab !== id) return null
  return <div className="py-4">{children}</div>
}

Tabs.List = TabList
Tabs.Tab = Tab
Tabs.Panel = TabPanel

export { Tabs }
```

Usage:
```tsx
<Tabs defaultTab="overview">
  <Tabs.List>
    <Tabs.Tab id="overview">Overview</Tabs.Tab>
    <Tabs.Tab id="analytics">Analytics</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel id="overview">Overview content</Tabs.Panel>
  <Tabs.Panel id="analytics">Analytics content</Tabs.Panel>
</Tabs>
```

## Props Design

### Keep props interfaces focused

Each component should accept only the props it needs. Use TypeScript to be explicit:

```tsx
interface UserCardProps {
  name: string
  email: string
  avatarUrl?: string
  role: 'admin' | 'member' | 'viewer'
}

export function UserCard({ name, email, avatarUrl, role }: UserCardProps) {
  // ...
}
```

### Spread HTML attributes for wrapper components

For components that wrap native elements, extend the native element's props:

```tsx
import { type ButtonHTMLAttributes, forwardRef } from 'react'

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', className, children, ...props }, ref) => {
    const base = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors'
    const variants = {
      primary: 'bg-blue-600 text-white hover:bg-blue-700',
      secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
      ghost: 'text-gray-600 hover:bg-gray-100',
    }
    const sizes = {
      sm: 'px-3 py-1.5 text-sm',
      md: 'px-4 py-2 text-sm',
      lg: 'px-6 py-3 text-base',
    }

    return (
      <button
        ref={ref}
        className={`${base} ${variants[variant]} ${sizes[size]} ${className ?? ''}`}
        {...props}
      >
        {children}
      </button>
    )
  }
)
Button.displayName = 'Button'
export { Button }
```

### children vs render props

- Use `children` for most cases — it's simpler and more readable.
- Use render props (or render function children) when the child needs data from the parent:

```tsx
<DataLoader url="/api/users">
  {({ data, isLoading }) =>
    isLoading ? <Skeleton /> : <UserList users={data} />
  }
</DataLoader>
```

## Custom Hooks

### Extract logic, not JSX

Custom hooks should encapsulate stateful logic and side effects, returning values and callbacks — not components.

```tsx
function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value)

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay)
    return () => clearTimeout(timer)
  }, [value, delay])

  return debouncedValue
}
```

```tsx
function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue
    try {
      const item = window.localStorage.getItem(key)
      return item ? JSON.parse(item) : initialValue
    } catch {
      return initialValue
    }
  })

  const setValue = (value: T | ((val: T) => T)) => {
    const valueToStore = value instanceof Function ? value(storedValue) : value
    setStoredValue(valueToStore)
    window.localStorage.setItem(key, JSON.stringify(valueToStore))
  }

  return [storedValue, setValue] as const
}
```

### Hook naming conventions

- Always prefix with `use`
- Name should describe what data/behavior it provides: `useAuth`, `useMediaQuery`, `useClickOutside`
- Return consistent shapes: `[value, setter]` for simple state, `{ data, error, isLoading }` for async

## State Management

### Start simple, scale as needed

1. **Local state (useState)** — for state that belongs to one component
2. **Lifted state** — when a sibling needs access, lift to the nearest common parent
3. **Context** — for state shared across a subtree (theme, auth, locale)
4. **URL state (searchParams)** — for state that should be shareable/bookmarkable (filters, pagination, tabs)
5. **External store (Zustand, Jotai)** — for complex client-side state shared across many components

### Context — avoid the "god provider" anti-pattern

Split contexts by domain rather than creating one massive AppContext:

```tsx
// Separate concerns into focused providers
<AuthProvider>
  <ThemeProvider>
    <ToastProvider>
      {children}
    </ToastProvider>
  </ThemeProvider>
</AuthProvider>
```

Each provider manages its own slice of state. Components only subscribe to the contexts they need, which avoids unnecessary re-renders.

### URL state for user-facing state

Filters, sort order, pagination, and active tabs should live in the URL so users can share and bookmark views:

```tsx
"use client"
import { useSearchParams, useRouter, usePathname } from 'next/navigation'

function useQueryState(key: string, defaultValue: string) {
  const searchParams = useSearchParams()
  const router = useRouter()
  const pathname = usePathname()

  const value = searchParams.get(key) ?? defaultValue

  const setValue = (newValue: string) => {
    const params = new URLSearchParams(searchParams.toString())
    if (newValue === defaultValue) {
      params.delete(key)
    } else {
      params.set(key, newValue)
    }
    router.replace(`${pathname}?${params.toString()}`)
  }

  return [value, setValue] as const
}
```

## Controlled vs Uncontrolled Components

### Support both patterns

Build form components that work controlled (parent owns the state) or uncontrolled (component owns its own state via `defaultValue`):

```tsx
interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
  label: string
  error?: string
}

export function Input({ label, error, id, ...props }: InputProps) {
  const inputId = id ?? label.toLowerCase().replace(/\s+/g, '-')
  return (
    <div>
      <label htmlFor={inputId} className="block text-sm font-medium text-gray-700 mb-1">
        {label}
      </label>
      <input
        id={inputId}
        className={`w-full px-3 py-2 border rounded-lg text-sm transition-colors
          ${error
            ? 'border-red-500 focus:ring-red-500'
            : 'border-gray-300 focus:ring-blue-500'
          } focus:outline-none focus:ring-2`}
        {...props}
      />
      {error && <p className="mt-1 text-sm text-red-600">{error}</p>}
    </div>
  )
}
```

Works both ways:
```tsx
// Controlled
<Input label="Email" value={email} onChange={e => setEmail(e.target.value)} />

// Uncontrolled
<Input label="Email" defaultValue="user@example.com" />
```

## Error Boundaries

### Wrap sections, not the entire app

Place error boundaries around independent sections so a failure in one area doesn't crash everything:

```tsx
"use client"
import { Component, type ReactNode } from 'react'

interface Props {
  children: ReactNode
  fallback?: ReactNode
}

interface State {
  hasError: boolean
  error: Error | null
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error }
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? (
        <div className="p-4 bg-red-50 border border-red-200 rounded-lg">
          <p className="text-red-800 font-medium">Something went wrong</p>
          <p className="text-red-600 text-sm mt-1">{this.state.error?.message}</p>
        </div>
      )
    }
    return this.props.children
  }
}
```

Usage:
```tsx
<div className="grid grid-cols-2 gap-4">
  <ErrorBoundary fallback={<WidgetError />}>
    <RevenueChart />
  </ErrorBoundary>
  <ErrorBoundary fallback={<WidgetError />}>
    <UserActivity />
  </ErrorBoundary>
</div>
```

## Lists and Keys

### Use stable, unique identifiers as keys

```tsx
// Good — stable ID from data
{users.map(user => <UserCard key={user.id} user={user} />)}

// Avoid — index as key (breaks with reordering, insertion, deletion)
{users.map((user, i) => <UserCard key={i} user={user} />)}
```

Index keys are acceptable only for static lists that never change order.

## Conditional Rendering

### Keep it readable

```tsx
// Simple boolean — use &&
{isAdmin && <AdminPanel />}

// Binary choice — use ternary
{isLoading ? <Skeleton /> : <Content data={data} />}

// Multiple conditions — use early returns or a mapping
function StatusBadge({ status }: { status: 'active' | 'pending' | 'inactive' }) {
  const styles = {
    active: 'bg-green-100 text-green-800',
    pending: 'bg-yellow-100 text-yellow-800',
    inactive: 'bg-gray-100 text-gray-800',
  }

  return (
    <span className={`px-2 py-1 text-xs font-medium rounded-full ${styles[status]}`}>
      {status}
    </span>
  )
}
```