Component Patterns

Component Patterns — React/Next.js Component Design Patterns

A reference for component patterns, state management strategies, and project structure that the frontend-dev agent uses during frontend development.

Target Agent

frontend-dev — Applies this skill's patterns directly to component design and state management.

Component Design Patterns

1. Compound Components

A pattern where parent and child share implicit state.

Suited for: Tab, Accordion, Dropdown, Select, and other composite UI Structure: <Select> + <Select.Trigger> + <Select.Option> Key Concept: State sharing via Context, flexible composition through children

2. Render Props / Children as Function

Delegates rendering logic externally.

Suited for: Data fetching wrappers, mouse/scroll tracking Structure: <DataLoader render={(data) => <UI data={data} />} /> Note: Prefer Hook pattern when it can replace this

3. Custom Hooks (Extraction Pattern)

Extracts state logic into reusable Hooks.

Suited for: Form management, API calls, localStorage, debounce Naming: use prefix required — useForm, useDebounce, useAuth

4. Container/Presentational Separation

Separates data logic (Container) from UI presentation (Presentational).

Suited for: Large-scale apps, when testability is needed Container: Data fetch, state management, event handlers Presentational: Renders only from props, functionally pure

5. Higher-Order Component (HOC)

Wraps a component to add functionality.

Suited for: Auth guards, layout wrappers, error boundaries Naming: with prefix — withAuth, withLayout Note: Prefer Hook/Context when they can replace this

6. Headless Component

Provides behavior/state without UI.

Suited for: Sharing logic independent of design system Examples: headless useCombobox, useDialog, useTable

State Management Strategy Selection Guide

State Placement Decision Flow

Should this state be restorable from URL? → URL state
Is it server data? → React Query
Is it shared across multiple components? → Zustand
Is it internal to one component? → useState
Does it have complex transition logic? → useReducer

Next.js App Router Folder Structure

Recommended Structure (Feature-Based)

src/
├── app/                    # Next.js App Router
│   ├── (auth)/             # Auth-related route group
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   ├── (main)/             # Main route group
│   │   ├── dashboard/page.tsx
│   │   └── settings/page.tsx
│   ├── api/                # API Routes
│   │   └── [...]/route.ts
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Home
├── components/
│   ├── ui/                 # General UI (Button, Input, Modal)
│   └── features/           # Feature-specific components
│       ├── auth/
│       └── dashboard/
├── hooks/                  # Custom Hooks
├── lib/                    # Utilities, config
│   ├── api.ts              # API client
│   ├── auth.ts             # Auth utilities
│   └── utils.ts
├── stores/                 # Zustand stores
├── types/                  # TypeScript types
└── styles/                 # Global styles

Component File Conventions

Performance Optimization Patterns

Error Handling Patterns

Hierarchical Error Boundaries

RootErrorBoundary (global)
  └── LayoutErrorBoundary (per section)
      └── ComponentErrorFallback (individual)

API Error Handling

Accessibility (a11y) Checklist

• Alt text on all images
• Keyboard navigation (Tab, Enter, Escape)
• ARIA labels (aria-label, role)
• Color contrast 4.5:1 or above
• Visible focus indicator
• Screen reader testing
• Semantic HTML (button, nav, main, section)