React Component Development

Overview

This skill provides patterns, conventions, and best practices for building React components with TypeScript. It covers the full spectrum from primitive UI components to complex composed layouts, custom hooks, state management integration, and React 19 server components.

All patterns assume:

• React 18+ or React 19 (server components)
• TypeScript in strict mode
• Tailwind CSS for styling
• ESLint with @typescript-eslint and eslint-plugin-react-hooks

When to Use

Use this skill when:

• Creating new React components
• Refactoring existing components for better patterns
• Implementing custom hooks
• Setting up state management (local or global)
• Building compound component APIs
• Working with React 19 server components
• Implementing form handling logic

Trigger phrases:

• "Create a React component"
• "Build a custom hook"
• "Set up state management"
• "TypeScript component pattern"
• "Compound component"
• "Server component"
• "Form handling in React"

Component Patterns

Functional Component with TypeScript

The standard pattern for all components:

import { type HTMLAttributes, forwardRef } from "react";
import { cn } from "@/lib/utils";

interface CardProps extends HTMLAttributes<HTMLDivElement> {
  variant?: "default" | "outlined" | "elevated";
  padding?: "none" | "sm" | "md" | "lg";
}

const Card = forwardRef<HTMLDivElement, CardProps>(
  ({ className, variant = "default", padding = "md", children, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={cn(
          "rounded-lg",
          {
            "bg-card text-card-foreground": variant === "default",
            "border border-border bg-transparent": variant === "outlined",
            "bg-card text-card-foreground shadow-lg": variant === "elevated",
          },
          {
            "p-0": padding === "none",
            "p-4": padding === "sm",
            "p-6": padding === "md",
            "p-8": padding === "lg",
          },
          className
        )}
        {...props}
      >
        {children}
      </div>
    );
  }
);
Card.displayName = "Card";

export { Card, type CardProps };

Rules:

1. Always use explicit interface for props (not inline types)
2. Extend the appropriate HTML element attributes
3. Use forwardRef for any component that wraps a DOM element
4. Accept and merge className via cn() (clsx + tailwind-merge)
5. Spread remaining props onto the root element
6. Set displayName when using forwardRef
7. Export the props type alongside the component

Discriminated Union Props

Use when a component has mutually exclusive configurations:

interface LinkButtonProps {
  as: "link";
  href: string;
  target?: "_blank" | "_self";
}

interface ActionButtonProps {
  as?: "button";
  onClick: () => void;
  disabled?: boolean;
}

type ButtonProps = (LinkButtonProps | ActionButtonProps) & {
  variant?: "primary" | "secondary";
  size?: "sm" | "md" | "lg";
  children: React.ReactNode;
};

function Button(props: ButtonProps) {
  const { variant = "primary", size = "md", children, ...rest } = props;
  const classes = cn(/* ... */);

  if (props.as === "link") {
    return (
      <a href={props.href} target={props.target} className={classes}>
        {children}
      </a>
    );
  }

  return (
    <button onClick={props.onClick} disabled={props.disabled} className={classes}>
      {children}
    </button>
  );
}

Children Patterns

// String children only
interface BadgeProps {
  children: string;
}

// ReactNode (any renderable)
interface ContainerProps {
  children: React.ReactNode;
}

// Render function (render props)
interface DataListProps<T> {
  items: T[];
  children: (item: T, index: number) => React.ReactNode;
}

// Named slots via props
interface DialogProps {
  trigger: React.ReactNode;
  title: React.ReactNode;
  description?: React.ReactNode;
  children: React.ReactNode;
  footer?: React.ReactNode;
}

Custom Hooks

Pattern: useLocalStorage

import { useState, useEffect, useCallback } from "react";

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) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => {
      setStoredValue((prev) => {
        const nextValue = value instanceof Function ? value(prev) : value;
        window.localStorage.setItem(key, JSON.stringify(nextValue));
        return nextValue;
      });
    },
    [key]
  );

  const removeValue = useCallback(() => {
    window.localStorage.removeItem(key);
    setStoredValue(initialValue);
  }, [key, initialValue]);

  return [storedValue, setValue, removeValue] as const;
}

Pattern: useDebounce

import { useState, useEffect } from "react";

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;
}

Pattern: useFetch

import { useState, useEffect, useRef } from "react";

interface UseFetchResult<T> {
  data: T | null;
  error: Error | null;
  isLoading: boolean;
}

function useFetch<T>(url: string, options?: RequestInit): UseFetchResult<T> {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const abortControllerRef = useRef<AbortController | null>(null);

  useEffect(() => {
    const abortController = new AbortController();
    abortControllerRef.current = abortController;
    setIsLoading(true);

    fetch(url, { ...options, signal: abortController.signal })
      .then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
        return res.json() as Promise<T>;
      })
      .then((json) => {
        if (!abortController.signal.aborted) {
          setData(json);
          setError(null);
        }
      })
      .catch((err: unknown) => {
        if (err instanceof Error && err.name !== "AbortError") {
          setError(err);
        }
      })
      .finally(() => {
        if (!abortController.signal.aborted) {
          setIsLoading(false);
        }
      });

    return () => abortController.abort();
  }, [url]); // eslint-disable-line react-hooks/exhaustive-deps

  return { data, error, isLoading };
}

Pattern: useMediaQuery

import { useState, useEffect } from "react";

function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(false);

  useEffect(() => {
    const media = window.matchMedia(query);
    setMatches(media.matches);

    const listener = (event: MediaQueryListEvent) => setMatches(event.matches);
    media.addEventListener("change", listener);
    return () => media.removeEventListener("change", listener);
  }, [query]);

  return matches;
}

// Usage
const isMobile = useMediaQuery("(max-width: 768px)");
const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");

Hook Rules

1. Always prefix with use
2. Only call hooks at the top level (never inside conditions or loops)
3. Return a tuple as const for positional returns, or an object for named returns
4. Include cleanup in useEffect return (abort controllers, event listeners, timers)
5. Explicitly type the return value for complex hooks
6. Document the hook purpose with a JSDoc comment

State Management Patterns

Local State: useState

Use for simple, component-scoped state:

const [count, setCount] = useState(0);
const [user, setUser] = useState<User | null>(null);
const [items, setItems] = useState<Item[]>([]);

Complex Local State: useReducer

Use when state transitions are complex or interdependent:

interface FormState {
  values: Record<string, string>;
  errors: Record<string, string>;
  isSubmitting: boolean;
  isValid: boolean;
}

type FormAction =
  | { type: "SET_FIELD"; field: string; value: string }
  | { type: "SET_ERROR"; field: string; error: string }
  | { type: "CLEAR_ERRORS" }
  | { type: "SUBMIT_START" }
  | { type: "SUBMIT_SUCCESS" }
  | { type: "SUBMIT_FAILURE"; errors: Record<string, string> };

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "SET_FIELD":
      return {
        ...state,
        values: { ...state.values, [action.field]: action.value },
        errors: { ...state.errors, [action.field]: "" },
      };
    case "SET_ERROR":
      return {
        ...state,
        errors: { ...state.errors, [action.field]: action.error },
        isValid: false,
      };
    case "CLEAR_ERRORS":
      return { ...state, errors: {}, isValid: true };
    case "SUBMIT_START":
      return { ...state, isSubmitting: true };
    case "SUBMIT_SUCCESS":
      return { ...state, isSubmitting: false };
    case "SUBMIT_FAILURE":
      return { ...state, isSubmitting: false, errors: action.errors, isValid: false };
  }
}

Global State: Zustand

Use for shared state across unrelated components:

import { create } from "zustand";
import { persist } from "zustand/middleware";

interface AuthStore {
  user: User | null;
  token: string | null;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
}

const useAuthStore = create<AuthStore>()(
  persist(
    (set) => ({
      user: null,
      token: null,
      login: async (email, password) => {
        const res = await fetch("/api/auth/login", {
          method: "POST",
          body: JSON.stringify({ email, password }),
          headers: { "Content-Type": "application/json" },
        });
        const data = await res.json();
        set({ user: data.user, token: data.token });
      },
      logout: () => set({ user: null, token: null }),
    }),
    { name: "auth-storage" }
  )
);

// Usage in components
function UserMenu() {
  const user = useAuthStore((state) => state.user);
  const logout = useAuthStore((state) => state.logout);
  // Select individual fields to avoid unnecessary re-renders
}

Atomic State: Jotai

Use for fine-grained, composable state atoms:

import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";

// Primitive atoms
const countAtom = atom(0);
const nameAtom = atom("");

// Derived atom (read-only)
const doubleCountAtom = atom((get) => get(countAtom) * 2);

// Async derived atom
const userAtom = atom(async (get) => {
  const id = get(userIdAtom);
  const res = await fetch(`/api/users/${id}`);
  return res.json() as Promise<User>;
});

// Write-only atom (action)
const incrementAtom = atom(null, (get, set) => {
  set(countAtom, get(countAtom) + 1);
});

When to Use What

Composition Patterns

Compound Components

Components that share implicit state through context:

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

interface AccordionContextValue {
  openItems: Set<string>;
  toggle: (id: string) => void;
}

const AccordionContext = createContext<AccordionContextValue | null>(null);

function useAccordion() {
  const context = useContext(AccordionContext);
  if (!context) throw new Error("useAccordion must be used within <Accordion>");
  return context;
}

function Accordion({ children, multiple = false }: { children: ReactNode; multiple?: boolean }) {
  const [openItems, setOpenItems] = useState<Set<string>>(new Set());

  const toggle = (id: string) => {
    setOpenItems((prev) => {
      const next = new Set(multiple ? prev : []);
      if (prev.has(id)) {
        next.delete(id);
      } else {
        next.add(id);
      }
      return next;
    });
  };

  return (
    <AccordionContext.Provider value={{ openItems, toggle }}>
      <div role="region">{children}</div>
    </AccordionContext.Provider>
  );
}

function AccordionItem({ id, trigger, children }: { id: string; trigger: ReactNode; children: ReactNode }) {
  const { openItems, toggle } = useAccordion();
  const isOpen = openItems.has(id);

  return (
    <div>
      <button
        onClick={() => toggle(id)}
        aria-expanded={isOpen}
        aria-controls={`accordion-panel-${id}`}
      >
        {trigger}
      </button>
      {isOpen && (
        <div id={`accordion-panel-${id}`} role="region">
          {children}
        </div>
      )}
    </div>
  );
}

Accordion.Item = AccordionItem;
export { Accordion };

Render Props

Expose internal logic to parent for flexible rendering:

interface VirtualListProps<T> {
  items: T[];
  itemHeight: number;
  containerHeight: number;
  children: (item: T, style: React.CSSProperties) => React.ReactNode;
}

function VirtualList<T>({ items, itemHeight, containerHeight, children }: VirtualListProps<T>) {
  const [scrollTop, setScrollTop] = useState(0);
  const startIndex = Math.floor(scrollTop / itemHeight);
  const endIndex = Math.min(startIndex + Math.ceil(containerHeight / itemHeight) + 1, items.length);
  const visibleItems = items.slice(startIndex, endIndex);

  return (
    <div style={{ height: containerHeight, overflow: "auto" }} onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)}>
      <div style={{ height: items.length * itemHeight, position: "relative" }}>
        {visibleItems.map((item, i) =>
          children(item, {
            position: "absolute",
            top: (startIndex + i) * itemHeight,
            height: itemHeight,
            width: "100%",
          })
        )}
      </div>
    </div>
  );
}

Slots via Props

Named content areas without compound component complexity:

interface PageLayoutProps {
  header: React.ReactNode;
  sidebar?: React.ReactNode;
  children: React.ReactNode;
  footer?: React.ReactNode;
}

function PageLayout({ header, sidebar, children, footer }: PageLayoutProps) {
  return (
    <div className="flex min-h-screen flex-col">
      <header>{header}</header>
      <div className="flex flex-1">
        {sidebar && <aside className="w-64 border-r">{sidebar}</aside>}
        <main className="flex-1 p-6">{children}</main>
      </div>
      {footer && <footer>{footer}</footer>}
    </div>
  );
}

Error Boundaries

import { Component, type ErrorInfo, type ReactNode } from "react";

interface ErrorBoundaryProps {
  children: ReactNode;
  fallback: ReactNode | ((error: Error, reset: () => void) => ReactNode);
}

interface ErrorBoundaryState {
  error: Error | null;
}

class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
  state: ErrorBoundaryState = { error: null };

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { error };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.error("ErrorBoundary caught:", error, info.componentStack);
  }

  reset = () => this.setState({ error: null });

  render() {
    if (this.state.error) {
      return typeof this.props.fallback === "function"
        ? this.props.fallback(this.state.error, this.reset)
        : this.props.fallback;
    }
    return this.props.children;
  }
}

// Usage
<ErrorBoundary fallback={(error, reset) => (
  <div role="alert">
    <p>Something went wrong: {error.message}</p>
    <button onClick={reset}>Try again</button>
  </div>
)}>
  <MyComponent />
</ErrorBoundary>

Server Components (React 19 / Next.js App Router)

Server vs. Client Components

// Server Component (default in app/ directory) — NO "use client" directive
// Can: fetch data, access backend, read files, use async/await
// Cannot: useState, useEffect, event handlers, browser APIs

// app/users/page.tsx (server component)
async function UsersPage() {
  const users = await db.user.findMany();     // Direct DB access
  return <UserList users={users} />;
}

// Client Component — must have "use client" directive
// Can: useState, useEffect, event handlers, browser APIs
// Cannot: async component, direct DB/filesystem access

// components/user-search.tsx
"use client";
import { useState } from "react";

function UserSearch({ onSearch }: { onSearch: (query: string) => void }) {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Server Component Patterns

// Pass server data to client components via props
// app/dashboard/page.tsx (server)
import { DashboardChart } from "@/components/dashboard-chart"; // client component

async function DashboardPage() {
  const stats = await getStats(); // server-side fetch
  return <DashboardChart data={stats} />;
}

// Streaming with Suspense
import { Suspense } from "react";

async function Page() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<ChartSkeleton />}>
        <SlowChart />
      </Suspense>
    </div>
  );
}

When to Use "use client"

Add "use client" only when the component needs:

• useState, useReducer, useEffect, useRef, useContext
• Event handlers (onClick, onChange, etc.)
• Browser APIs (window, document, localStorage)
• Third-party libraries that use any of the above

Push "use client" as far down the tree as possible. Keep layouts and pages as server components; extract interactive pieces into small client components.

Form Handling

Controlled Form Pattern

"use client";
import { useState, type FormEvent } from "react";

interface ContactForm {
  name: string;
  email: string;
  message: string;
}

function ContactForm() {
  const [values, setValues] = useState<ContactForm>({ name: "", email: "", message: "" });
  const [errors, setErrors] = useState<Partial<ContactForm>>({});

  const validate = (): boolean => {
    const newErrors: Partial<ContactForm> = {};
    if (!values.name.trim()) newErrors.name = "Name is required";
    if (!values.email.includes("@")) newErrors.email = "Valid email required";
    if (!values.message.trim()) newErrors.message = "Message is required";
    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };

  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
    if (!validate()) return;
    await fetch("/api/contact", {
      method: "POST",
      body: JSON.stringify(values),
      headers: { "Content-Type": "application/json" },
    });
  };

  return (
    <form onSubmit={handleSubmit} noValidate>
      <label htmlFor="name">Name</label>
      <input
        id="name"
        value={values.name}
        onChange={(e) => setValues((v) => ({ ...v, name: e.target.value }))}
        aria-invalid={!!errors.name}
        aria-describedby={errors.name ? "name-error" : undefined}
      />
      {errors.name && <p id="name-error" role="alert">{errors.name}</p>}
      {/* ... other fields ... */}
      <button type="submit">Send</button>
    </form>
  );
}

react-hook-form Pattern

"use client";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const contactSchema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Valid email required"),
  message: z.string().min(10, "Message must be at least 10 characters"),
});

type ContactFormValues = z.infer<typeof contactSchema>;

function ContactForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<ContactFormValues>({
    resolver: zodResolver(contactSchema),
  });

  const onSubmit = async (data: ContactFormValues) => {
    await fetch("/api/contact", {
      method: "POST",
      body: JSON.stringify(data),
      headers: { "Content-Type": "application/json" },
    });
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <label htmlFor="name">Name</label>
      <input id="name" {...register("name")} aria-invalid={!!errors.name} />
      {errors.name && <p role="alert">{errors.name.message}</p>}

      <label htmlFor="email">Email</label>
      <input id="email" type="email" {...register("email")} aria-invalid={!!errors.email} />
      {errors.email && <p role="alert">{errors.email.message}</p>}

      <label htmlFor="message">Message</label>
      <textarea id="message" {...register("message")} aria-invalid={!!errors.message} />
      {errors.message && <p role="alert">{errors.message.message}</p>}

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Sending..." : "Send"}
      </button>
    </form>
  );
}

File Organization

src/
├── components/
│   ├── ui/                  # Primitive, reusable UI components
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── card.tsx
│   │   └── index.ts         # Barrel export
│   ├── layout/              # Layout structure components
│   │   ├── header.tsx
│   │   ├── footer.tsx
│   │   └── page-layout.tsx
│   ├── sections/            # Page-level content sections
│   │   ├── hero-section.tsx
│   │   └── features-grid.tsx
│   └── providers/           # Context providers
│       ├── theme-provider.tsx
│       └── auth-provider.tsx
├── hooks/                   # Custom hooks
│   ├── use-local-storage.ts
│   ├── use-debounce.ts
│   └── use-media-query.ts
├── stores/                  # Zustand / Jotai stores
│   ├── auth-store.ts
│   └── cart-store.ts
├── lib/                     # Utilities
│   ├── utils.ts             # cn(), formatters
│   └── validators.ts        # Zod schemas
└── types/                   # Shared TypeScript types
    ├── api.ts
    └── models.ts

Common Mistakes to Avoid

1. Overusing useEffect -- Derive state during render instead of syncing with effects. If you can calculate it from existing state/props, do so inline.
2. Missing dependency arrays -- Always include all dependencies in useEffect/useMemo/useCallback. Use the ESLint rule.
3. Premature memoization -- Don't wrap everything in React.memo, useMemo, or useCallback. Only optimize when you have measured a performance problem.
4. Prop drilling past 2-3 levels -- Use context or a state library instead.
5. Putting "use client" on layout components -- Keep layouts as server components. Extract interactive parts into small client child components.
6. Inline object/array props -- <Comp style={{ color: "red" }} /> creates a new object every render. Hoist to a constant or use useMemo if in a hot path.
7. Not handling loading and error states -- Every async operation needs loading, success, and error UI.

Skill Version: 1.0.0 Last Updated: 2026-03-11