JavaScript LocalStorage, SessionStorage
Aprenda a usar localStorage e sessionStorage em JavaScript: armazene e leia dados, salve objetos com JSON, ouça o evento storage e lide com erros de cota.
localStorage e sessionStorage são os dois objetos que compõem a Web Storage API — a maneira mais simples de manter dados no navegador entre recarregamentos de página. Ambos armazenam informações como pares de chave/valor do tipo string vinculados à origem da página (protocolo + host + porta), e ambos expõem exatamente os mesmos métodos. A única diferença é por quanto tempo os dados persistem: localStorage os mantém indefinidamente, enquanto sessionStorage os descarta quando a aba é fechada.
Esta página abrange toda a API, como armazenar objetos com segurança usando JSON, como reagir a mudanças em outras abas com o evento storage, como tratar os erros que essas APIs podem lançar, e quando recorrer a um armazenamento mais robusto.
Nunca armazene informações sensíveis (senhas, tokens, dados pessoais) em localStorage ou sessionStorage. Qualquer JavaScript em execução na página — incluindo scripts de terceiros — pode lê-los, e eles ficam totalmente expostos a ataques de cross-site scripting (XSS).
Entendendo o LocalStorage em JavaScript
localStorage armazena dados no navegador do usuário de forma persistente, sem data de expiração. Os dados sobrevivem ao fechamento da aba, ao fechamento do navegador e até à reinicialização da máquina — permanecem até que seu código (ou o usuário) os apague. Os dados têm escopo de origem, portanto https://example.com não pode ler o que https://other.com armazenou.
Como Usar o LocalStorage
A API é pequena. Você grava um par com setItem(key, value), lê de volta com getItem(key) e o exclui com removeItem(key). Ler uma chave que não existe retorna null (não undefined). A API também fornece:
clear()— remove todos os itens desta origem.key(index)— obtém o nome da chave em um determinado índice.length— o número de itens armazenados.- um evento
storageque você pode ouvir para detectar mudanças feitas em outras abas.
As operações de armazenamento são síncronas e executam na thread principal, portanto ler ou gravar grandes quantidades de dados pode bloquear a renderização da interface. Para dados maiores ou estruturados, prefira o IndexedDB.
Armazenando Objetos e Arrays com JSON
O erro mais comum com o Web Storage é esquecer que tudo é armazenado como string. Se você passar um object para setItem, ele será convertido silenciosamente com toString(), resultando no valor inútil "[object Object]". A solução é serializar com JSON.stringify ao gravar e JSON.parse ao ler.
Saiba mais sobre como converter valores de e para strings em Trabalhando com JSON.
Iterando Sobre Itens Armazenados
Use length em conjunto com key(index) para percorrer tudo no armazenamento, ou leia as chaves com Object.keys:
Aplicação Prática: Criando um Alternador de Tema com LocalStorage
Considere um cenário em que você deseja salvar o tema preferido do usuário (claro ou escuro) para que ele persista entre sessões. O exemplo a seguir combina HTML, CSS e JavaScript em um único bloco para simplificar.
<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 verifica se há um tema armazenado no LocalStorage ou usa 'light' como padrão. Em seguida, aplica o tema definindo o nome da classe do elemento HTML raiz, permitindo que o CSS ajuste os estilos de acordo.
SessionStorage: Armazenamento Temporário de Dados em JavaScript
Enquanto o LocalStorage é projetado para armazenar dados sem expiração, o SessionStorage oferece uma forma de armazenar dados durante a sessão da página. Os dados armazenados no SessionStorage são apagados quando a sessão da página termina — ou seja, quando a aba ou janela é fechada.
Como Usar o SessionStorage
Abaixo está um exemplo básico do uso do SessionStorage. Os métodos e a sintaxe são idênticos aos do localStorage — apenas o tempo de vida difere. Um valor de sessionStorage também tem escopo por aba: abrir o mesmo site em uma nova aba começa com um sessionStorage vazio, enquanto uma nova aba compartilha o mesmo localStorage.
Exemplo: Usando SessionStorage em um Recurso de Auto-Save de Formulário
Imagine que você tem um formulário que o usuário pode estar preenchendo, mas há o risco de fechar o navegador por acidente. Você pode usar o SessionStorage para salvar temporariamente os dados do formulário.
<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 carrega automaticamente qualquer e-mail salvo quando a página é carregada e atualiza o item do SessionStorage sempre que o campo de e-mail é alterado. Para testá-lo, clique no botão "try it yourself", escreva algo no campo de entrada e atualize a página. O valor permanecerá após a atualização.
Considere sempre as limitações de tamanho antes de armazenar qualquer dado (normalmente em torno de 5 MB para LocalStorage e SessionStorage).
LocalStorage vs. SessionStorage
Ambos os objetos compartilham a mesma API, o mesmo escopo por origem e o mesmo modelo de armazenamento somente de string. As diferenças práticas se resumem ao tempo de vida e à visibilidade:
| Recurso | localStorage | sessionStorage |
|---|---|---|
| Tempo de vida | Até ser explicitamente apagado | Até a aba ser fechada |
| Sobrevive ao reinício da aba/navegador | Sim | Não |
| Compartilhado entre abas da mesma origem | Sim | Não (cada aba é isolada) |
| Capacidade | ~5 MB | ~5 MB |
Dispara o evento storage em outras abas | Sim | Não |
Use sessionStorage quando os dados forem relevantes apenas para a visita atual — um assistente de várias etapas, um formulário em andamento, uma posição de rolagem. Use localStorage para preferências e outros dados que devem persistir entre visitas.
Reagindo a Mudanças com o Evento storage
Quando localStorage é alterado em uma aba, o navegador dispara um evento storage em todas as outras abas da mesma origem (mas não na aba que fez a mudança). Esta é a maneira padrão de manter várias abas sincronizadas — por exemplo, desconectar o usuário em todos os lugares quando ele se desconecta em uma aba.
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');As propriedades key, oldValue e newValue do objeto de evento informam exatamente o que mudou. Observe que sessionStorage não dispara este evento em outras abas, pois seus dados nunca são compartilhados.
Tratando Erros e Casos Extremos
As chamadas de armazenamento podem lançar exceções, portanto o código em produção não deve presumir que sempre terão sucesso:
- Cota excedida. Gravar além do limite de ~5 MB lança um
QuotaExceededError. Envolva as gravações emtry...catchse o valor puder ser grande. - Desabilitado ou modo privado. Alguns navegadores (ou configurações de privacidade rígidas) tornam o armazenamento indisponível, e até mesmo acessar
localStoragepode lançar umSecurityError. Faça a detecção do recurso antes de depender dele.
Para conjuntos de dados maiores, consultas complexas ou armazenamento de dados binários, um banco de dados do lado do cliente mais robusto, como o IndexedDB, é uma opção melhor. Se você precisar que os dados sejam enviados automaticamente com cada requisição ao servidor, use cookies. Você também pode verificar a capacidade restante e solicitar persistência com a Storage API.
Conclusão
LocalStorage e SessionStorage oferecem opções poderosas para melhorar a experiência do usuário ao gerenciar dados de forma eficiente em aplicações web. Ao entender suas capacidades e limitações, os desenvolvedores podem tomar decisões informadas sobre como melhor utilizar essas ferramentas em seus projetos.