js-cookie para cookies com JavaScript

js-cookie é uma biblioteca JavaScript para trabalhar com cookies de maneira simples e eficiente. Saiba mais sobre esta poderosa lib para controlar cookies.

Ir para o artigo

js-cookie é uma biblioteca que permite usar cookies com JavaScript de maneira simples e eficiente.

A lib, que (no momento da publicação deste artigo) já conta com mais de 15 mil estrelas no GitHub, tem como suas principais características:

Funciona em todos os navegadores;
Aceita qualquer caractere;
Pesadamente testado;
Sem dependências;
Diversas maneiras de usar em projetos;
Fartamente documentado;
Levíssimo (<700 bytes no gzip).

Quer dizer, js-cookie permite manipular cookies muito facilmente, praticamente não afetando o peso total do projeto e trazendo muitas possibilidades de interação e controle.

Criar cookie

O js cookie é bastante completo, provendo muitas possibilidades de manipular e usar cookies em qualquer projeto Web.

Mas somente com suas funções básicas também é possível conseguir muitos resultados. Então, conheça o uso básico do js-cookie para manipular cookies com JavaScript.

Obviamente, para começar a brincadeira, é preciso saber como criar um cookie com o js cookie.

Uma vez inserida a biblioteca (por qualquer dos meios possíveis oferecidos por ela), basta usar a função .set().

Cookies.set('nome', 'valor');

1	Cookies.set('nome', 'valor');

Um cookie nada mais é que uma informação de dados simples, sendo formado por uma entrada de texto e se respectivo valor — alguns fazem analogia a uma entrada em um dicionário ou item de um array.

Por exemplo, se quiser criar um cookie para guardar um nome de usuário, seria algo mais ou menos como:

Cookies.set('username', 'josedelascoles');

1	Cookies.set('username', 'josedelascoles');

Com essa simples linha de código, já se criou um browser cookie com o respectivo valor associado.

Expiração do cookie

Por padrão, o tempo de vida de um cookie criado com o js-cookie é o tempo de sessão, quer dizer, ao fechar o navegador ou a aba do site/app, o cookie é destruído sumariamente.

Claro que há casos em que é preciso que um cookie tenha um tempo de vida maior; como não poderia deixar de ser, js-cookie também oferece opções para que o tempo de vida do cookie seja especificado.

Para estipular o tempo de um cookie, usa-se a opção expires (passada no objeto de opções que é o 3º parâmetro da função de criação).

Então, para especificar, por exemplo, um tempo de vida de 7 dias para o cookie, o código seria:

Cookies.set('username', 'josedelascoles', { expires: 7 });

1	Cookies.set('username', 'josedelascoles', { expires: 7 });

Perceba que o valor informado já em dias. Se quisesse 1 mês, colocaria 30, por exemplo.

Para os casos de ser necessário especificar cookies com tempo de vida inferior a um dia, basta colocar o valor associado, sem problemas. Exemplo: para “meio dia”, use 0.5 e assim por diante.

Também é possível usar funções nativas do JavaScript (ou libs de manipulação de data) para chegar a valores necessários.

Numa situação de ser preciso um cookie de 15 minutos, seria algo como:

var fifteenMinutes = new Date(new Date().getTime() + 15 * 60 * 1000);

Cookies.set('username', 'josedelascoles', {
  expires: fifteenMinutes
});

var fifteenMinutes = new Date(new Date().getTime() + 15 * 60 * 1000);

Cookies.set('username', 'josedelascoles', {

expires: fifteenMinutes

});

Ler cookie

Para ler cookies e ter acesso a informações, a função do js-cookie é a .get(), como no exemplo:

Cookies.get('username'); // => 'josedelascoles'

1	Cookies.get('username'); // => 'josedelascoles'

Obviamente, quando se tentar ler um cookie inexistente, a resposta é um belo undefined:

Cookies.get('nothing'); // => undefined

1	Cookies.get('nothing'); // => undefined

Para ler todos os cookies existentes, basta não passar o parâmetro de nome (retorno é um objeto):

Cookies.get();

1	Cookies.get();

Domínio do cookie

Uma das opções possíveis no objeto do 3º parâmetro é domain, que permite limitar a visibilidade do cookie a somente o domínio especificado.

Cookies.get('username', { domain: 'subdomain.site.com' });

1	Cookies.get('username', { domain: 'subdomain.site.com' });

Remover cookie

Se for preciso remover um cookie, o js-cookie conta com a função .remove(), que exige que se passe somente o nome do cookie que se quer deletar.

Cookies.remove('username');

1	Cookies.remove('username');

Se por acaso usou a opção domain (ou path, uma outra possível), é preciso especificar isso no momento da deleção.

Faça suas verificações manualmente, pois a remoção de um cookie inexistente não gera nenhuma exceção nem retorna valor.

Conflitos de namespace

E o danadinho do js-cookie é tão bom que já prevê possíveis conflitos de namespace com outras bibliotecas e/ou implementações, a .noConflict().

Define um nome qualquer para a atribuição total de sua API e depois basta usar as funções normalmente a partir do que foi escolhido.

Exemplo:

var Cookies2 = Cookies.noConflict();

Cookies2.set('username', 'josedelascoles');

var Cookies2 = Cookies.noConflict();

Cookies2.set('username', 'josedelascoles');

Exemplo prático com js-cookie: controle de modal para newsletter

Os principais métodos para manipular cookies usando js-cookie já foram mostrados (não deixe de conferir a documentação completa) e, para complementar, vamos a uma implementação prática.

Seguindo a dica de um inscrito de nosso canal no YouTube, o exemplo contemplará o código JavaScript necessário para exibir um modal com convite à inscrição de uma newsletter quando se abre a página e, se a pessoa clicar em “Fechar”, somente dentro de 7 dias o modal aparece novamente.

Você poderá ver a explicação mais completa e parte visual no vídeo no início do artigo; aqui, vamos abordar o JavaScript de uma maneira possível de se chegar ao resultado.

Criando o cookie quando se clica no botão de fechar

Queremos que o cookie seja criado assim que o visitante pressionar o botão “Fechar” do modal. Para isso, é preciso identificar este botão no HTML (atribuindo-se uma classe, por exemplo) e atribuir um listener para este evento do clique.

var $closeButton = document.querySelector('.js-close');

$closeButton.addEventLitener('click', function(){
  Cookies.set('closed', true, { expires: 7 })
});

var $closeButton = document.querySelector('.js-close');

$closeButton.addEventLitener('click', function(){

Cookies.set('closed', true, { expires: 7 })

});

Com isso, quando a pessoa clicar no botão de fechar, o cookie será criado (com tempo de expiração de 7 dias).

Controlando a interface a partir de cookies

Agora, para completar a interação, é preciso controlar o visual do modal, fazendo com que ele desapareça da tela quando o “Fechar” for clicado e/ou enquanto o cookie closed for válido.

var $overlay = document.querySelector('.js-overlay');
var $closeButton = document.querySelector('.js-close');

if (Cookies.get('closed')) {
  $overlay.classList.remove('is-open');
}

$closeButton.addEventLitener('click', function(){
  Cookies.set('closed', true, { expires: 7 })

  $overlay.classList.remove('is-open');
});

var $overlay = document.querySelector('.js-overlay');

var $closeButton = document.querySelector('.js-close');

if (Cookies.get('closed')) {

$overlay.classList.remove('is-open');

}

$closeButton.addEventLitener('click', function(){

Cookies.set('closed', true, { expires: 7 })

$overlay.classList.remove('is-open');

});

O código ainda poderia ser otimizado, mas, para fins de demonstração, cumpre bem o seu papel elucidativo.

A lição importante a se considerar é saber o momento certo de criar um cookie — no caso, quando determinado evento acontece (click) — e saber tomar ações a partir de situações/condições especificadas nas regras de negócio — if (Cookies.get('closed')) {}.

Conclusão

Cookies estão presentes na vida de desenvolvedores e visitantes comuns de web sites e apps há muitos e muitos anos. O que, comumente, pertencia ao reino do back end, atualmente pode estar presente em todas as frentes de um projeto Web.

O desenvolvimento para web moderno também conta com outras formas e tecnologias para armazenamento de dados no lado do cliente, com suas vantagens e desvantagens e prós e contras em relação a cookies. Mas isso já assuntos para outro artigo. :)

E você, já conhecia e/ou já usou o js-cookie para controlar cookies em seus projetos Web? Usa alguma outra solução para isso? Comente!