design-patterns

name	design-patterns
description	Frontend design patterns with React 19.2 and TypeScript 6 examples (Composition, Compound Components, Custom Hooks, Render Props, HOC, State Machines). Use when user asks "implement pattern", "use composition", or when designing reusable components.
argument-hint	[pattern-name]

Frontend Design Patterns Skill

Quick reference for common frontend design patterns in React 19.2 and TypeScript 6.

When to Use

• User asks to implement a specific pattern
• Designing reusable/extensible components
• Refactoring rigid or duplicated component code

Quick Reference: When to Use What

Problem	Pattern	Use When
Reusable UI with variations	Composition	Building flexible component APIs
Widget with shared internal state	Compound Component	Tabs, Accordion, Select, Menu
Reusable stateful logic	Custom Hook	Data fetching, form, media query
Flexible rendering delegation	Render Prop	Charts, virtual lists, headless UI
Cross-cutting behavior	HOC	Auth guards, error boundaries (rare)
Complex state transitions	State Machine	Multi-step forms, async flows
Type-safe event handling	Discriminated Union	Action reducers, event systems

---

Composition (Primary Pattern)

Problem: Build flexible components that work in many contexts.

// ✅ Composition with children and slots
type CardProps = {
  children: React.ReactNode;
  className?: string;
};

export function Card({ children, className }: CardProps) {
  return <div className={cn("rounded-lg border bg-white p-6 shadow-card", className)}>{children}</div>;
}

export function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="mb-4 border-b pb-4">{children}</div>;
}

export function CardTitle({ children }: { children: React.ReactNode }) {
  return <h3 className="text-lg font-semibold">{children}</h3>;
}

export function CardContent({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>;
}

// Usage — composable, flexible
<Card>
  <CardHeader>
    <CardTitle>Product Details</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Description here</p>
  </CardContent>
</Card>

---

Compound Component

Problem: Complex widget where sub-components share state.

"use client";

import { createContext, useContext, useState, type ReactNode } from "react";

// Types
type TabsContextValue = {
  activeTab: string;
  setActiveTab: (id: string) => void;
};

// Context
const TabsContext = createContext<TabsContextValue | null>(null);

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

// Root
type TabsProps = { defaultTab: string; children: ReactNode };

export function Tabs({ defaultTab, children }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultTab);

  return (
    <TabsContext value={{ activeTab, setActiveTab }}>
      <div>{children}</div>
    </TabsContext>
  );
}

// Tab list
export function TabList({ children }: { children: ReactNode }) {
  return <div role="tablist" className="flex gap-1 border-b">{children}</div>;
}

// Tab trigger
export function Tab({ id, children }: { id: string; children: ReactNode }) {
  const { activeTab, setActiveTab } = useTabs();
  const isActive = activeTab === id;

  return (
    <button
      type="button"
      role="tab"
      id={`tab-${id}`}
      aria-selected={isActive}
      aria-controls={`panel-${id}`}
      onClick={() => setActiveTab(id)}
      className={cn("px-4 py-2", isActive && "border-b-2 border-brand-500 font-semibold")}
    >
      {children}
    </button>
  );
}

// Tab panel
export function TabPanel({ id, children }: { id: string; children: ReactNode }) {
  const { activeTab } = useTabs();

  return (
    <div
      role="tabpanel"
      id={`panel-${id}`}
      aria-labelledby={`tab-${id}`}
      hidden={activeTab !== id}
      className="py-4"
    >
      {children}
    </div>
  );
}

// Usage
<Tabs defaultTab="overview">
  <TabList>
    <Tab id="overview">Overview</Tab>
    <Tab id="specs">Specifications</Tab>
    <Tab id="reviews">Reviews</Tab>
  </TabList>
  <TabPanel id="overview">Overview content</TabPanel>
  <TabPanel id="specs">Specs content</TabPanel>
  <TabPanel id="reviews">Reviews content</TabPanel>
</Tabs>

---

Custom Hook

Problem: Reusable stateful logic across components.

"use client";

import { useState, useCallback } from "react";

type UseToggleReturn = {
  isOpen: boolean;
  open: () => void;
  close: () => void;
  toggle: () => void;
};

export function useToggle(initial = false): UseToggleReturn {
  const [isOpen, setIsOpen] = useState(initial);

  return {
    isOpen,
    open: useCallback(() => setIsOpen(true), []),
    close: useCallback(() => setIsOpen(false), []),
    toggle: useCallback(() => setIsOpen((prev) => !prev), []),
  };
}

// Usage
function Dialog() {
  const { isOpen, open, close } = useToggle();

  return (
    <>
      <button onClick={open}>Open Dialog</button>
      {isOpen && <ModalContent onClose={close} />}
    </>
  );
}

Data Fetching Hook (with TanStack Query 5)

"use client";

import { useQuery, type UseQueryOptions } from "@tanstack/react-query";
import { z } from "zod/v4";

const ProductSchema = z.object({
  id: z.string(),
  name: z.string(),
  price: z.number(),
});

type Product = z.infer<typeof ProductSchema>;

export function useProduct(id: string, options?: Partial<UseQueryOptions<Product>>) {
  return useQuery({
    queryKey: ["product", id],
    queryFn: async () => {
      const res = await fetch(`/api/products/${id}`);
      if (!res.ok) throw new Error("Failed to fetch product");
      const data = await res.json();
      return ProductSchema.parse(data);
    },
    ...options,
  });
}

---

Render Prop (Headless Pattern)

Problem: Delegate rendering to consumer while providing behavior.

"use client";

type UseSelectReturn<T> = {
  selectedItem: T | null;
  isOpen: boolean;
  getToggleProps: () => Record<string, unknown>;
  getItemProps: (item: T) => Record<string, unknown>;
};

type SelectProps<T> = {
  items: T[];
  itemToString: (item: T) => string;
  children: (api: UseSelectReturn<T>) => React.ReactNode;
};

export function Select<T>({ items, itemToString, children }: SelectProps<T>) {
  const [selectedItem, setSelectedItem] = useState<T | null>(null);
  const [isOpen, setIsOpen] = useState(false);

  const api: UseSelectReturn<T> = {
    selectedItem,
    isOpen,
    getToggleProps: () => ({
      onClick: () => setIsOpen((prev) => !prev),
      "aria-expanded": isOpen,
      "aria-haspopup": "listbox",
    }),
    getItemProps: (item: T) => ({
      onClick: () => {
        setSelectedItem(item);
        setIsOpen(false);
      },
      role: "option",
      "aria-selected": selectedItem === item,
    }),
  };

  return <>{children(api)}</>;
}

// Usage
<Select items={countries} itemToString={(c) => c.name}>
  {({ selectedItem, isOpen, getToggleProps, getItemProps }) => (
    <div>
      <button {...getToggleProps()}>
        {selectedItem ? selectedItem.name : "Select country..."}
      </button>
      {isOpen && (
        <ul role="listbox">
          {countries.map((c) => (
            <li key={c.code} {...getItemProps(c)}>{c.name}</li>
          ))}
        </ul>
      )}
    </div>
  )}
</Select>

---

Discriminated Union (TypeScript Pattern)

Problem: Type-safe handling of multiple action types.

type Action =
  | { type: "ADD_ITEM"; payload: { id: string; name: string } }
  | { type: "REMOVE_ITEM"; payload: { id: string } }
  | { type: "UPDATE_QUANTITY"; payload: { id: string; quantity: number } }
  | { type: "CLEAR" };

function cartReducer(state: CartState, action: Action): CartState {
  switch (action.type) {
    case "ADD_ITEM":
      return { ...state, items: [...state.items, action.payload] };
    case "REMOVE_ITEM":
      return { ...state, items: state.items.filter((i) => i.id !== action.payload.id) };
    case "UPDATE_QUANTITY":
      return {
        ...state,
        items: state.items.map((i) =>
          i.id === action.payload.id ? { ...i, quantity: action.payload.quantity } : i,
        ),
      };
    case "CLEAR":
      return { ...state, items: [] };
    // TypeScript enforces exhaustiveness — no default needed
  }
}

---

Pattern Selection Guide

Situation	Pattern
Flexible UI layout	Composition (children + slots)
Widget with shared internal state	Compound Component
Reusable stateful logic	Custom Hook
Consumer controls rendering	Render Prop / Headless
Type-safe event/action handling	Discriminated Union
Complex async/state transitions	State Machine (XState)

Anti-Patterns to Avoid

Anti-Pattern	Problem	Better Approach
Prop drilling (5+ levels)	Hard to maintain	Zustand 5, Context, composition
HOC chains	Hard to type, debug	Custom Hooks
Barrel file re-exports	Breaks Turbopack tree-shaking	Direct imports
useEffect for derived state	Extra render, stale data	Compute during render
Global state for local data	Unnecessary coupling	useState, URL state
Over-abstraction	Complexity for no benefit	Simple components, extract later