aria-labelledby

설명

aria-labelledby는 하나 이상의 요소 ID를 값으로 받아, 그 요소들의 텍스트를 이어 붙여 현재 요소의 접근 가능한 이름으로 만듭니다. 이름으로 쓸 텍스트가 이미 화면에 보이는 경우에 가장 알맞은 방법입니다. 보이는 텍스트와 들리는 이름이 자동으로 같아지고, 텍스트를 고치면 이름도 함께 바뀝니다.

대화상자(dialog)의 이름을 제목(<h2>)으로 정하거나, tabpanel의 이름을 해당 tab으로, region·listbox·radiogroup처럼 HTML <label>을 쓸 수 없는 사용자 정의 위젯의 이름을 정할 때 씁니다. 공백으로 구분해 여러 ID를 넣으면 나열한 순서대로 이어 붙습니다. 예를 들어 “삭제” 버튼에 aria-labelledby="btn-self row-title"를 주면 “삭제 2024년 결산 보고서”처럼 어떤 항목을 지우는지 알려 줄 수 있습니다. 자기 자신의 ID도 넣을 수 있습니다.

이름 계산에서 가장 우선순위가 높아 aria-label, <label>, 콘텐츠를 모두 덮어씁니다. 참조된 요소가 hidden이나 display: none으로 숨겨져 있어도 텍스트는 이름에 쓰입니다. 그래서 화면에 보이지 않는 이름 텍스트를 따로 둘 수도 있지만, 보이는 텍스트를 참조하는 것이 원래 목적에 맞습니다. 참조는 한 단계만 따라갑니다. 참조된 요소에 다시 aria-labelledby가 있어도 그것은 따라가지 않습니다.

주의할 점은 ID가 정확히 존재해야 한다는 것입니다. 오타가 있거나 참조 대상이 아직 DOM에 없으면 이름이 비어 버리며, 화면에서는 아무 차이가 없어 발견하기 어렵습니다. 컴포넌트를 반복 렌더링할 때 ID가 중복되면 엉뚱한 텍스트가 이름이 됩니다. aria-label과 마찬가지로 generic 등 이름이 금지된 역할에는 쓰지 않습니다.

테스트할 때는 값에 들어 있는 모든 ID가 페이지에 하나씩만 존재하는지, 개발자 도구 접근성 패널의 Name이 의도한 순서의 텍스트로 계산되는지 확인합니다. 자동 검사 도구(axe 등)는 존재하지 않는 ID 참조를 오류로 보고합니다.

값

사용 예

<div role="dialog" aria-modal="true" aria-labelledby="dlg-title">
  <h2 id="dlg-title">배송지 변경</h2>
  …
</div>

<li>
  <span id="file-3">2024년 결산 보고서.pdf</span>
  <button type="button" id="del-3" aria-labelledby="del-3 file-3">삭제</button>
</li>

<p id="ship-label">배송 방법</p>
<div role="radiogroup" aria-labelledby="ship-label">
  <div role="radio" aria-checked="true" tabindex="0">일반 배송</div>
  <div role="radio" aria-checked="false" tabindex="-1">새벽 배송</div>
</div>

<section role="region" aria-labelledby="sec-titel">
  <h2 id="sec-title">이번 주 일정</h2>
</section>

직접 해 보기

체크 상자로 aria-labelledby에 넣을 ID를 고르면 영역의 이름이 바뀝니다. 나열 순서대로 이어 붙는 모습을 확인해 보세요.

화면낭독기에서는

사용 지침

사용할 수 있는 역할

전역 속성이므로 모든 역할과 HTML 요소에 쓸 수 있습니다. 특히 다음 역할과 자주 함께 씁니다.

관련 속성·패턴

이 속성을 쓰는 패턴

참고 자료

• WAI-ARIA 1.2 명세: aria-labelledby (새 창)
• APG: Providing Accessible Names and Descriptions (새 창)
• MDN: aria-labelledby (새 창)
• Accessible Name and Description Computation 1.2 (새 창)