Tag HTML <summary>
A tag HTML <summary> define o rótulo clicável para um widget de divulgação <details>. Sintaxe, acessibilidade, estilo e exemplos.
A tag <summary> define a legenda clicável — o rótulo visível — para um widget de divulgação <details>. Clicar no summary expande ou recolhe o restante do conteúdo de <details>, portanto o summary é a parte que permanece sempre na tela, independentemente de o widget estar aberto ou fechado.
O elemento <summary> deve ser o primeiro filho de um elemento <details>. Se <details> não tiver um <summary>, o navegador fornece um rótulo padrão (geralmente a palavra "Details"), o que raramente é o desejado — portanto, quase todo widget de divulgação deve incluir um.
Esta página abrange a sintaxe de <summary>, seu comportamento, suas características de acessibilidade, o evento toggle e como estilizá-lo (incluindo a remoção do triângulo de divulgação).
Sintaxe
A tag <summary> vem em pares. O texto do rótulo é escrito entre as tags de abertura <summary> e fechamento </summary>, e fica diretamente dentro de <details>.
Exemplo da tag HTML <summary>
Tag HTML <summary>
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<details>
<summary>Copyright 2013-2014.</summary>
<p>W3docs. All rights reserved.</p>
<p>The content of the website is the property of W3Docs.com.</p>
</details>
</body>
</html>Conteúdo rico dentro de <summary>
Um summary não se limita a texto simples. Ele pode conter conteúdo inline como <strong>, <em>, <code> ou um ícone, o que é útil para enfatizar o rótulo:
<details>
<summary><strong>Shipping & returns</strong> — read before ordering</summary>
<p>Orders ship within 2 business days. Returns accepted for 30 days.</p>
</details>Mantenha o summary curto e significativo: ele é o rótulo que um usuário lê (e um leitor de tela anuncia) para decidir se abre o widget.
Acessibilidade
O elemento <summary> expõe uma função ARIA implícita de button para a tecnologia assistiva, sendo focalizável e operável pelo teclado por padrão:
- Tab move o foco para o summary.
- Enter ou Space alterna o
<details>pai entre aberto e fechado.
Por causa disso, você não deve envolver um <button> real ou um link dentro do summary — o summary já é o controle. Certifique-se de que o summary contenha um rótulo claro e descritivo para que os usuários que navegam por tabulação ou por leitor de tela saibam o que o widget revela.
O evento toggle e details.open
O estado aberto/fechado de um widget de divulgação fica no elemento <details>, não no summary. O atributo boolean open reflete esse estado, e você pode ler ou definir como details.open em JavaScript.
Sempre que o estado muda — por clique, teclado ou script — o navegador dispara um evento toggle no elemento <details>. Ouvi-lo permite reagir ao usuário abrindo ou fechando o widget (por exemplo, carregamento preguiçoso de conteúdo ou envio de analytics) em vez de verificar o estado periodicamente:
const details = document.querySelector('details');
details.addEventListener('toggle', () => {
console.log('Details is now', details.open ? 'open' : 'closed');
});Como estilizar a tag <summary>
O estilo padrão de um <summary> usa a propriedade CSS display com o valor list-item, que é o que desenha o triângulo de divulgação (o marcador) ao lado do rótulo.
Você pode estilizar o summary como qualquer outro elemento — mudar sua cor, adicionar padding ou definir um cursor:
summary {
color: blue;
cursor: pointer;
padding: 8px;
}Removendo o triângulo de divulgação
Para ocultar o triângulo padrão de forma confiável em todos os navegadores, remova o marcador de lista e também limpe o marcador legado do WebKit/Blink:
summary {
list-style: none; /* Firefox and standards-based browsers */
}
summary::-webkit-details-marker {
display: none; /* Safari and older Chrome */
}Atributos
A tag <summary> não possui atributos obrigatórios próprios. Ela suporta os Atributos Globais e os Atributos de Evento.
Construindo um FAQ / acordeão
Como cada <details> funciona de forma independente, você pode colocar vários em uma página para criar um FAQ ou acordeão. Cada <summary> é a pergunta, e o conteúdo oculto é a resposta:
<details>
<summary>How do I track my order?</summary>
<p>Use the tracking link in your confirmation email.</p>
</details>
<details>
<summary>Can I change my shipping address?</summary>
<p>Yes, as long as the order has not yet shipped.</p>
</details>
<details>
<summary>Do you ship internationally?</summary>
<p>We ship to most countries. Rates are shown at checkout.</p>
</details>Para permitir que apenas uma seção fique aberta por vez (um verdadeiro acordeão), dê aos elementos <details> o mesmo atributo name para que o navegador os mantenha mutuamente exclusivos.
A tag <summary> é um dos elementos HTML5. Veja também o elemento <details> que ela rotula.