ARIA 접근성 가이드

역할 · 위젯

role="textbox"

자유롭게 글자를 입력하는 입력란입니다. 여러 줄이면 aria-multiline="true"를 씁니다.

기초HTML 요소 우선

한눈에 보기

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

설명

textbox는 자유 형식 텍스트를 입력받는 요소입니다. <input type="text">와 <textarea>가 이 역할을 기본으로 가지며, 커서 이동·선택·복사·붙여넣기·실행 취소·맞춤법 검사·IME(한글 조합)·자동완성까지 브라우저가 처리합니다. contenteditable 요소에 role="textbox"를 붙이는 것은 서식 있는 편집기처럼 네이티브로 불가능한 경우에만 합니다.

placeholder는 라벨이 아닙니다

입력을 시작하면 사라지고 대비도 낮아 라벨을 대신할 수 없습니다. 모든 입력란에 보이는 <label>을 붙이고, 형식 안내는 aria-describedby로 연결합니다.

테스터 관점

  • 라벨이 프로그램적으로 연결되었는지(라벨 클릭 시 입력란에 포커스) 확인합니다.
  • 오류가 생기면 aria-invalid="true"와 오류 메시지가 함께 읽히는지 확인합니다.
  • 직접 만든 편집 영역에서 한글 입력, 붙여넣기, 실행 취소가 정상 동작하는지 확인합니다.

함께 쓰는 속성

지원 속성

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

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

키보드 동작

키보드 동작
키동작
글자 키글자를 입력합니다.
← / →커서를 한 글자씩 옮깁니다. Ctrl을 함께 누르면 단어 단위로 이동합니다.
Home / End줄의 처음/끝으로 커서를 옮깁니다.
Shift + ←글자를 선택합니다(방향에 따라 →, Home, End와 조합).
Enter한 줄 입력란: 폼을 제출합니다. 여러 줄 입력란(aria-multiline="true"): 줄을 바꿉니다.
Tab다음 포커스 요소로 이동합니다. 입력란 안에 탭 문자를 넣지 않습니다(코드 편집기 등 예외는 빠져나가는 방법을 안내).

사용 예

네이티브 입력란

권장권장
<label for="email">이메일</label>
<input type="email" id="email" autocomplete="email" required aria-describedby="email-hint">
<p id="email-hint">예: name@example.com</p>

<label for="memo">요청 사항</label>
<textarea id="memo" rows="3"></textarea>

contenteditable 편집 영역

네이티브로 불가능한 서식 편집기에서만 씁니다.

HTML
<p id="cmt-label">댓글</p>
<div role="textbox" contenteditable="true" aria-multiline="true"
     aria-labelledby="cmt-label" aria-placeholder="댓글을 입력하세요"></div>

오류 상태 알리기

JavaScript
if (!valid) {
  input.setAttribute('aria-invalid', 'true');
  input.setAttribute('aria-errormessage', 'email-err');
  document.getElementById('email-err').hidden = false;
}

div에 역할만 붙이는 실수

비권장비권장
<div role="textbox">이름</div>
<!-- 편집도 포커스도 되지 않습니다. 역할은 기능을 만들어 주지 않습니다 -->

직접 해 보기

두 입력란을 비교해 보세요. 위는 네이티브 <textarea>, 아래는 contenteditable + role="textbox"입니다. 아래 편집 영역은 비어 있을 때만 힌트를 보여 주도록 스크립트로 처리합니다.

댓글 (role="textbox")

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
빈 입력란에 포커스이메일, 편집창, 필수, 비어 있음, 예: name@example.com
여러 줄 입력란에 포커스요청 사항, 편집창, 여러 줄
오류 상태 입력란이메일, 편집창, 유효하지 않은 항목

사용 지침

이렇게 쓰세요

  • 가능하면 <input>/<textarea>와 <label>을 씁니다.
  • 알맞은 type, autocomplete, inputmode로 입력을 돕습니다(WCAG 1.3.5).
  • 직접 만든 편집 영역은 contenteditable로 실제 편집이 되게 하고, 이름과 aria-multiline을 붙입니다.

이렇게 쓰지 마세요

  • placeholder나 aria-placeholder만으로 이름을 대신하지 않습니다.
  • 편집할 수 없는 요소에 role="textbox"만 붙이지 않습니다.
  • 팝업 제안 목록이 있는 입력란을 textbox로만 두지 않습니다. combobox를 씁니다.
searchboxcomboboxspinbutton

이 역할을 쓰는 패턴

폼 오류 검증콤보박스(자동완성)

참고 자료