Dokumentacja HTML z przykładami: details i summary

Q: Jak sprawić, żeby element details był domyślnie otwarty?

Dodaj atrybut logiczny open: . Przeglądarka dodaje i usuwa ten atrybut, gdy użytkownik przełącza sekcję, więc CSS może stylizować details[open].

Q: Jak zrobić akordeon, w którym otwarta jest tylko jedna sekcja?

Nadaj każdemu w grupie ten sam atrybut name, na przykład name="faq". Otwarcie jednej sekcji zamyka pozostałe w tej grupie, bez JavaScriptu.

Q: Jak usunąć lub zmienić strzałkę w summary elementu details?

Ustaw list-style: none na summary i dodaj summary::-webkit-details-marker { display: none; } dla Safari. Potem narysuj własny wskaźnik, na przykład przez summary::after, i zmieniaj go przez details[open] summary::after.

Q: Czy da się wykryć otwarcie elementu details?

Tak. Nasłuchuj zdarzenia toggle na elemencie i odczytuj jego właściwość open. Ustawienie details.open = true w JavaScripcie go otwiera.

Zwijana treść z details i summary

Otocz treść elementem <details> i umieść na początku <summary>. Summary pozostaje widoczne; cała reszta jest ukryta, dopóki czytelnik go nie kliknie:

<!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>

Kliknij pytanie, żeby je otworzyć, i jeszcze raz, żeby zamknąć. Przeglądarka dodaje trójkątny znacznik, pozwala ustawić fokus na summary, przełącza je klawiszem Enter lub Spacją i informuje czytniki ekranu, czy sekcja jest rozwinięta, czy zwinięta. Nie ma tu ani linijki JavaScriptu.

Jeśli pominiesz <summary>, przeglądarka pokaże zamiast niego domyślną etykietę ("Szczegóły" po polsku).

Domyślnie otwarte

Atrybut logiczny open pokazuje treść od początku. Przeglądarka dodaje i usuwa open, gdy czytelnik przełącza sekcję, więc służy on też jako zaczep do stylowania:

<!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>

Otwarte pudełko ma niebieskie obramowanie z details[open]. Otwórz "Returns", a też zrobi się niebieskie; obie sekcje mogą być otwarte jednocześnie.

Akordeon: tylko jedna otwarta sekcja

Nadaj kilku elementom <details> tę samą name, a staną się grupą wyłączną: otwarcie jednego zamyka pozostałe. Kiedyś wymagało to JavaScriptu, a teraz w aktualnych Chrome, Edge, Firefoksie i Safari działa samym atrybutem:

<!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>

Otwórz drugie pytanie, a pierwsze się zamknie. Usuń atrybuty name, a znowu będą się otwierać niezależnie. Wyłączny akordeon ukrywa treść, którą czytelnik mógłby chcieć porównać, więc używaj go, gdy sekcje są alternatywami, a zwykłego <details>, gdy ktoś może chcieć mieć otwartych kilka.

Stylowanie znacznika

Trójkąt to znacznik listy na summary. list-style: none go usuwa (reguła ::-webkit-details-marker obsługuje Safari), a pseudoelement może narysować własny wskaźnik:

<!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>

Plus obraca się o 45 stopni w krzyżyk, gdy sekcja się otwiera. Zachowaj widoczny styl fokusu, jak tutaj obramowanie :focus-visible: po usunięciu domyślnego znacznika to na ramce fokusu polegają użytkownicy klawiatury.

Zdarzenie toggle i właściwość open

JavaScript może odczytywać i ustawiać details.open, a zdarzenie toggle odpala się po każdej zmianie, niezależnie od tego, czy wywołało ją kliknięcie, klawisz czy skrypt:

<!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" ustawia open na obu, a log pokazuje ostatnie zdarzenie toggle. Zdarzenie nie propaguje się w górę (nie bąbelkuje), więc nasłuchuj na każdym elemencie <details>, a nie na rodzicu.

Co umieścić w summary

Summary zawiera tekst, elementy liniowe albo nagłówek, gdy tytuł sekcji należy do konspektu strony:

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

Unikaj linków, przycisków i pól formularza wewnątrz <summary>: summary już jest kontrolką, więc kontrolkę w jego środku łatwo przeoczyć albo kliknąć przez pomyłkę, a czytniki ekranu słabo ogłaszają zagnieżdżone kontrolki. Treść interaktywną umieszczaj w ciele <details>.

Częste błędy

Budowanie przełącznika z <div> i JavaScriptu. <details> już obsługuje kliknięcia, klawisze i stan dla czytników ekranu. Gdy naprawdę potrzebujesz własnego przełącznika, użyj przycisku z aria-expanded.
<summary> w innym miejscu niż na początku. Musi być pierwszym dzieckiem <details>.
Ukrycie znacznika bez zamiennika. Daj czytelnikom jakiś znak, że summary się otwiera, jak plus powyżej.
Ukrywanie treści przez display. Zamiast tego przełączaj open; CSS, który wymusza widoczność lub ukrycie treści, walczy ze stanem przeglądarki.
Grupy wyłączne dla treści, którą ludzie porównują. Używaj name tylko wtedy, gdy jedna otwarta sekcja naraz ma sens.

Najczęściej zadawane pytania

Do czego służą details i summary w HTML?

<details> tworzy element rozwijany: sekcję, którą można otwierać i zamykać. Jego pierwsze dziecko, <summary>, to zawsze widoczna etykieta; kliknięcie jej (albo naciśnięcie Enter lub Spacji, gdy ma fokus) pokazuje lub ukrywa całą resztę wewnątrz <details>.

Jak sprawić, żeby element details był domyślnie otwarty?

Dodaj atrybut logiczny open: <details open>. Przeglądarka dodaje i usuwa ten atrybut, gdy użytkownik przełącza sekcję, więc CSS może stylizować details[open].

Jak zrobić akordeon, w którym otwarta jest tylko jedna sekcja?

Nadaj każdemu <details> w grupie ten sam atrybut name, na przykład name="faq". Otwarcie jednej sekcji zamyka pozostałe w tej grupie, bez JavaScriptu.

Jak usunąć lub zmienić strzałkę w summary elementu details?

Ustaw list-style: none na summary i dodaj summary::-webkit-details-marker { display: none; } dla Safari. Potem narysuj własny wskaźnik, na przykład przez summary::after, i zmieniaj go przez details[open] summary::after.

Czy da się wykryć otwarcie elementu details?

Tak. Nasłuchuj zdarzenia toggle na elemencie <details> i odczytuj jego właściwość open. Ustawienie details.open = true w JavaScripcie go otwiera.

Powiązane zagadnienia