useState Hook

Manage local component state with React's most fundamental hook.

Recipe

Quick-reference recipe card - copy-paste ready.

const [value, setValue] = useState<T>(initialValue)
 
// With lazy initializer (expensive computation)
const [value, setValue] = useState(() => computeExpensive())
 
// Updater function (when new state depends on previous)
setValue(prev => prev + 1)

When to reach for this: You need local, synchronous state in a single component.

Working Example

"use client";
 
import { useState } from "react";
 
export function Counter() {
  const [count, setCount] = useState(0);
 
  return (
    <div className="flex items-center gap-4">
      <button
        onClick={() => setCount(prev => prev - 1)}
        className="px-3 py-1 border rounded"
      >
        -
      </button>
      <span className="text-xl font-mono w-12 text-center">{count}</span>
      <button
        onClick={() => setCount(prev => prev + 1)}
        className="px-3 py-1 border rounded"
      >
        +
      </button>
    </div>
  );
}

What this demonstrates:

• Basic useState with a number
• Using the updater function prev => prev + 1 instead of setCount(count + 1) to avoid stale closure issues
• The component re-renders only when count changes

Deep Dive

How It Works

• useState returns a tuple: the current state value and a setter function
• On the initial render, the state is set to initialValue
• On subsequent renders, React returns the latest state
• When you call the setter, React schedules a re-render with the new value
• React batches multiple setState calls within the same event handler into a single re-render for performance

Parameters & Return Values

Variations

Object state:

const [form, setForm] = useState({ name: "", email: "" });
// Must spread to create new reference
setForm(prev => ({ ...prev, name: "Alice" }));

Array state:

const [items, setItems] = useState<string[]>([]);
setItems(prev => [...prev, "new item"]);

Lazy initializer (runs only on mount):

const [data, setData] = useState(() => {
  return JSON.parse(localStorage.getItem("key") ?? "null");
});

TypeScript Notes

// Type is inferred from initial value
const [count, setCount] = useState(0); // number
 
// Explicit generic for union types or null
const [user, setUser] = useState<User | null>(null);
 
// Explicit generic for complex types
const [items, setItems] = useState<Item[]>([]);

Gotchas

Things that will bite you. Each gotcha includes what goes wrong, why it happens, and the fix.

• Stale closure trap - Reading count inside a setTimeout or useEffect without it in the dependency array gives you the old value. Fix: Use the updater function setCount(prev => prev + 1).

• Object identity - setState({ ...obj }) creates a new reference every time, even if values haven't changed, causing unnecessary re-renders. Fix: Only spread when values actually change, or use useMemo for derived values.

• Lazy initializer pitfall - Passing computeExpensive() instead of () => computeExpensive() runs the function on every render, not just the first. Fix: Always wrap expensive computations in an arrow function.

• Batching gotcha - Calling setCount(count + 1) three times in a row results in only +1, not +3, because each call reads the same count. Fix: Use the updater function setCount(prev => prev + 1).

Alternatives

Other ways to solve the same problem - and when each is the better choice.

Why not just always use Zustand? Zustand adds a dependency and indirection. useState is zero-cost for local state - no provider, no store, no selectors. Use the simplest tool that works.

Real-World Example

From a production Next.js 15 / React 19 SaaS application (SystemsArchitect.io).

// Production example: FAQ edit form with multiple useState
// File: src/components/admin/faq-edit-form.tsx
'use client';
import { useState } from 'react';
 
interface FaqEditFormProps {
  faq: Faq & { category?: { id: string; slug: string; title: string } };
  onSave: (updatedFaq: Partial<Faq>) => Promise<void>;
  onCancel: () => void;
}
 
export default function FaqEditForm({ faq, onSave, onCancel }: FaqEditFormProps) {
  const [question, setQuestion] = useState(faq.question);
  const [answer, setAnswer] = useState(faq.answer);
  const [isActive, setIsActive] = useState(faq.isActive);
  const [sortOrder, setSortOrder] = useState(faq.sortOrder);
  const [isSaving, setIsSaving] = useState(false);
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsSaving(true);
    try {
      await onSave({ question, answer, isActive, sortOrder });
    } catch (error) {
      console.error('Error saving FAQ:', error);
    } finally {
      setIsSaving(false);
    }
  };
  // ... form JSX
}

What this demonstrates in production:

• TypeScript infers the type of each state variable from the initial value passed to useState. No explicit generic needed for useState(faq.question) since faq.question is already typed as string.
• The finally block ensures isSaving is reset to false on both success and failure. Without it, a failed save would leave the form stuck in a loading state.
• Partial<Faq> means only the changed fields are sent to the save handler, not the entire FAQ object. This keeps the API call lean.
• Five separate useState calls work fine for a form this size. For forms with more than 6-8 fields, consider useReducer or a form library like react-hook-form to reduce boilerplate and enable field-level validation.
• The isSaving flag is used to disable the submit button during the async operation, preventing double-submission.

FAQs

const [form, setForm] = useState({ name: "", email: "" });
 
// Correct: spread to create a new reference
setForm(prev => ({ ...prev, name: "Alice" }));
 
// Wrong: mutating the existing object
form.name = "Alice"; // No re-render

// Use an explicit generic for union types
const [user, setUser] = useState<User | null>(null);
 
// Later, TypeScript knows user can be null
if (user) {
  console.log(user.name); // narrowed to User
}

// Without the generic, TypeScript infers never[]
const [items, setItems] = useState<string[]>([]);
 
// Now you can push strings
setItems(prev => [...prev, "new item"]);

Related

• useReducer - for complex state logic with actions
• useRef - for mutable values that don't trigger re-renders
• Zustand Setup - when state needs to be shared globally