localStorage em JavaScript (com exemplos práticos)
localStorage em JavaScript
localStorage em JavaScript: exemplos, JSON, limites | We.Inc
Teste o localStorage em um playground ao vivo e copie exemplos que funcionam para preferências salvas, um carrinho e um tema, além de JSON, limites de tamanho, erros e sincronização entre abas.
O localStorage é um armazenamento de chave e valor por origem no navegador que mantém os dados depois que a aba e o navegador são fechados. Você chama setItem(key, value) para salvar, getItem(key) para ler, removeItem(key) para apagar e clear() para esvaziar. Os valores são sempre strings, então envolva objetos com JSON.stringify e JSON.parse.
Toda a Storage API em um cartão
- Membro
- O que faz
- Retorna
- setItem(key, value)
- Adiciona ou sobrescreve uma entrada
- getItem(key)
- Lê uma entrada
- A string, ou null se não existir
- removeItem(key)
- Apaga uma entrada
- clear()
- Apaga todas as entradas desta origem
- key(index)
- Nome da entrada em uma posição
- Uma string ou null
- Quantas entradas estão armazenadas
- Um número
A maioria dos bugs com localStorage vem de três surpresas: tudo vira string, a chamada pode lançar um erro e os dados ficam presos a uma origem exata. O playground abaixo grava no seu próprio navegador para você ver essas regras acontecendo, e depois os exemplos mostram padrões seguros para preferências, um carrinho de compras e uma troca de tema.
- Digite uma chave e um valor no playground e clique em Salvar. A entrada é gravada no storage desta página no seu navegador.
- Clique em Ler para buscá-la de volta, ou em Apagar para removê-la. A tabela abaixo lista todas as chaves que este site guarda para você.
- Mude o tipo de valor para Objeto para ver como JSON.stringify o transforma em texto e JSON.parse o reconstrói.
- Copie qualquer exemplo abaixo para o seu projeto. Cada um envolve o acesso ao storage em try e catch.
- Use prefixos nas chaves, por exemplo shop:cart, para que dois scripts na mesma origem não sobrescrevam um ao outro.
- Guarde um número de versão junto dos dados estruturados para poder migrar formatos antigos depois de um redesign.
- Nunca guarde senhas, tokens ou dados pessoais aqui. Qualquer script rodando na página pode ler todas as entradas.
- Leia uma vez na inicialização e mantenha o valor em memória. Cada chamada é síncrona e bloqueia a thread principal.
- Use sessionStorage quando os dados devem sumir assim que o visitante fechar a aba.
Perguntas frequentes
Quantos dados o localStorage comporta?
O MDN documenta um limite de 5 MiB de localStorage por origem nos navegadores atuais, com outros 5 MiB separados para o sessionStorage. As strings são armazenadas em UTF-16, então o número de caracteres que cabe é menor do que a contagem de bytes sugere. Gravar além do limite lança um QuotaExceededError.
O localStorage expira?
Não. As entradas ficam até o seu código removê-las ou o visitante limpar os dados do site. Em uma janela anônima, o navegador as apaga quando a última aba anônima é fechada. Se você precisa de expiração, guarde um timestamp junto do valor e confira na leitura.
Por que getItem retorna "[object Object]"?
setItem transforma em string tudo o que você passa. Um objeto simples vira o texto [object Object] e os dados se perdem. Salve JSON.stringify(obj) e leia de volta com JSON.parse.
O localStorage é compartilhado entre http e https?
Não. O storage pertence a uma origem, que é o esquema, o host e a porta juntos. http://example.com e https://example.com têm cada um o próprio storage separado, e o mesmo vale para subdomínios.
Como sincronizo mudanças entre abas do navegador?
Escute o evento storage no window. Ele dispara nos outros documentos abertos da mesma origem quando um deles altera um valor, e traz key, oldValue e newValue. A aba que fez a mudança não o recebe.
localStorage ou cookies?
Cookies vão para o servidor a cada requisição e servem para sessões. O localStorage nunca sai do navegador, comporta mais e serve para estado da interface, como um tema, um rascunho ou uma barra lateral recolhida.
Quando o localStorage é a ferramenta certa
- Ele brilha com pequenas memórias da interface: a última aba que a pessoa abriu, um banner dispensado, um rascunho de mensagem, uma unidade preferida. Perder esses dados é um leve incômodo, não um prejuízo, o que combina com a facilidade com que as pessoas os apagam.
- Ele não serve para nada que você não pode perder, nada que outro dispositivo precise ver ou coleções grandes. Pedidos ficam em um servidor, e dados estruturados grandes ficam no IndexedDB, que é assíncrono.
Por que toda chamada precisa de try e catch
- Os navegadores lançam um SecurityError quando o storage está bloqueado, por exemplo quando o visitante desativou os dados de sites, e páginas abertas por URLs file: se comportam de forma diferente entre navegadores. Um storage cheio lança um QuotaExceededError na gravação.
- Uma pequena função que retorna um valor padrão em caso de falha mantém o resto da página funcionando. Todos os exemplos abaixo usam esse formato.
Mantendo tudo seguro
- Qualquer coisa no storage pode ser lida por qualquer script da origem, incluindo um widget de terceiros ou código injetado por um bug de cross-site scripting. Trate o conteúdo como público para a página.
- Os dados lidos de volta também são entrada não confiável. Valide antes de usar e exiba como texto, nunca como HTML.
localStorage vs sessionStorage vs cookies
Escolha o armazenamento por quanto tempo os dados devem durar e quem precisa deles
- localStorage
- sessionStorage
- Cookie
- Duração
- Até ser removido
- Até a aba fechar
- Até a data de expiração
- Compartilhado entre abas
- Sim, mesma origem
- Não, só uma aba
- Sim
- Enviado ao servidor
- Não
- Não
- Sim, a cada requisição
- Tamanho (número do MDN)
- 5 MiB por origem
- 5 MiB por origem
- Pequeno, limites definidos por navegador
- Estilo da API
- Síncrona
- Síncrona
- String document.cookie
Exemplos para copiar
Funções seguras de leitura e gravação com JSON
Um único lugar trata storage bloqueado, cota cheia e JSON quebrado, para que o resto do seu código nunca precise tratar.
Lembrar as preferências de um visitante
Os padrões são mesclados com o que foi salvo, então adicionar uma nova configuração depois não quebra dados salvos antigos.
Um pequeno carrinho de compras que sobrevive a um reload
Cada mudança cria um novo array e o grava de volta. O servidor continua decidindo os preços no checkout.
Escolha de tema com fallback do sistema
Se nada foi salvo, vale a configuração do sistema operacional. Rode isso cedo no head para evitar um flash do tema errado.
Entradas que expiram
O localStorage não tem expiração nativa, então guarde o prazo junto do valor e descarte entradas vencidas na leitura.
Manter abas abertas sincronizadas
O evento storage chega a todas as outras abas da mesma origem, então um contador do carrinho pode ser atualizado sem reload.
O storage está bloqueado neste navegador, então toda chamada lançaria um erro. Seu código precisa de um fallback.
Lançou {name}: {message}
Digite uma chave primeiro.
{call} armazenou {n} caracteres.
{call} retornou null: não existe entrada com essa chave.
JSON.parse devolveu: {value}
O texto armazenado não é JSON: {value}
{call} retornou a string {value}
{call} concluído.
{n} entradas do playground removidas. As outras chaves deste site não foram tocadas.
Playground de {name}
Salve, leia e apague entradas no seu próprio navegador e veja todas as chaves que este site armazena. As chaves do playground começam com demo: para nunca conflitarem com as do site.
Chave
Valor
Tipo de valor
String simples
Objeto (JSON)
Salvar
Ler
Apagar
Limpar chaves do playground
Os resultados aparecem aqui.
Entradas do playground armazenadas no seu navegador ({n})
String armazenada
Comece o teste grátis · Teste grátis de 7 dias, $0 hoje
Relacionados: Guias
- O for no JavaScript, e qual loop usar em cada caso
- Objetos em JavaScript e por que aparece [object Object]
- Recarregar a página com JavaScript
- Rolar até um elemento com JavaScript
- Ordenar um array de objetos em JavaScript
- Métodos de string em JavaScript
- Sites em JavaScript e rastreadores de IA
- Criar Site de Joalheria
Produto
Para quem é
- Para agências
- Para freelancers
- Para provedores de hospedagem
- Para plataformas SaaS
- Para startups
- Serviços financeiros
- Soluções para saúde
Recursos
Recursos
- Blog
- Central de Ajuda
- Ferramentas gratuitas para empresas
- Free UI Components
- Modelos
- Coleções de modelos
- Exemplos de sites
- Guias
- Comparações
- Alternativas
- Os melhores
- Avaliações
- Guias de preços
- Casos de uso
- Glossário e guias
- Integrações
- Desenvolvedores
- Benchmark
- Windows App