ARIA 접근성 가이드

역할 · 위젯

role="searchbox"

검색어를 입력하는 한 줄짜리 텍스트 입력란입니다. textbox의 하위 역할입니다.

기초HTML 요소 우선

한눈에 보기

분류
위젯
대응 HTML
<input type="search"> (list 속성이 없을 때)
이름 정하는 방법
작성자
이름 필수
예
필수 상위 요소
없음
필수 하위 요소
없음

설명

searchbox는 검색 기능에 쓰는 textbox입니다. 역할만 다를 뿐 키보드·속성은 텍스트 입력란과 같고, 보조기술이 “검색 편집창”처럼 용도를 알려 줍니다. HTML <input type="search">가 이 역할을 기본으로 가집니다(list 속성으로 자동완성 목록을 연결하면 combobox가 됩니다).

searchbox와 search는 다릅니다. search는 검색 폼 전체를 감싸는 랜드마크이고, searchbox는 그 안의 입력란입니다. 둘을 함께 쓰면 사용자는 랜드마크로 검색 영역을 바로 찾고, 입력란의 용도도 알 수 있습니다. HTML에는 <search> 요소도 있습니다.

검색 제안 목록이 뜬다면

입력하는 동안 제안 목록이 팝업으로 뜨는 검색창은 searchbox가 아니라 combobox 패턴으로 만들어야 합니다(aria-expanded, aria-controls, aria-activedescendant). 결과가 페이지에 바로 걸러져 보이는 방식이라면 결과 개수를 status로 알립니다.

테스터 관점

  • 보이는 라벨이나 aria-label로 이름이 있는지 확인합니다. placeholder만 있는 경우는 이름으로 의존하지 않습니다.
  • 검색 버튼(아이콘)에도 이름이 있는지, Enter로 검색되는지 확인합니다.
  • 결과 수가 바뀌면 알려지는지 확인합니다.

함께 쓰는 속성

지원 속성

aria-activedescendantaria-autocompletearia-disabledaria-errormessagearia-haspopuparia-invalidaria-multilinearia-placeholderaria-readonlyaria-required

전역 속성(이름·설명 등)은 모든 역할에 쓸 수 있어 생략했습니다.

키보드 동작

키보드 동작
키동작
글자 키검색어를 입력합니다. 커서 이동·선택·삭제 등 일반 텍스트 편집 키가 그대로 동작합니다.
Enter폼 안에 있으면 검색을 제출합니다.
Esc(브라우저에 따라) type="search"의 입력 내용을 지웁니다.

사용 예

검색 랜드마크 + 검색 입력란

권장권장
<search>
  <form action="/search">
    <label for="q">사이트 검색</label>
    <input type="search" id="q" name="q">
    <button type="submit">검색</button>
  </form>
</search>

ARIA로 역할만 지정

type="search"를 쓸 수 없을 때(예: 프레임워크 제약) 역할을 명시합니다.

HTML
<form role="search">
  <input type="text" role="searchbox" aria-label="상품 검색">
</form>

라벨 없이 placeholder만 쓰는 실수

비권장비권장
<input type="search" placeholder="검색">
<button><img src="search.svg"></button>   <!-- 버튼 이름도 없습니다 -->

직접 해 보기

검색어를 입력하면 아래 목록이 걸러지고, 결과 개수가 상태 메시지(role="status")로 알려집니다.

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
검색창에 포커스사이트 검색, 검색 편집창
검색 랜드마크로 이동검색 랜드마크, 사이트 검색, 검색 편집창

사용 지침

이렇게 쓰세요

  • 가능하면 <input type="search">를 쓰고 보이는 라벨을 붙입니다.
  • 검색 폼은 <search> 또는 role="search"로 감쌉니다.

이렇게 쓰지 마세요

  • placeholder만으로 이름을 대신하지 않습니다.
  • 제안 목록이 팝업으로 뜨는데 searchbox만 쓰고 콤보박스 속성을 빠뜨리지 않습니다.
  • 검색 랜드마크(search)와 검색 입력란(searchbox)을 혼동하지 않습니다.
textboxsearchcombobox

이 역할을 쓰는 패턴

콤보박스(자동완성)페이지 레이아웃(랜드마크)

참고 자료