실행 가능한 HTML 문서: details와 summary

Q: HTML에서 details와 summary는 무슨 일을 하나요?

는 열고 닫을 수 있는 섹션인 공개(disclosure) 위젯을 만들어요. 첫 번째 자식인 는 항상 보이는 라벨이고, 클릭하면(또는 포커스가 있을 때 Enter나 Space를 누르면) 안의 나머지 전부가 보이거나 숨겨져요.

Q: details 요소를 처음부터 열린 상태로 하려면 어떻게 하나요?

불리언 open 속성을 추가하세요. 처럼요. 사용자가 열고 닫을 때 브라우저가 이 속성을 추가하고 제거하기 때문에, CSS로 details[open]을 꾸밀 수 있어요.

Q: 하나만 열리는 아코디언은 어떻게 만드나요?

묶음의 모든 에 name="faq"처럼 같은 name 속성을 주세요. 하나를 열면 같은 묶음의 나머지가 닫혀요. JavaScript는 필요 없어요.

Q: details summary의 화살표를 없애거나 바꾸려면 어떻게 하나요?

summary에 list-style: none을 주고, Safari를 위해 summary::-webkit-details-marker { display: none; }을 추가하세요. 그다음 summary::after 등으로 표시를 직접 그리고, details[open] summary::after로 바꾸세요.

Q: details 요소가 열리는 걸 감지할 수 있나요?

네. 요소에서 toggle 이벤트를 듣고 open 속성을 읽으세요. JavaScript에서 details.open = true로 설정하면 열려요.

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을 쓰세요.

자주 묻는 질문

HTML에서 details와 summary는 무슨 일을 하나요?

<details>는 열고 닫을 수 있는 섹션인 공개(disclosure) 위젯을 만들어요. 첫 번째 자식인 <summary>는 항상 보이는 라벨이고, 클릭하면(또는 포커스가 있을 때 Enter나 Space를 누르면) <details> 안의 나머지 전부가 보이거나 숨겨져요.

details 요소를 처음부터 열린 상태로 하려면 어떻게 하나요?

불리언 open 속성을 추가하세요. <details open>처럼요. 사용자가 열고 닫을 때 브라우저가 이 속성을 추가하고 제거하기 때문에, CSS로 details[open]을 꾸밀 수 있어요.

하나만 열리는 아코디언은 어떻게 만드나요?

묶음의 모든 <details>에 name="faq"처럼 같은 name 속성을 주세요. 하나를 열면 같은 묶음의 나머지가 닫혀요. JavaScript는 필요 없어요.

details summary의 화살표를 없애거나 바꾸려면 어떻게 하나요?

summary에 list-style: none을 주고, Safari를 위해 summary::-webkit-details-marker { display: none; }을 추가하세요. 그다음 summary::after 등으로 표시를 직접 그리고, details[open] summary::after로 바꾸세요.

details 요소가 열리는 걸 감지할 수 있나요?

네. <details> 요소에서 toggle 이벤트를 듣고 open 속성을 읽으세요. JavaScript에서 details.open = true로 설정하면 열려요.