ARIA 접근성 가이드

속성 · 위젯 상태

aria-autocomplete

입력하는 동안 입력값을 예측해 제안하는 방식(목록, 입력란 안 자동 채움, 둘 다)을 알립니다.

중급

한눈에 보기

구분
속성 (Property)
분류
위젯 상태
값 형식
토큰 (inline / list / both / none)
기본값
none
적용 범위
특정 역할에만 사용
HTML 대체
<input list> + <datalist> (브라우저 기본 제안)

설명

aria-autocomplete는 텍스트 입력 요소(combobox, textbox, searchbox)가 사용자가 입력하는 동안 어떤 방식으로 완성 제안을 보여 주는지 알려 줍니다. 제안이 목록으로 나오는지(list), 입력란 안에 남은 글자가 선택된 상태로 미리 채워지는지(inline), 둘 다인지(both)를 화면낭독기 사용자가 미리 알 수 있게 합니다.

주로 콤보 상자 패턴의 입력란에 씁니다. 검색어 추천, 주소·도시 검색, 받는 사람 입력처럼 입력값으로 목록을 걸러 보여 주는 위젯이라면 list, 첫 번째 일치 항목을 입력란에 바로 채워 주기까지 한다면 both를 씁니다. 제안 목록이 따로 뜨는 경우에는 입력란에 aria-controls(목록 ID), aria-expanded(목록이 보이는지), 목록 안에서 강조된 항목을 가리키는 aria-activedescendant를 함께 씁니다.

이 속성은 동작을 만들어 주지 않습니다. 값이 list라면 실제로 목록을 보여 주고, 방향키로 항목을 고르고, Enter로 확정하고, Esc로 닫는 기능을 스크립트로 구현해야 합니다. 값과 실제 동작이 다르면(예: both라고 했는데 입력란 자동 채움이 없음) 사용자는 기대와 다른 결과를 듣게 됩니다.

HTML의 autocomplete 속성(예: autocomplete="email")과는 다릅니다. HTML autocomplete는 브라우저가 저장된 개인정보를 채우도록 입력 목적을 알리는 것(WCAG 1.3.5 입력 목적 식별)이고, aria-autocomplete는 페이지 스크립트가 제공하는 제안 방식을 알리는 것입니다. 사용자 정의 제안 목록을 쓸 때는 브라우저 자동 완성 목록과 겹치지 않도록 autocomplete="off"를 함께 쓰는 경우가 많습니다.

테스트할 때는 입력란에 포커스했을 때 화면낭독기가 자동 완성 지원을 알리는지, 글자를 입력하면 제안 개수나 목록 표시가 전달되는지, 방향키로 항목을 이동할 때 항목 이름이 읽히는지, 한글 입력(IME 조합) 중에도 자동 채움이 글자를 망가뜨리지 않는지 확인합니다.

값

값
값의미
inline입력하는 동안 예측한 나머지 글자를 입력란 안에 채우고, 채운 부분을 선택 상태로 둡니다. 계속 입력하면 덮어씁니다.
list입력값에 따라 걸러진 제안을 별도의 목록(listbox 등)으로 보여 줍니다.
both제안 목록을 보여 주고, 동시에 첫 번째 제안의 나머지 글자를 입력란 안에 채웁니다.
none 기본값자동 완성 제안을 하지 않습니다. 목록이 있더라도 입력값에 따라 걸러지지 않습니다.

사용 예

목록형 자동 완성 콤보 상자

권장HTML
<label for="city">도시</label>
<input id="city" type="text" role="combobox"
       aria-autocomplete="list" aria-expanded="true"
       aria-controls="city-list" aria-activedescendant="city-opt-2" autocomplete="off">
<ul id="city-list" role="listbox" aria-label="도시 제안">
  <li id="city-opt-1" role="option" aria-selected="false">부산</li>
  <li id="city-opt-2" role="option" aria-selected="true">부천</li>
</ul>

목록을 걸러 보여 주는 스크립트

JavaScript
input.addEventListener('input', function () {
  var q = input.value.trim();
  var matches = cities.filter(function (c) { return q && c.indexOf(q) === 0; });
  renderOptions(matches);                      // role="option" 항목 다시 그리기
  list.hidden = matches.length === 0;
  input.setAttribute('aria-expanded', String(matches.length > 0));
  input.removeAttribute('aria-activedescendant');
  status.textContent = matches.length ? '제안 ' + matches.length + '개' : '';
});

값과 동작이 다른 경우 (비권장)

비권장HTML
<input type="text" role="combobox" aria-autocomplete="both"
       aria-expanded="false" aria-controls="tag-list">

입력란 자동 채움 기능이 없는데 both로 표시하면 사용자에게 잘못된 기대를 줍니다. 실제 동작이 목록뿐이면 list를 씁니다.

직접 해 보기

값을 바꾼 뒤 입력란에 “부”, “대”, “서” 등을 입력해 보세요. 아래 방향키로 제안을 고르고 Enter로 확정, Esc로 닫습니다.

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
aria-autocomplete="list" 콤보 상자에 포커스도시, 콤보 상자, 축소됨, 자동 완성, 편집 창
“부”를 입력제안 2개
아래 방향키로 제안 이동부산, 1/2
Enter로 확정부산 선택됨

사용 지침

이렇게 쓰세요

  • 제안 방식과 똑같은 값을 씁니다. 목록만 있으면 list, 자동 채움도 하면 both입니다.
  • 목록을 쓰면 aria-expanded, aria-controls, aria-activedescendant를 함께 관리합니다.
  • 제안 개수처럼 화면에만 보이는 변화는 상태 메시지(role="status")로 알립니다.
  • 한글 IME 조합 중에는 입력란 자동 채움을 하지 않도록 처리합니다.

이렇게 쓰지 마세요

  • HTML autocomplete(입력 목적) 대신 쓰지 않습니다. 두 속성은 목적이 다릅니다.
  • 버튼·체크 상자 등 텍스트 입력이 아닌 요소에 쓰지 않습니다.
  • 속성만 붙이고 키보드로 제안을 고르는 기능을 빠뜨리지 않습니다.

사용할 수 있는 역할

comboboxtextboxsearchbox
aria-activedescendantaria-controlsaria-expandedaria-haspopup

이 속성을 쓰는 패턴

콤보박스(자동완성)리스트박스

참고 자료