Qué es el localStorage y cómo guardar datos en el navegador

¿Alguna vez has notado que ciertas páginas web recuerdan tus preferencias aunque cierres el navegador y vuelvas a abrirlas? El modo oscuro que activaste sigue activo, tu carrito de compras no está vacío, el formulario que llenaste a medias todavía tiene tus datos. Eso, en muchos casos, es obra del localStorage.

En este artículo aprenderás qué es el localStorage, cómo funciona, cómo usarlo con JavaScript desde cero y cuándo tiene sentido usarlo frente a otras alternativas de almacenamiento en el navegador.

Qué es el localStorage

El localStorage es una API del navegador que permite guardar datos en el dispositivo del usuario de forma persistente. A diferencia de las variables de JavaScript, que desaparecen cuando recargas la página, los datos guardados en localStorage permanecen ahí hasta que el usuario o la aplicación los eliminen explícitamente.

Algunas características clave:

• Los datos persisten aunque se cierre la pestaña, el navegador o se reinicie el dispositivo.
• Tiene un límite de almacenamiento de aproximadamente 5 MB por dominio, dependiendo del navegador.
• Solo almacena texto. Cualquier otro tipo de dato (números, arrays, objetos) debe convertirse a string antes de guardarlo.
• Es específico del origen (protocolo + dominio + puerto). Una página no puede acceder al localStorage de otra.
• No se envía al servidor con cada petición HTTP, a diferencia de las cookies.
• Solo es accesible desde JavaScript en el navegador. No existe en Node.js ni en otros entornos.

localStorage vs sessionStorage vs cookies

El navegador ofrece varias formas de guardar datos en el cliente. Es importante saber cuál usar en cada caso:

La regla general es: usa localStorage para preferencias y datos que deben persistir entre sesiones, sessionStorage para datos temporales que solo necesitas mientras el usuario está en la página, y cookies cuando necesitas que el servidor también tenga acceso a esa información (como tokens de autenticación).

Los métodos básicos del localStorage

La API del localStorage es muy simple. Solo tiene cuatro métodos principales y una propiedad para contar los elementos guardados.

Guardar un dato: setItem()

localStorage.setItem("clave", "valor");

El primer argumento es la clave (el nombre con el que identificarás el dato) y el segundo es el valor. Ambos deben ser strings.

localStorage.setItem("nombre", "Ana");
localStorage.setItem("tema", "oscuro");
localStorage.setItem("idioma", "es");

Leer un dato: getItem()

const valor = localStorage.getItem("clave");

Devuelve el valor guardado bajo esa clave, o null si la clave no existe.

const nombre = localStorage.getItem("nombre");
console.log(nombre); // "Ana"

const algo = localStorage.getItem("clave-inexistente");
console.log(algo); // null

Eliminar un dato: removeItem()

localStorage.removeItem("clave");

Elimina la clave y su valor del localStorage.

localStorage.removeItem("tema");
console.log(localStorage.getItem("tema")); // null

Limpiar todo: clear()

localStorage.clear();

Elimina todos los datos guardados en el localStorage para ese dominio. Úsalo con precaución.

Contar los elementos: length

console.log(localStorage.length); // número de claves guardadas

Obtener una clave por su posición: key()

const primeraClave = localStorage.key(0);
console.log(primeraClave); // nombre de la primera clave guardada

Guardar y leer objetos y arrays

Aquí está el punto más importante y el que genera más confusión en principiantes: el localStorage solo almacena strings. Si intentas guardar un objeto o un array directamente, se convertirá a su representación en texto, que generalmente es [object Object] y pierde toda su estructura.

// ❌ Incorrecto: el objeto se convierte a "[object Object]"
const usuario = { nombre: "Ana", edad: 25 };
localStorage.setItem("usuario", usuario);

console.log(localStorage.getItem("usuario")); // "[object Object]"

La solución es usar JSON.stringify() para convertir el objeto a string antes de guardarlo, y JSON.parse() para convertirlo de vuelta al leerlo.

// ✅ Correcto: convertir a JSON antes de guardar
const usuario = { nombre: "Ana", edad: 25, activo: true };
localStorage.setItem("usuario", JSON.stringify(usuario));

// Leer y convertir de vuelta a objeto
const usuarioGuardado = JSON.parse(localStorage.getItem("usuario"));
console.log(usuarioGuardado.nombre); // "Ana"
console.log(usuarioGuardado.edad);   // 25

Lo mismo aplica para arrays:

const tareas = ["Estudiar JavaScript", "Hacer ejercicio", "Leer un libro"];
localStorage.setItem("tareas", JSON.stringify(tareas));

const tareasGuardadas = JSON.parse(localStorage.getItem("tareas"));
console.log(tareasGuardadas[0]); // "Estudiar JavaScript"

Manejo de errores al leer del localStorage

Cuando lees un valor que no existe, getItem() devuelve null. Si intentas hacer JSON.parse(null), el resultado es null, lo cual no genera error. Pero si el valor guardado está corrupto o mal formado, JSON.parse() lanzará una excepción.

Es buena práctica envolver las lecturas del localStorage en un bloque try/catch:

function leerDeStorage(clave) {
  try {
    const valor = localStorage.getItem(clave);
    return valor ? JSON.parse(valor) : null;
  } catch (error) {
    console.error("Error al leer del localStorage:", error);
    return null;
  }
}

const usuario = leerDeStorage("usuario");
console.log(usuario);

Ejemplo práctico: guardar preferencias de tema

Uno de los usos más comunes del localStorage es guardar la preferencia de tema (claro u oscuro) del usuario para que se mantenga entre visitas.

// Leer el tema guardado al cargar la página
const temaGuardado = localStorage.getItem("tema") || "claro";
document.body.classList.add(temaGuardado);

// Función para cambiar el tema y guardarlo
function cambiarTema() {
  const temaActual = localStorage.getItem("tema") || "claro";
  const nuevoTema = temaActual === "claro" ? "oscuro" : "claro";

  document.body.classList.remove(temaActual);
  document.body.classList.add(nuevoTema);

  localStorage.setItem("tema", nuevoTema);
}

// Asociar la función a un botón
const boton = document.getElementById("btn-tema");
boton.addEventListener("click", cambiarTema);

La próxima vez que el usuario abra la página, el tema guardado se aplicará automáticamente antes de que el usuario tenga que hacer nada.

Ejemplo práctico: lista de tareas persistente

Un caso más completo: una lista de tareas que se guarda automáticamente en localStorage y se recupera al recargar la página.

// Cargar tareas guardadas o inicializar con array vacío
function cargarTareas() {
  const datos = localStorage.getItem("tareas");
  return datos ? JSON.parse(datos) : [];
}

// Guardar el array de tareas en localStorage
function guardarTareas(tareas) {
  localStorage.setItem("tareas", JSON.stringify(tareas));
}

// Agregar una nueva tarea
function agregarTarea(texto) {
  const tareas = cargarTareas();
  tareas.push({ id: Date.now(), texto: texto, completada: false });
  guardarTareas(tareas);
}

// Marcar una tarea como completada
function completarTarea(id) {
  const tareas = cargarTareas();
  const tarea = tareas.find((t) => t.id === id);
  if (tarea) {
    tarea.completada = true;
    guardarTareas(tareas);
  }
}

// Eliminar una tarea
function eliminarTarea(id) {
  const tareas = cargarTareas().filter((t) => t.id !== id);
  guardarTareas(tareas);
}

// Uso
agregarTarea("Aprender localStorage");
agregarTarea("Construir un proyecto con JavaScript");
console.log(cargarTareas()); // Array con las dos tareas

Escuchar cambios en el localStorage con el evento storage

Si tu aplicación tiene varias pestañas abiertas del mismo dominio, puedes sincronizar datos entre ellas usando el evento storage. Este evento se dispara en todas las pestañas del mismo origen cuando el localStorage cambia, excepto en la pestaña que realizó el cambio.

window.addEventListener("storage", function (evento) {
  console.log("Clave modificada:", evento.key);
  console.log("Valor anterior:", evento.oldValue);
  console.log("Valor nuevo:", evento.newValue);
  console.log("URL de origen:", evento.url);
});

Esto es útil, por ejemplo, para detectar en tiempo real si el usuario cerró sesión en otra pestaña y reflejar ese cambio en todas las demás.

Crear una función utilitaria reutilizable

En proyectos reales, es una buena práctica encapsular las operaciones del localStorage en funciones utilitarias que manejen la serialización y los errores de forma centralizada:

const storage = {
  guardar(clave, valor) {
    try {
      localStorage.setItem(clave, JSON.stringify(valor));
    } catch (error) {
      console.error("Error al guardar en localStorage:", error);
    }
  },

  leer(clave, valorPorDefecto = null) {
    try {
      const item = localStorage.getItem(clave);
      return item !== null ? JSON.parse(item) : valorPorDefecto;
    } catch (error) {
      console.error("Error al leer del localStorage:", error);
      return valorPorDefecto;
    }
  },

  eliminar(clave) {
    localStorage.removeItem(clave);
  },

  limpiar() {
    localStorage.clear();
  }
};

// Uso
storage.guardar("configuracion", { tema: "oscuro", idioma: "es", notificaciones: true });
const config = storage.leer("configuracion", { tema: "claro" });
console.log(config.tema); // "oscuro"

Limitaciones y cuándo no usar localStorage

El localStorage es muy útil, pero tiene limitaciones importantes que debes conocer antes de usarlo:

No guardes información sensible

El localStorage es accesible desde cualquier JavaScript que se ejecute en la página. Si un atacante logra inyectar código malicioso (ataque XSS), puede leer todo lo que tengas guardado. Por eso, nunca guardes en localStorage:

• Contraseñas.
• Tokens de autenticación (usa cookies HttpOnly para eso).
• Números de tarjetas de crédito.
• Información personal sensible.

No es una base de datos

Con su límite de ~5 MB, el localStorage no está diseñado para almacenar grandes volúmenes de datos. Si necesitas guardar más información en el navegador, considera IndexedDB, que es una base de datos completa disponible en el navegador y puede almacenar gigabytes de datos estructurados.

No está disponible en todos los contextos

En modo incógnito algunos navegadores limitan o bloquean el localStorage. En entornos donde las cookies de terceros están bloqueadas también puede haber restricciones. Siempre es buena práctica verificar que está disponible antes de usarlo:

function localStorageDisponible() {
  try {
    const prueba = "__prueba__";
    localStorage.setItem(prueba, prueba);
    localStorage.removeItem(prueba);
    return true;
  } catch (error) {
    return false;
  }
}

if (localStorageDisponible()) {
  localStorage.setItem("dato", "valor");
} else {
  console.warn("localStorage no está disponible en este entorno");
}

Es síncrono

A diferencia de otras APIs modernas del navegador, el localStorage opera de forma síncrona. En aplicaciones que leen y escriben muchos datos constantemente, esto puede generar pequeñas ralentizaciones. Para esos casos, IndexedDB con su API asíncrona es una mejor opción.

Casos de uso recomendados

El localStorage es la herramienta perfecta para estos escenarios:

• Preferencias de usuario: tema claro/oscuro, idioma, tamaño de fuente.
• Estado de la interfaz: menú abierto o cerrado, pestañas activas, filtros seleccionados.
• Borradores de formularios para no perder el progreso si el usuario recarga accidentalmente.
• Historial de búsquedas recientes.
• Datos de una aplicación pequeña que no requiere servidor, como una lista de tareas o un bloc de notas.
• Caché de datos no sensibles para evitar peticiones repetidas a una API.

Conclusión

El localStorage es una de las APIs más simples y más útiles que tiene el navegador. Con solo cuatro métodos puedes guardar, leer y eliminar datos que persisten entre sesiones, sin necesidad de servidor ni base de datos.

Los puntos clave para recordar: siempre usa JSON.stringify() y JSON.parse() para guardar y leer objetos o arrays, nunca almacenes información sensible, y ten presente el límite de almacenamiento de ~5 MB.

Si estás construyendo tus primeros proyectos con JavaScript, el localStorage te permite añadir persistencia de datos de forma sencilla y sin depender de un backend. Es un gran recurso para que tus proyectos de portafolio se sientan más completos y reales.

Para seguir avanzando, te recomendamos leer nuestros artículos sobre qué es el DOM y cómo manipularlo y sobre qué es JavaScript y para qué se usa, donde encontrarás la base necesaria para sacarle el máximo partido a lo que aprendiste aquí.