Copiar página como Markdown para IA

Cookiebar

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O br-cookiebar avisa sobre o uso de cookies e registra o consentimento da pessoa, por categoria e por cookie.

Ele aparece como uma barra no rodapé (mode="default") e abre um painel com as categorias quando a pessoa escolhe "Definir Cookies" (mode="open").

Como usar

Escreva o texto da barra em info-text.
Coloque o título e a introdução do painel em um br-cookiebar-header.
Crie um br-cookiebar-group por categoria e, dentro dele, um br-cookiebar-cookie por cookie. Use group-opt-out="false" nas categorias que não podem ser desativadas.
Adicione os links de política em br-cookiebar-link, no slot links.
Ouça brCookiebarResponse para salvar a escolha e ative show somente enquanto não houver escolha salva.

<br-cookiebar info-text="Usamos cookies para melhorar sua experiência.">
  <br-cookiebar-header slot="header" main-title="Aviso de cookies" entry-text="Escolha quais cookies aceitar."></br-cookiebar-header>

  <br-cookiebar-group group-id="necessarios" group-name="Necessários" group-text="Essenciais para o site funcionar." group-opt-out="false">
    <br-cookiebar-cookie cookie-id="sessao" cookie-name="sessao" expires="Ao fechar o navegador" domain="exemplo.gov.br" enterprise="Próprio" purpose="Manter a sessão" description="Identifica a sessão de acesso."></br-cookiebar-cookie>
  </br-cookiebar-group>

  <br-cookiebar-link slot="links" name="Política de privacidade" href="/privacidade"></br-cookiebar-link>
</br-cookiebar>

const cookiebar = document.querySelector('br-cookiebar');
cookiebar.show = !localStorage.getItem('consentimento');
cookiebar.addEventListener('brCookiebarResponse', (event) => {
  localStorage.setItem('consentimento', JSON.stringify(event.detail));
});

event.detail traz o estado de cada categoria (cookieGroups) e de cada cookie (cookieList). Para reabrir o painel depois, por exemplo num link "Preferências de cookies", chame openPanel().

Quando evitar

Avisos que não tratam de consentimento: use br-message ou br-notification.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

Exemplos

Carregando preview…

Recolher controles e código

Sobreposição

A barra fica fixa no rodapé, sobre o conteúdo, sem empurrar a página. O painel (mode="open") e a barra com scrim abrem como diálogo modal: o restante da página fica inacessível até o diálogo fechar.

Evite abrir outro modal ao mesmo tempo que o cookiebar.

Propriedades

acceptButton

Atributo	`accept-button`
Descrição	Texto do botão primário de aceite. Padrão: `Aceitar`.
Tipo	`string`
Valor padrão	`'Aceitar'`

allAlertMessage

Atributo	`all-alert-message`
Descrição	Mensagem exibida abaixo do checkbox geral quando está desmarcado ou com seleção parcial.
Tipo	`string`
Valor padrão	---

allOptOut

Atributo	`all-opt-out`
Descrição	Define se o cookiebar opera no padrão opt-out (`true`, recomendado) ou opt-in (`false`). - opt-out (`true`): botão secundário "Definir Cookies"; usuário pode configurar cookies. - opt-in (`false`): botão secundário "Ver Política de Cookies"; painel é somente leitura.
Tipo	`boolean`
Valor padrão	`true`

closeLabel

Atributo	`close-label`
Descrição	`aria-label` do botão fechar exibido no canto do painel expandido (`mode="open"`). Permite traduzir o rótulo para outros idiomas.
Tipo	`string`
Valor padrão	`'Fechar'`

cookieGroupsLabel

Atributo	`cookie-groups-label`
Descrição	Rótulo do título da seção de grupos de cookies.
Tipo	`string`
Valor padrão	`'Classes de cookies'`

customId

Atributo	`custom-id`
Descrição	Identificador único; gerado automaticamente quando omitido.
Tipo	`string`
Valor padrão	`generateUniqueId()`

defaultPanelLabel

Atributo	`default-panel-label`
Descrição	`aria-label` da barra de aviso de cookies (`mode="default"`). Deve descrever o propósito da região de forma sucinta (ex: "Aviso de cookies").
Tipo	`string`
Valor padrão	`'Aviso de cookies'`

infoText

Atributo	`info-text`
Descrição	Texto informativo exibido na barra inferior (modo default), descrevendo a política de cookies. (obrigatório)
Tipo	`string`
Valor padrão	---

linksLabel

Atributo	`links-label`
Descrição	`aria-label` do elemento `<nav>` que envolve os links complementares no painel expandido. Permite traduzir o rótulo para outros idiomas.
Tipo	`string`
Valor padrão	`'Links complementares'`

mode

Atributo	`mode`
Descrição	Estado visual atual do painel. Valores inválidos usam `default`. - `default`: barra inferior com texto e botões. - `open`: painel de tela cheia com grupos de cookies configuráveis.
Tipo	`"default" \| "open"`
Valor padrão	`'default'`

optInButton

Atributo	`opt-in-button`
Descrição	Texto do botão secundário quando `all-opt-out="false"`.
Tipo	`string`
Valor padrão	`'Ver Política de Cookies'`

optOutButton

Atributo	`opt-out-button`
Descrição	Texto do botão secundário quando `all-opt-out="true"`.
Tipo	`string`
Valor padrão	`'Definir Cookies'`

panelLabel

Atributo	`panel-label`
Descrição	`aria-label` do painel expandido (`mode="open"`), que possui `role="dialog"`. Leitores de tela anunciam este texto ao entrar no diálogo modal de configuração de cookies. Deve descrever o propósito do diálogo de forma sucinta (ex: "Configurações de cookies").
Tipo	`string`
Valor padrão	`'Configurações de cookies'`

rejectButton

Atributo	`reject-button`
Descrição	Texto do botão de rejeição dos cookies não obrigatórios. Exibido apenas quando `show-reject-button="true"`.
Tipo	`string`
Valor padrão	`'Rejeitar não obrigatórios'`

scrim

Atributo	`scrim`
Descrição	Quando `true`, exibe uma camada semitransparente (scrim) sobre o conteúdo da página abaixo do painel default, sinalizando que o cookiebar requer atenção. Efeito no foco: com `scrim=true`, o atributo `inert` é aplicado nos irmãos do cookiebar no DOM, prendendo o foco e o cursor virtual do leitor de tela dentro do painel default enquanto ele estiver visível. Com `scrim=false` (padrão), nenhum trap é ativado — o usuário pode navegar livremente pela página, em conformidade com WCAG 2.1.2 (No Keyboard Trap). Use `scrim=true` apenas quando o cenário de negócio exigir que a decisão sobre cookies seja tomada antes de qualquer outra interação. No modo `open` (diálogo modal), o `inert` é aplicado independentemente do valor de `scrim`.
Tipo	`boolean`
Valor padrão	`false`

selectAll

Atributo	`select-all`
Descrição	Estado inicial do checkbox "Selecionar tudo". Quando `true`, todos os grupos opt-out iniciam selecionados.
Tipo	`boolean`
Valor padrão	`false`

selectAllLabel

Atributo	`select-all-label`
Descrição	Texto do checkbox geral quando está totalmente selecionado (ação: desselecionar).
Tipo	`string`
Valor padrão	`'Selecionar tudo'`

show

Atributo	`show`
Descrição	Controla a visibilidade do componente. O consumidor é responsável por definir este valor com base na persistência do consentimento (ex: verificar se já existe um cookie de consentimento salvo).
Tipo	`boolean`
Valor padrão	`false`

showRejectButton

Atributo	`show-reject-button`
Descrição	Quando `true`, exibe o botão "Rejeitar não obrigatórios" nos painéis default e open. Cookies de grupos com `group-opt-out="false"` (sempre ativos) não são afetados.
Tipo	`boolean`
Valor padrão	`false`

unselectAllLabel

Atributo	`unselect-all-label`
Descrição	Texto do checkbox geral quando está desmarcado ou indeterminado (ação: selecionar).
Tipo	`string`
Valor padrão	`'Desselecionar tudo'`

Slots

Nome	Descrição
`"actions"`	Recebe botões de ação. Se vazio, o componente renderiza os botões padrão.
`"default"`	Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`.
`"header"`	Recebe `br-cookiebar-header` ou HTML livre.
`"links"`	Recebe links complementares (`br-cookiebar-link` ou elementos `<a>` livres).

Eventos

Evento	Descrição	Depreciação	Propagação
`brCookiebarAccept`	Sinal emitido quando o usuário clica em Aceitar. Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.	---	true
`brCookiebarClose`	Emitido quando o painel recolhe para modo default.	---	true
`brCookiebarHide`	Emitido quando o componente é ocultado (`show` → false).	---	true
`brCookiebarOpen`	Emitido quando o painel expande para modo open.	---	true
`brCookiebarPolicyClick`	Emitido quando o usuário clica no botão secundário no modo opt-in (`allOptOut=false`). O consumidor é responsável por navegar para a página de Política de Cookies.	---	true
`brCookiebarReject`	Sinal emitido quando o usuário clica em "Rejeitar não obrigatórios". Não carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.	---	true
`brCookiebarResponse`	Emitido após `brCookiebarAccept` ou `brCookiebarReject`, com o estado final de consentimento. É o único evento que carrega `CookiebarOutputData` — use-o para persistir o consentimento (localStorage, cookie HTTP, API etc.). Não é disparado durante interações com checkboxes e switches internos.	---	true
`brCookiebarShow`	Emitido quando o componente se torna visível (`show` → true).	---	true

Métodos

close

Descrição	Oculta o cookiebar.
Assinatura	`close() => Promise<void>`
Parâmetros	---

getSelectedCookies

Descrição	Retorna o JSON com o estado atual de seleção de todos os grupos e cookies.
Assinatura	`getSelectedCookies() => Promise<CookiebarOutputData>`
Parâmetros	---

openDefault

Descrição	Exibe o cookiebar no modo `default` (barra inferior).
Assinatura	`openDefault() => Promise<void>`
Parâmetros	---

openPanel

Descrição	Exibe o cookiebar diretamente no modo `open` (painel de tela cheia).
Assinatura	`openPanel() => Promise<void>`
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
`"body"`	Corpo do painel aberto (com rolagem).
`"container"`	Container raiz do componente.
`"default-panel"`	Painel fechado (modo default).
`"footer"`	Rodapé com botões de ação.
`"header"`	Cabeçalho do painel aberto.
`"open-panel"`	Painel expandido (modo open).
`"scrim"`	Camada de sobreposição opcional.

Dependências

Subcomponentes

Depende de

Gráfico

Migração de `<br-cookiebar>` (1.x → 2.x)

O conteúdo deixou de ser um objeto e passou a ser montado com subcomponentes.

1.x	2.x	O que fazer
`content`	subcomponentes	Monte com `br-cookiebar-header`, `br-cookiebar-group`, `br-cookiebar-cookie` e `br-cookiebar-link`.
`lang`	—	Remova. Escreva os textos no idioma da aplicação.
`open`	`show`	Renomeie.
evento `report`	`brCookiebarResponse`	Leia a escolha em `event.detail`.

Para abrir e fechar pelo código, use openDefault(), openPanel() e close(). Para ler a escolha a qualquer momento, use getSelectedCookies().

1.x:

<br-cookiebar :content="content" lang="pt-BR" open></br-cookiebar>

2.x:

<br-cookiebar show info-text="Usamos cookies para melhorar sua experiência.">
  <br-cookiebar-header slot="header" main-title="Aviso de cookies"></br-cookiebar-header>
  <!-- grupos e cookies -->
</br-cookiebar>

Visão Geral​

Como usar​

Quando evitar​

Exemplo(s)​

Sobreposição​

Propriedades​

acceptButton​

allAlertMessage​

allOptOut​

closeLabel​

cookieGroupsLabel​

customId​

defaultPanelLabel​

infoText​

linksLabel​

mode​

optInButton​

optOutButton​

panelLabel​

rejectButton​

scrim​

selectAll​

selectAllLabel​

show​

showRejectButton​

unselectAllLabel​

Slots​

Eventos​

Métodos​

close​

getSelectedCookies​

openDefault​

openPanel​

CSS Shadow Parts​

Dependências​

Subcomponentes​

Depende de​

Gráfico​

Migração de <br-cookiebar> (1.x → 2.x)​