Hook useState

Gestiona el estado local del componente con el hook más fundamental de React.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

const [value, setValue] = useState<T>(initialValue)
 
// Con inicializador perezoso (cálculo costoso)
const [value, setValue] = useState(() => computeExpensive())
 
// Función actualizadora (cuando el nuevo estado depende del anterior)
setValue(prev => prev + 1)

Cuándo usarlo: Necesitas estado local y síncrono en un único componente.

Ejemplo en Funcionamiento

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

Lo que esto demuestra:

• useState básico con un número
• Usar la función actualizadora prev => prev + 1 en lugar de setCount(count + 1) para evitar problemas de cierre obsoleto
• El componente se re-renderiza solo cuando count cambia

Análisis Profundo

Cómo Funciona

• useState devuelve una tupla: el valor de estado actual y una función setter
• En el renderizado inicial, el estado se establece en initialValue
• En renderizados posteriores, React devuelve el estado más reciente
• Cuando llamas al setter, React programa un re-renderizado con el nuevo valor
• React agrupa múltiples llamadas setState dentro del mismo manejador de eventos en un único re-renderizado para el rendimiento

Parámetros y Valores de Retorno

Variaciones

Estado de objeto:

const [form, setForm] = useState({ name: "", email: "" });
// Debe expandir para crear nueva referencia
setForm(prev => ({ ...prev, name: "Alice" }));

Estado de array:

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

Inicializador perezoso (se ejecuta solo al montar):

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

Notas de TypeScript

// El tipo se infiere del valor inicial
const [count, setCount] = useState(0); // number
 
// Genérico explícito para tipos unión o null
const [user, setUser] = useState<User | null>(null);
 
// Genérico explícito para tipos complejos
const [items, setItems] = useState<Item[]>([]);

Trampas

Cosas que te afectarán. Cada trampa incluye qué sale mal, por qué sucede y la solución.

• Trampa de cierre obsoleto - Leer count dentro de setTimeout o useEffect sin agregarlo al array de dependencias te da el valor antiguo. Solución: Usa la función actualizadora setCount(prev => prev + 1).

• Identidad del objeto - setState({ ...obj }) crea una nueva referencia cada vez, incluso si los valores no han cambiado, causando re-renderizados innecesarios. Solución: Solo expande cuando los valores realmente cambien, o usa useMemo para valores derivados.

• Trampa del inicializador perezoso - Pasar computeExpensive() en lugar de () => computeExpensive() ejecuta la función en cada renderizado, no solo en el primero. Solución: Siempre envuelve cálculos costosos en una función de flecha.

• Trampa de agrupamiento - Llamar a setCount(count + 1) tres veces seguidas resulta en solo +1, no +3, porque cada llamada lee el mismo count. Solución: Usa la función actualizadora setCount(prev => prev + 1).

Alternativas

Otras formas de resolver el mismo problema - y cuándo cada una es la mejor opción.

¿Por qué no usar siempre Zustand? Zustand añade una dependencia e indirección. useState es de costo cero para el estado local - sin provider, sin store, sin selectores. Usa la herramienta más simple que funcione.

Ejemplo del Mundo Real

De una aplicación SaaS de producción Next.js 15 / React 19 (SystemsArchitect.io).

// Ejemplo de producción: formulario de edición de FAQ con múltiples useState
// Archivo: 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);
    }
  };
  // ... JSX del formulario
}

Lo que esto demuestra en producción:

• TypeScript infiere el tipo de cada variable de estado del valor inicial pasado a useState. No se necesita genérico explícito para useState(faq.question) ya que faq.question ya está tipado como string.
• El bloque finally asegura que isSaving se reinicie a false tanto en éxito como en fallo. Sin él, un guardado fallido dejaría el formulario atrapado en un estado de carga.
• Partial<Faq> significa que solo los campos cambiados se envían al manejador de guardado, no el objeto FAQ completo. Esto mantiene la llamada API eficiente.
• Cinco llamadas useState separadas funcionan bien para un formulario de este tamaño. Para formularios con más de 6-8 campos, considera useReducer o una librería de formularios como react-hook-form para reducir boilerplate y habilitar validación a nivel de campo.
• El indicador isSaving se usa para desactivar el botón de envío durante la operación asíncrona, evitando envíos duplicados.

Preguntas Frecuentes

const [form, setForm] = useState({ name: "", email: "" });
 
// Correcto: expande para crear una nueva referencia
setForm(prev => ({ ...prev, name: "Alice" }));
 
// Incorrecto: mutar el objeto existente
form.name = "Alice"; // Sin re-renderizado

// Usa un genérico explícito para tipos unión
const [user, setUser] = useState<User | null>(null);
 
// Después, TypeScript sabe que user puede ser null
if (user) {
  console.log(user.name); // estrechado a User
}

// Sin el genérico, TypeScript infiere never[]
const [items, setItems] = useState<string[]>([]);
 
// Ahora puedes agregar strings
setItems(prev => [...prev, "new item"]);

Relacionado

• useReducer - para lógica de estado compleja con acciones
• useRef - para valores mutables que no disparan re-renderizados
• Zustand Setup - cuando el estado necesita ser compartido globalmente