ARIA 접근성 가이드

역할 · 위젯

role="spinbutton"

위·아래 키나 증감 버튼으로 숫자 값을 한 단계씩 바꾸는 입력 요소입니다.

중급HTML 요소 우선

한눈에 보기

분류
위젯
대응 HTML
<input type="number">
이름 정하는 방법
작성자
이름 필수
예
필수 상위 요소
없음
필수 하위 요소
없음

설명

spinbutton은 정해진 단계로 값을 올리고 내리는 위젯입니다. 수량, 시·분, 날짜의 각 부분처럼 범위가 정해진 값을 고를 때 씁니다. 보통 텍스트 입력이 가능한 입력란 자체가 스핀버튼이고, 옆의 증감(+/−) 버튼은 마우스용 보조 수단입니다.

  • aria-valuenow — 현재 값. WAI-ARIA 1.2에서 필수는 아니며, 값이 없으면(빈 입력란) 생략합니다.
  • aria-valuemin · aria-valuemax — 슬라이더와 달리 기본값이 없습니다(제한 없음). 범위가 있다면 명시합니다.
  • aria-valuetext — “오후 3시”처럼 숫자와 다른 표현이 필요할 때 씁니다.

HTML <input type="number">가 같은 역할을 가지며 min, max, step을 지원합니다. 다만 전화번호·우편번호·카드 번호처럼 “숫자로 된 문자열”은 값을 올리고 내리는 대상이 아니므로 스핀버튼이 아니라 <input type="text" inputmode="numeric">를 씁니다.

증감 버튼은 탭 순서에서 빼도 됩니다

APG 예제는 +/− 버튼에 tabindex="-1"을 주어 키보드 사용자는 입력란 하나에서 방향키로 조절하게 합니다. 버튼에는 “수량 줄이기”처럼 이름을 붙여 마우스·터치 화면낭독기 사용자도 쓸 수 있게 합니다.

테스터 관점

  • ↑/↓로 값이 바뀌고 새 값이 읽히는지, 범위 끝에서 더 바뀌지 않는지 확인합니다.
  • 범위를 벗어난 값을 직접 입력했을 때 오류가 aria-invalid와 오류 메시지로 알려지는지 확인합니다.

함께 쓰는 속성

지원 속성

aria-activedescendantaria-disabledaria-errormessagearia-invalidaria-readonlyaria-requiredaria-valuemaxaria-valueminaria-valuenowaria-valuetext

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

키보드 동작

키보드 동작
키동작
↑값을 한 단계 올립니다.
↓값을 한 단계 내립니다.
Home최솟값이 있으면 최솟값으로 설정합니다.
End최댓값이 있으면 최댓값으로 설정합니다.
Page Up(선택 사항) 값을 큰 단위로 올립니다.
Page Down(선택 사항) 값을 큰 단위로 내립니다.
글자 키(편집 가능한 경우) 값을 직접 입력합니다. 커서 이동·삭제 등 텍스트 편집 키가 동작합니다.

사용 예

네이티브 숫자 입력

권장권장
<label for="qty">수량</label>
<input type="number" id="qty" min="1" max="10" value="1">

ARIA 스핀버튼 + 증감 버튼

HTML
<label for="qty2">수량</label>
<button type="button" tabindex="-1" aria-label="수량 줄이기" aria-controls="qty2">−</button>
<input type="text" id="qty2" role="spinbutton" inputmode="numeric"
       aria-valuemin="1" aria-valuemax="10" aria-valuenow="1" value="1">
<button type="button" tabindex="-1" aria-label="수량 늘리기" aria-controls="qty2">+</button>

값 텍스트가 필요한 경우

HTML
<div role="spinbutton" tabindex="0" aria-label="시"
     aria-valuemin="0" aria-valuemax="23" aria-valuenow="15" aria-valuetext="오후 3시">오후 3시</div>

전화번호에 쓰는 실수

비권장비권장
<input type="number" aria-label="휴대전화 번호">
<!-- 앞자리 0이 사라지고 방향키로 값이 바뀝니다. type="tel"을 씁니다 -->

직접 해 보기

입력란에 포커스를 두고 ↑/↓, Page Up/Page Down(5씩), Home/End로 바꿔 보세요. 숫자를 직접 입력할 수도 있습니다. 범위(1~20)를 벗어나면 오류가 표시됩니다.


화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
스핀버튼에 포커스인원 (1~20명), 스핀 버튼, 편집 가능, 2
↑로 값 올림3
범위를 벗어난 값을 입력유효하지 않은 항목, 1에서 20 사이의 숫자를 입력하세요.

사용 지침

이렇게 쓰세요

  • 가능하면 <input type="number">를 씁니다.
  • 범위가 있으면 aria-valuemin·aria-valuemax를 명시합니다.
  • 증감 버튼에는 “늘리기/줄이기” 이름을 붙입니다.

이렇게 쓰지 마세요

  • 전화번호·카드 번호처럼 값을 증감할 의미가 없는 숫자에 쓰지 않습니다.
  • 값이 비어 있는데 aria-valuenow에 이전 값을 남겨 두지 않습니다.
slidertextboxcombobox

이 역할을 쓰는 패턴

슬라이더폼 오류 검증

참고 자료