ARIA 접근성 가이드

속성 · 이름·설명 · 전역

aria-describedby

다른 요소의 텍스트를 ID로 참조해 이름 뒤에 읽히는 접근 가능한 설명으로 씁니다.

기초

한눈에 보기

구분
속성 (Property)
분류
이름·설명
값 형식
ID 참조 목록 (공백으로 구분)
기본값
없음
적용 범위
모든 요소 (전역 속성)
HTML 대체
title 속성(이름으로 쓰이지 않을 때 설명이 됨), <input>의 placeholder(이름·설명 대체 아님)

설명

aria-describedby는 요소의 접근 가능한 설명(accessible description)을 정합니다. 이름이 “무엇인지”를 짧게 알려 준다면, 설명은 입력 형식, 조건, 결과처럼 알아 두면 좋은 부가 정보를 담습니다. 값은 aria-labelledby와 같은 형식의 ID 목록이며, 참조한 요소들의 텍스트가 순서대로 이어져 설명이 됩니다.

대표적인 쓰임은 입력 필드의 도움말(“영문·숫자 포함 8자 이상”)과 오류 메시지, 버튼을 누르면 생기는 결과 안내(“삭제한 파일은 복구할 수 없습니다”), 대화상자 본문의 첫 문단 연결입니다. 화면낭독기는 보통 이름·역할·상태를 읽은 뒤 잠시 쉬고 설명을 읽으며, 사용자 설정에 따라 설명을 생략하기도 합니다. 그러므로 설명이 없으면 조작할 수 없는 핵심 정보는 이름이나 레이블에 넣어야 합니다.

참조된 요소가 숨겨져 있어도(hidden, display: none) 텍스트는 설명에 쓰입니다. 다만 설명은 평범한 문자열로 합쳐져 읽히므로 목록, 링크, 표 같은 구조는 사라집니다. 구조가 있는 긴 내용을 연결하려면 aria-details를 씁니다. 오류 메시지는 aria-errormessage로도 연결할 수 있지만 지원 범위가 아직 고르지 않아 aria-describedby와 aria-invalid를 함께 쓰는 방식이 널리 쓰입니다.

오류 메시지를 동적으로 보여 줄 때는 메시지 요소의 ID를 값에 추가하거나 제거하고, 기존 도움말 ID는 그대로 둡니다. 설명은 포커스를 받을 때 읽히므로, 이미 포커스가 있는 필드에서 설명이 바뀌어도 즉시 읽히지는 않습니다. 즉시 알려야 한다면 라이브 리전을 함께 씁니다.

테스트할 때는 개발자 도구 접근성 패널의 Description 값이 의도한 텍스트인지, 참조 ID가 모두 존재하는지, 오류 상태가 사라진 뒤에도 오래된 오류 메시지가 설명에 남아 있지 않은지 확인합니다.

값

값
값의미
ID 참조 목록설명으로 쓸 텍스트를 가진 요소의 ID입니다. 여러 개면 공백으로 구분하고, 나열한 순서대로 이어 붙습니다.

사용 예

입력 필드 도움말

권장HTML
<label for="pw">비밀번호</label>
<input id="pw" type="password" aria-describedby="pw-hint">
<p id="pw-hint">영문, 숫자를 포함해 8자 이상 입력하세요.</p>

도움말 + 오류 메시지

HTML
<input id="pw" type="password" aria-invalid="true" aria-describedby="pw-hint pw-err">
<p id="pw-hint">영문, 숫자를 포함해 8자 이상 입력하세요.</p>
<p id="pw-err" class="error">숫자가 포함되지 않았습니다.</p>

오류를 표시·제거하는 스크립트

JavaScript
function setError(input, errorEl, message) {
  var ids = (input.getAttribute('aria-describedby') || '').split(' ').filter(Boolean);
  var i = ids.indexOf(errorEl.id);
  if (message) {
    errorEl.textContent = message;
    errorEl.hidden = false;
    if (i === -1) ids.push(errorEl.id);
    input.setAttribute('aria-invalid', 'true');
  } else {
    errorEl.hidden = true;
    if (i !== -1) ids.splice(i, 1);
    input.removeAttribute('aria-invalid');
  }
  input.setAttribute('aria-describedby', ids.join(' '));
}

설명에 핵심 정보를 넣은 경우 (비권장)

비권장HTML
<input type="text" aria-describedby="hint">
<p id="hint">이메일</p>

“이메일”은 필드의 이름입니다. 설명은 생략될 수 있으므로 이름은 <label>로 제공합니다.

직접 해 보기

비밀번호를 입력하고 “확인”을 누르세요. 조건을 만족하지 못하면 오류 메시지 ID가 aria-describedby에 추가됩니다.

영문, 숫자를 포함해 8자 이상 입력하세요.

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
도움말이 연결된 비밀번호 필드에 포커스비밀번호, 편집 창, 보호됨, 영문, 숫자를 포함해 8자 이상 입력하세요.
오류 발생 후 다시 포커스비밀번호, 편집 창, 잘못된 입력, 영문, 숫자를 포함해 8자 이상 입력하세요. 숫자가 포함되지 않았습니다.
설명이 연결된 “삭제” 버튼에 포커스삭제, 버튼, 삭제한 파일은 복구할 수 없습니다.

사용 지침

이렇게 쓰세요

  • 입력 형식·조건 같은 부가 정보를 이름과 분리해 연결합니다.
  • 오류 메시지가 생기면 ID를 추가하고, 오류가 사라지면 ID를 제거합니다.
  • 대화상자의 핵심 안내 문단을 대화상자 설명으로 연결합니다.
  • 여러 설명을 연결할 때는 읽혀야 할 순서대로 ID를 나열합니다.

이렇게 쓰지 마세요

  • 조작에 꼭 필요한 정보를 설명에만 넣지 않습니다. 설명은 생략될 수 있습니다.
  • 목록·링크가 들어 있는 긴 영역을 설명으로 연결하지 않습니다. 구조가 사라집니다. aria-details를 검토합니다.
  • 오류가 해결된 뒤에도 오류 메시지 ID를 남겨 두지 않습니다.
  • 존재하지 않거나 중복된 ID를 참조하지 않습니다.

사용할 수 있는 역할

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

textboxcomboboxcheckboxbuttondialogalertdialogradiogrouptooltiplink
aria-labelledbyaria-labelaria-descriptionaria-detailsaria-errormessagearia-invalid

이 속성을 쓰는 패턴

폼 오류 검증모달 대화상자툴팁

참고 자료