Docs executáveis de HTML: Details e summary

Q: Como deixar um details aberto por padrão?

Adicione o atributo booleano open: . O navegador adiciona e remove esse atributo conforme o usuário alterna, então o CSS pode estilizar details[open].

Q: Como fazer um acordeão em que só uma seção fica aberta?

Dê a todos os do grupo o mesmo atributo name, por exemplo name="faq". Abrir um fecha os outros desse grupo, sem JavaScript.

Q: Como remover ou mudar a seta do summary?

Defina list-style: none no summary e adicione summary::-webkit-details-marker { display: none; } para o Safari. Depois desenhe o seu próprio indicador, por exemplo com summary::after, e mude-o com details[open] summary::after.

Q: Dá para detectar quando um details abre?

Sim. Escute o evento toggle no elemento e leia a sua propriedade open. Definir details.open = true no JavaScript o abre.

Conteúdo recolhível com details e summary

Envolva o conteúdo em <details> e coloque um <summary> primeiro. O summary fica visível; todo o resto fica escondido até o usuário clicar nele:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>details</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <details>
    <summary>What is included in the free plan?</summary>
    <p>Five projects, community support and all the beginner courses.</p>
  </details>
</body>
</html>

Clique na pergunta para abrir, e de novo para fechar. O navegador adiciona o marcador triangular, torna o summary focável, o alterna com Enter ou Espaço e diz aos leitores de tela se ele está expandido ou recolhido. Nenhum JavaScript envolvido.

Se você deixar o <summary> de fora, o navegador mostra um rótulo padrão ("Detalhes" em português) no lugar.

Aberto por padrão

O atributo booleano open mostra o conteúdo desde o início. O navegador adiciona e remove open conforme o usuário alterna, então ele também é o gancho para estilizar:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>open</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    details { border: 2px solid #e5e7eb; border-radius: 8px; padding: 8px 12px; margin-bottom: 8px; }
    details[open] { border-color: #2563eb; }
    summary { cursor: pointer; font-weight: 600; }
  </style>
</head>
<body>
  <details open>
    <summary>Shipping</summary>
    <p>Orders ship within two working days.</p>
  </details>
  <details>
    <summary>Returns</summary>
    <p>Return any item within 30 days.</p>
  </details>
</body>
</html>

A caixa aberta tem uma borda azul vinda de details[open]. Abra "Returns" e ela também fica azul; as duas podem ficar abertas ao mesmo tempo.

Acordeão: só um aberto por vez

Dê a vários elementos <details> o mesmo name e eles viram um grupo exclusivo: abrir um fecha os outros. Isso antes exigia JavaScript e hoje funciona só com o atributo nas versões atuais de Chrome, Edge, Firefox e Safari:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Accordion</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .faq { max-width: 420px; border: 1px solid #e5e7eb; border-radius: 10px; }
    .faq details + details { border-top: 1px solid #e5e7eb; }
    .faq summary { padding: 12px 14px; cursor: pointer; font-weight: 600; }
    .faq p { margin: 0; padding: 0 14px 12px; color: #374151; }
  </style>
</head>
<body>
  <div class="faq">
    <details name="faq" open>
      <summary>Is it free?</summary>
      <p>Yes, the basics are free forever.</p>
    </details>
    <details name="faq">
      <summary>Do I need to install anything?</summary>
      <p>No, everything runs in the browser.</p>
    </details>
    <details name="faq">
      <summary>Can I cancel any time?</summary>
      <p>Yes, from your account settings.</p>
    </details>
  </div>
</body>
</html>

Abra a segunda pergunta e a primeira fecha. Remova os atributos name e elas voltam a abrir de forma independente. Um acordeão exclusivo esconde conteúdo que o usuário talvez queira comparar, então use quando as seções são alternativas, e <details> simples quando as pessoas podem querer várias abertas.

Estilizando o marcador

O triângulo é um marcador de lista no summary. list-style: none o remove (a regra ::-webkit-details-marker cobre o Safari), e um pseudo-elemento pode desenhar o seu próprio indicador:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom marker</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    details { max-width: 420px; background: #f9fafb; border-radius: 8px; margin-bottom: 8px; }
    summary {
      list-style: none; cursor: pointer;
      display: flex; justify-content: space-between; align-items: center;
      padding: 12px 14px; font-weight: 600;
    }
    summary::-webkit-details-marker { display: none; }
    summary::after {
      content: "+"; font-size: 20px; color: #2563eb;
      transition: transform 0.2s;
    }
    details[open] summary::after { transform: rotate(45deg); }
    summary:focus-visible { outline: 3px solid #2563eb; outline-offset: 2px; border-radius: 8px; }
    details p { margin: 0; padding: 0 14px 12px; }
  </style>
</head>
<body>
  <details>
    <summary>How long are the lessons?</summary>
    <p>Most lessons take five to ten minutes.</p>
  </details>
  <details>
    <summary>Do I get a certificate?</summary>
    <p>Yes, when you finish a course.</p>
  </details>
</body>
</html>

O sinal de mais gira 45 graus e vira um X quando a seção abre. Mantenha um estilo de foco visível como o contorno :focus-visible daqui: depois que você remove o marcador padrão, o contorno de foco é o que quem usa teclado tem como referência.

O evento toggle e a propriedade open

O JavaScript pode ler e definir details.open, e o evento toggle dispara depois de cada mudança, seja ela causada por um clique, uma tecla ou um script:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>toggle</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    button { font: inherit; padding: 4px 10px; margin-inline-end: 6px; }
    details { margin-top: 10px; border: 2px solid #e5e7eb; border-radius: 8px; padding: 8px 12px; }
    #log { color: #16a34a; }
  </style>
</head>
<body>
  <button id="expand">Expand all</button>
  <button id="collapse">Collapse all</button>
  <details><summary>Step 1</summary><p>Create an account.</p></details>
  <details><summary>Step 2</summary><p>Pick a course.</p></details>
  <p id="log">Nothing toggled yet.</p>
  <script>
    const all = document.querySelectorAll('details');
    all.forEach((d) => d.addEventListener('toggle', () => {
      document.getElementById('log').textContent =
        d.querySelector('summary').textContent + (d.open ? ' opened' : ' closed');
    }));
    document.getElementById('expand').onclick = () => all.forEach((d) => { d.open = true; });
    document.getElementById('collapse').onclick = () => all.forEach((d) => { d.open = false; });
  </script>
</body>
</html>

"Expand all" define open nos dois, e o log mostra o último evento toggle. O evento não se propaga (não faz bubbling), então escute em cada elemento <details>, e não num pai.

O que vai num summary

Um summary contém texto, elementos inline ou um título, quando o título da seção faz parte da estrutura da página:

<details>
  <summary><h3>Refund policy</h3></summary>
  <p>...</p>
</details>

Evite links, botões e campos de formulário dentro de <summary>: o summary já é um controle, então um controle dentro dele é fácil de não ver ou de acionar sem querer, e os leitores de tela anunciam mal controles aninhados. Coloque o conteúdo interativo no corpo do <details>.

Erros comuns

Montar uma alternância com uma <div> e JavaScript. <details> já cuida dos cliques, das teclas e do estado para o leitor de tela. Quando você precisar mesmo de uma alternância personalizada, use um button com aria-expanded.
Colocar o <summary> em outro lugar que não o primeiro. Ele precisa ser o primeiro filho de <details>.
Esconder o marcador sem colocar outro. Dê ao usuário algum sinal de que o summary abre, como o sinal de mais acima.
Usar display para esconder o conteúdo. Alterne o open; um CSS que força o conteúdo a ficar visível ou escondido briga com o estado do navegador.
Grupos exclusivos para conteúdo que as pessoas comparam. Use name só quando faz sentido uma seção aberta por vez.

Perguntas frequentes

O que details e summary fazem no HTML?

<details> cria um widget de divulgação: uma seção que pode ser aberta e fechada. O seu primeiro filho, <summary>, é o rótulo sempre visível; clicar nele (ou apertar Enter ou Espaço quando ele tem o foco) mostra ou esconde todo o resto dentro de <details>.

Como deixar um details aberto por padrão?

Adicione o atributo booleano open: <details open>. O navegador adiciona e remove esse atributo conforme o usuário alterna, então o CSS pode estilizar details[open].

Como fazer um acordeão em que só uma seção fica aberta?

Dê a todos os <details> do grupo o mesmo atributo name, por exemplo name="faq". Abrir um fecha os outros desse grupo, sem JavaScript.

Como remover ou mudar a seta do summary?

Defina list-style: none no summary e adicione summary::-webkit-details-marker { display: none; } para o Safari. Depois desenhe o seu próprio indicador, por exemplo com summary::after, e mude-o com details[open] summary::after.

Dá para detectar quando um details abre?

Sim. Escute o evento toggle no elemento <details> e leia a sua propriedade open. Definir details.open = true no JavaScript o abre.

Conceitos relacionados