JavaScript LocalStorage, SessionStorage
Aprende a usar localStorage y sessionStorage en JavaScript: almacena y lee datos, guarda objetos con JSON, escucha el evento storage y gestiona errores.
localStorage y sessionStorage son los dos objetos que conforman la Web Storage API — la forma más sencilla de conservar datos en el navegador entre recargas de página. Ambos almacenan información como pares clave/valor de tipo string vinculados al origen de la página (protocolo + host + puerto), y ambos exponen exactamente los mismos métodos. La única diferencia es cuánto tiempo viven los datos: localStorage los conserva indefinidamente, mientras que sessionStorage los descarta cuando se cierra la pestaña.
Esta página cubre la API completa, cómo almacenar objetos de forma segura con JSON, cómo reaccionar a cambios en otras pestañas con el evento storage, cómo gestionar los errores que estas APIs pueden lanzar y cuándo conviene usar un almacén más potente.
Nunca almacenes información sensible (contraseñas, tokens, datos personales) en localStorage ni en sessionStorage. Cualquier JavaScript que se ejecute en la página — incluidos los scripts de terceros — puede leerlos, y están completamente expuestos a ataques de cross-site scripting (XSS).
Entendiendo LocalStorage en JavaScript
localStorage almacena datos en el navegador del usuario de forma persistente, sin fecha de expiración. Los datos sobreviven al cierre de la pestaña, al cierre del navegador e incluso al reinicio del equipo — permanecen hasta que tu código (o el usuario) los borre. Los datos tienen alcance de origen, por lo que https://example.com no puede leer lo que almacenó https://other.com.
Cómo usar LocalStorage
La API es pequeña. Escribes un par con setItem(key, value), lo recuperas con getItem(key) y lo eliminas con removeItem(key). Leer una clave que no existe devuelve null (no undefined). La API también proporciona:
clear()— elimina todos los elementos de este origen.key(index)— obtiene el nombre de la clave en un índice determinado.length— el número de elementos almacenados.- un evento
storageal que puedes suscribirte para detectar cambios realizados en otras pestañas.
Las operaciones de almacenamiento son síncronas y se ejecutan en el hilo principal, por lo que leer o escribir grandes cantidades de datos puede bloquear el renderizado de la UI. Para datos más voluminosos o estructurados, es preferible usar IndexedDB.
Almacenar objetos y arrays con JSON
El error más común con Web Storage es olvidar que todo se almacena como string. Si pasas un object a setItem, se convierte silenciosamente con toString(), lo que produce el valor inútil "[object Object]". La solución es serializar con JSON.stringify al escribir y deserializar con JSON.parse al leer.
Aprende más sobre la conversión de valores a y desde strings en Trabajar con JSON.
Iterar sobre los elementos almacenados
Usa length junto con key(index) para recorrer todo el almacenamiento, o lee las claves con Object.keys:
Aplicación práctica: crear un selector de tema con LocalStorage
Considera un escenario en el que quieres guardar el tema preferido del usuario (claro u oscuro) para que persista entre sesiones. El siguiente ejemplo combina HTML, CSS y JavaScript en un único bloque por simplicidad.
<style>
:root {
--bg-color: #ffffff;
--text-color: #000000;
}
.dark {
--bg-color: #333333;
--text-color: #ffffff;
}
body {
background-color: var(--bg-color);
color: var(--text-color);
transition: background-color 0.5s, color 0.5s;
}
button {
padding: 10px 20px;
font-size: 16px;
cursor: pointer;
}
</style>
<body>
<button onclick="toggleTheme()">Toggle Theme</button>
<script>
function setTheme(themeName) {
localStorage.setItem('theme', themeName);
document.documentElement.className = themeName;
}
function toggleTheme() {
var currentTheme = localStorage.getItem('theme') === 'dark' ? 'dark' : 'light';
if (currentTheme === 'light') {
setTheme('dark');
} else {
setTheme('light');
}
}
function loadTheme() {
var theme = localStorage.getItem('theme') || 'light';
setTheme(theme);
}
// Initial theme load
loadTheme();
</script>
</body>Este script comprueba si hay un tema guardado en LocalStorage o usa 'light' por defecto. Luego aplica el tema asignando el nombre de clase al elemento HTML raíz, lo que permite a CSS ajustar los estilos en consecuencia.
SessionStorage: almacenamiento temporal de datos en JavaScript
Mientras que LocalStorage está diseñado para almacenar datos sin expiración, SessionStorage ofrece una forma de guardar datos durante la duración de la sesión de página. Los datos almacenados en SessionStorage se eliminan cuando termina la sesión de página — es decir, cuando se cierra la pestaña o ventana.
Cómo usar SessionStorage
A continuación se muestra un ejemplo básico de uso de SessionStorage. Los métodos y la sintaxis son idénticos a los de localStorage — solo difiere la duración. Un valor de sessionStorage también tiene alcance por pestaña: abrir el mismo sitio en una nueva pestaña comienza con sessionStorage vacío, mientras que una nueva pestaña comparte el mismo localStorage.
Ejemplo: usar SessionStorage para el autoguardado de datos de un formulario
Imagina que tienes un formulario que el usuario podría estar rellenando, pero existe el riesgo de que cierre el navegador accidentalmente. Puedes usar SessionStorage para guardar temporalmente los datos del formulario.
<body>
<div>Start writing an email address in the following input. Refresh the page in the middle of your typing, and you'll see that the page remembers what you entered before.</div>
<br />
<input type="email" id="email"/>
</body>
<script>
window.onload = function() {
const email = sessionStorage.getItem('email');
if (email) {
alert('email found from session storage: ' + email);
document.getElementById('email').value = email;
}
document.getElementById('email').oninput = function() {
sessionStorage.setItem('email', this.value);
};
};
</script>Este código carga automáticamente cualquier dirección de correo guardada cuando se carga la página y actualiza el elemento de SessionStorage cada vez que cambia el campo de correo electrónico. Para probarlo, haz clic en el botón "pruébalo tú mismo", escribe algo en el campo y luego recarga la página. El valor permanecerá después de recargar.
Considera siempre las limitaciones de tamaño antes de almacenar cualquier dato (normalmente alrededor de 5 MB tanto para LocalStorage como para SessionStorage).
LocalStorage vs. SessionStorage
Ambos objetos comparten la misma API, el mismo alcance por origen y el mismo modelo de almacenamiento exclusivamente de strings. Las diferencias prácticas se reducen a la duración y la visibilidad:
| Característica | localStorage | sessionStorage |
|---|---|---|
| Duración | Hasta que se borre explícitamente | Hasta que se cierre la pestaña |
| Sobrevive al reinicio de pestaña/navegador | Sí | No |
| Compartido entre pestañas del mismo origen | Sí | No (cada pestaña está aislada) |
| Capacidad | ~5 MB | ~5 MB |
Dispara el evento storage en otras pestañas | Sí | No |
Usa sessionStorage cuando los datos solo tengan sentido para la visita actual — un asistente de varios pasos, un formulario en curso, una posición de desplazamiento. Usa localStorage para preferencias y otros datos que deban persistir entre visitas.
Reaccionar a cambios con el evento storage
Cuando localStorage cambia en una pestaña, el navegador dispara un evento storage en todas las demás pestañas del mismo origen (pero no en la pestaña que realizó el cambio). Esta es la forma estándar de mantener varias pestañas sincronizadas — por ejemplo, cerrar la sesión del usuario en todas partes cuando cierra sesión en una pestaña.
window.addEventListener('storage', (event) => {
console.log('Key changed:', event.key);
console.log('Old value:', event.oldValue);
console.log('New value:', event.newValue);
console.log('URL of the page that made the change:', event.url);
});
// In another tab, this would trigger the handler above:
// localStorage.setItem('theme', 'dark');Las propiedades key, oldValue y newValue del objeto de evento te indican exactamente qué cambió. Ten en cuenta que sessionStorage no dispara este evento en otras pestañas, porque sus datos nunca se comparten.
Gestionar errores y casos extremos
Las llamadas de almacenamiento pueden lanzar excepciones, por lo que el código en producción no debe asumir que siempre tienen éxito:
- Cuota excedida. Escribir más allá del límite de ~5 MB lanza un
QuotaExceededError. Envuelve las escrituras entry...catchsi el valor podría ser grande. - Deshabilitado o modo privado. Algunos navegadores (o configuraciones de privacidad estrictas) hacen que el almacenamiento no esté disponible, e incluso acceder a
localStoragepuede lanzar unSecurityError. Detecta la funcionalidad antes de depender de ella.
Para conjuntos de datos más grandes, consultas complejas o almacenamiento de datos binarios, una base de datos del lado cliente más potente como IndexedDB es una mejor opción. Si necesitas que los datos se envíen automáticamente con cada solicitud al servidor, usa cookies en su lugar. También puedes comprobar la capacidad restante y solicitar persistencia con la Storage API.
Conclusión
LocalStorage y SessionStorage ofrecen opciones potentes para mejorar la experiencia del usuario mediante la gestión eficiente de datos en aplicaciones web. Al comprender sus capacidades y limitaciones, los desarrolladores pueden tomar decisiones informadas sobre cómo aprovechar mejor estas herramientas en sus proyectos.