HTML details와 summary: 접고 펼치는 섹션 만들기

details와 summary로 접고 펼치는 콘텐츠

콘텐츠를 <details>로 감싸고 맨 앞에 <summary>를 두세요. summary는 계속 보이고, 나머지는 독자가 클릭할 때까지 숨겨져요.

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

질문을 클릭하면 열리고, 다시 클릭하면 닫혀요. 브라우저가 삼각형 표시를 붙이고, summary가 포커스를 받게 하고, Enter나 Space로 열고 닫게 하고, 펼쳐졌는지 접혔는지 스크린 리더에 알려 줘요. JavaScript는 전혀 쓰이지 않아요.

<summary>를 빼면 브라우저가 대신 기본 라벨(영어에서는 "Details")을 보여 줘요.

처음부터 열어 두기

불리언 open 속성은 처음부터 콘텐츠를 보여 줘요. 독자가 열고 닫을 때 브라우저가 open을 추가하고 제거하니, 스타일을 입히는 고리로도 써요.

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

열린 상자에는 details[open] 덕분에 파란 테두리가 있어요. "Returns"를 열면 그것도 파랗게 바뀌고, 둘 다 동시에 열려 있을 수 있어요.

아코디언: 한 번에 하나만 열기

여러 <details> 요소에 같은 name을 주면 배타적인 묶음이 돼요. 하나를 열면 나머지가 닫혀요. 예전에는 JavaScript가 필요했지만, 이제 현재 Chrome, Edge, Firefox, 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>

두 번째 질문을 열면 첫 번째가 닫혀요. name 속성을 지우면 다시 각자 따로 열려요. 배타적인 아코디언은 독자가 비교하고 싶을 수 있는 내용을 숨기니, 섹션들이 서로 대안일 때 쓰고, 여러 개를 열어 두고 싶어 할 수 있다면 일반 <details>를 쓰세요.

표시 꾸미기

삼각형은 summary의 목록 표시예요. list-style: none으로 없애고(::-webkit-details-marker 규칙은 Safari용이에요), 가상 요소로 표시를 직접 그릴 수 있어요.

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

섹션이 열리면 더하기 기호가 45도 회전해서 곱하기 모양이 돼요. 여기의 :focus-visible outline처럼 포커스 스타일을 보이게 유지하세요. 기본 표시를 없애고 나면 키보드 사용자가 기댈 수 있는 건 포커스 링이에요.

toggle 이벤트와 open 속성

JavaScript는 details.open을 읽고 설정할 수 있고, 클릭이든 키든 스크립트든 무엇 때문이든 바뀔 때마다 toggle 이벤트가 발생해요.

<!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"은 두 요소 모두에 open을 설정하고, 로그는 마지막 toggle 이벤트를 보여 줘요. 이 이벤트는 버블링되지 않으니 부모가 아니라 각 <details> 요소에서 들으세요.

summary에 넣을 수 있는 것

summary에는 텍스트, 인라인 요소, 또는 섹션 제목이 페이지 개요에 속해야 할 때는 제목을 넣어요.

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

<summary> 안에 링크, 버튼, 폼 필드는 피하세요. summary 자체가 이미 컨트롤이라서, 그 안의 컨트롤은 놓치거나 실수로 누르기 쉽고, 스크린 리더도 중첩된 컨트롤을 제대로 알려 주지 못해요. 인터랙티브 콘텐츠는 대신 <details> 본문에 넣으세요.

자주 하는 실수

• <div>와 JavaScript로 토글을 만듦. <details>는 이미 클릭, 키, 스크린 리더 상태를 처리해요. 직접 만든 토글이 꼭 필요하다면 aria-expanded와 함께 button을 쓰세요.
• <summary>를 맨 앞이 아닌 곳에 둠. 반드시 <details>의 첫 번째 자식이어야 해요.
• 대체 표시 없이 표시를 숨김. 위의 더하기 기호처럼 summary가 열린다는 신호를 독자에게 주세요.
• display로 콘텐츠를 숨김. 대신 open을 토글하세요. 콘텐츠를 강제로 보이거나 숨기는 CSS는 브라우저의 상태와 충돌해요.
• 사람들이 비교하는 콘텐츠에 배타적 묶음을 씀. 한 번에 하나만 여는 게 맞을 때만 name을 쓰세요.