Como armazenar objetos em localStorage e sessionStorage: guia completo

Por que o localStorage não funciona com objetos (e como corrigir isso)

Você já tentou salvar um objeto no localStorage e recebeu uma string "[object Object]"? Se sim — você não está sozinho. Essa pergunta no Stack Overflow acumulou milhares de visualizações, e hoje vamos entender de uma vez por todas como armazenar objetos corretamente no armazenamento web HTML5.

O problema é que localStorage e sessionStorage só funcionam com strings. Quando você escreve:

localStorage.setItem('user', {name: 'Ana', age: 25});

O JavaScript automaticamente chama o método .toString() do objeto, resultando em uma string inútil. Mas existe uma maneira comprovada de contornar essa limitação — a serialização via JSON.

O que é serialização e por que ela é necessária

Serialização é o processo de converter uma estrutura de dados complexa (objeto, array) em uma string que pode ser salva ou transmitida. O processo inverso é chamado de desserialização (transformar a string de volta em objeto).

Em JavaScript, dois métodos são responsáveis por isso:

• JSON.stringify() — transforma um objeto em uma string JSON
• JSON.parse() — transforma uma string JSON de volta em um objeto

São esses métodos — a chave para resolver o problema de armazenamento de objetos no localStorage e sessionStorage.

Tutorial passo a passo: salvando um objeto no localStorage

Passo 1. Criando um objeto

const user = {  id: 101,  name: 'Maria',  email: 'maria@example.com',  preferences: {    theme: 'dark',    notifications: true  },  tags: ['javascript', 'react', 'python']};

Passo 2. Serializando em JSON

const userJSON = JSON.stringify(user);console.log(userJSON); // {"id":101,"name":"Maria","email":"maria@example.com","preferences":{"theme":"dark","notifications":true},"tags":["javascript","react","python"]}

Passo 3. Salvando no localStorage

localStorage.setItem('currentUser', userJSON);

Passo 4. Recuperando e desserializando

const savedUserJSON = localStorage.getItem('currentUser');const savedUser = JSON.parse(savedUserJSON);

console.log(savedUser.name); // Mariaconsole.log(savedUser.preferences.theme); // darkconsole.log(savedUser.tags[0]); // javascript

Pronto! Agora você tem um objeto completo com todas as estruturas aninhadas.

sessionStorage: a mesma coisa, mas com uma diferença

sessionStorage funciona exatamente como localStorage, mas com uma diferença importante: os dados duram apenas até o fechamento da aba. Assim que você fecha a aba do navegador — tudo é removido.

// SalvandosessionStorage.setItem('tempData', JSON.stringify({step: 3, progress: '75%'}));

// Recuperandoconst temp = JSON.parse(sessionStorage.getItem('tempData'));console.log(temp.progress); // 75%

Use sessionStorage para dados temporários: estado de formulários, etapas de assistente de configuração, tokens de uso único.

Erros típicos e como evitá-los

Erro 1: Esqueceu de fazer o parse

const data = localStorage.getItem('myObject');console.log(data.name); // undefined — porque data é uma string!

Solução: sempre use JSON.parse() após obter os dados.

Erro 2: Salvando undefined ou funções

const obj = { name: 'Alex', greet: function() { return 'Oi!'; } };localStorage.setItem('test', JSON.stringify(obj)); // a função será perdida

Solução: JSON.stringify não salva funções, undefined, Symbol