ARIA 접근성 가이드

속성 · 값·범위

aria-valuemax

범위 위젯이 가질 수 있는 가장 큰 값을 숫자로 알립니다.

기초

한눈에 보기

구분
속성 (Property)
분류
값·범위
값 형식
숫자 (number)
기본값
100 (spinbutton: 없음)
적용 범위
특정 역할에만 사용
HTML 대체
<input type="range">·<input type="number">·<meter>의 max, <progress>의 max

설명

aria-valuemax는 slider, spinbutton, progressbar, meter, scrollbar, 포커스를 받을 수 있는 separator처럼 범위 안에서 값을 가지는 요소(범위 위젯)의 최댓값을 정합니다. 값은 정수뿐 아니라 소수도 쓸 수 있으며, 반드시 aria-valuemin보다 크거나 같아야 합니다.

보조기술은 최솟값·최댓값·현재 값을 함께 사용해 위치를 계산합니다. 특히 progressbar와 scrollbar는 화면낭독기가 현재 값을 백분율로 바꿔 읽는 경우가 많기 때문에, 최댓값이 틀리면 "50%"여야 할 진행률이 엉뚱한 숫자로 안내됩니다. 최댓값을 알 수 있는 위젯이라면 명시적으로 넣는 것이 안전합니다.

aria-valuemax를 생략하면 역할마다 정해진 기본값이 쓰입니다. slider, scrollbar, progressbar, meter, separator는 100이고, spinbutton은 최댓값이 없음으로 처리됩니다. 실제 범위가 0~100이 아니라면 기본값에 기대지 말고 값을 적어야 합니다.

최댓값은 고정값일 필요가 없습니다. 가격 범위처럼 손잡이가 두 개인 슬라이더에서는 "최저 가격" 손잡이의 최댓값이 "최고 가격" 손잡이의 현재 값과 같아지도록 스크립트로 함께 갱신합니다(APG Multi-Thumb Slider). 이렇게 하면 화면낭독기 사용자도 손잡이가 더 움직일 수 없는 이유를 알 수 있습니다.

검수할 때는 접근성 트리(개발자 도구의 Accessibility 패널)에서 해당 요소의 max 값이 화면에 보이는 최댓값과 같은지, aria-valuenow가 최댓값을 넘는 순간이 없는지, End 키를 눌렀을 때 현재 값이 최댓값과 일치하는지 확인합니다. 네이티브 <input type="range">를 쓸 수 있다면 max 속성만으로 충분하므로 ARIA를 덧붙이지 않습니다.

값

값
값의미
<숫자>범위의 최댓값입니다. 소수도 쓸 수 있으며 aria-valuemin보다 크거나 같아야 합니다. (예: 100, 5, 1.0)
(생략) 기본값slider·scrollbar·progressbar·meter·separator는 100으로, spinbutton은 최댓값이 없는 것으로 처리됩니다.

사용 예

0~10 범위의 음량 슬라이더

권장HTML
<span id="vol-label">음량</span>
<div role="slider" tabindex="0"
     aria-labelledby="vol-label"
     aria-valuemin="0" aria-valuemax="10" aria-valuenow="5">
  <span class="thumb"></span>
</div>

기본값(100)에 기댄 진행 표시줄

실제로는 파일 12개 중 6개를 처리한 상태인데 최댓값을 적지 않아, 보조기술은 100 중 6 즉 "6%"로 계산합니다.

HTML
<!-- 비권장: 실제 범위는 0~12 -->
<div role="progressbar" aria-label="업로드" aria-valuenow="6"></div>

<!-- 권장 -->
<div role="progressbar" aria-label="업로드"
     aria-valuemin="0" aria-valuemax="12" aria-valuenow="6"
     aria-valuetext="파일 12개 중 6개 완료"></div>

가능하면 네이티브 <progress max="12" value="6">를 먼저 고려합니다.

다른 손잡이에 맞춰 최댓값 바꾸기

JavaScript
// 최저 가격 손잡이는 최고 가격 손잡이보다 커질 수 없습니다.
function syncRange(lowThumb, highThumb) {
  const high = highThumb.getAttribute('aria-valuenow');
  const low = lowThumb.getAttribute('aria-valuenow');
  lowThumb.setAttribute('aria-valuemax', high);
  highThumb.setAttribute('aria-valuemin', low);
}

네이티브 요소로 대체

권장HTML
<label for="vol">음량</label>
<input type="range" id="vol" min="0" max="10" value="5">

네이티브 range 입력은 최댓값·키보드 조작·접근성 정보를 브라우저가 모두 처리합니다.

직접 해 보기

가격 범위 슬라이더입니다. 최저 가격 손잡이를 움직이면 최고 가격 손잡이의 aria-valuemin이, 최고 가격 손잡이를 움직이면 최저 가격 손잡이의 aria-valuemax가 바뀝니다.

가격 범위

각 손잡이에서 방향키(5,000원 단위), Page Up / Page Down(20,000원 단위), Home / End를 눌러 보세요. 한 손잡이를 움직이면 다른 손잡이의 aria-valuemin 또는 aria-valuemax가 함께 바뀝니다.

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
0~10 슬라이더에 포커스음량, 슬라이더, 5
End 키를 누름10
최댓값 12, 현재 값 6인 진행 표시줄업로드, 진행 표시줄, 50%
최댓값을 생략한 같은 진행 표시줄업로드, 진행 표시줄, 6%

사용 지침

이렇게 쓰세요

  • 최댓값을 알 수 있는 범위 위젯에는 aria-valuemin과 함께 명시합니다.
  • aria-valuenow가 항상 aria-valuemin 이상, aria-valuemax 이하가 되도록 스크립트에서 값을 제한합니다.
  • 두 손잡이 슬라이더처럼 범위가 서로 묶여 있으면 한쪽이 바뀔 때 다른 쪽의 최댓값·최솟값도 함께 갱신합니다.
  • 화면에 보이는 최댓값(예: "최대 10")과 속성 값을 같게 유지합니다.

이렇게 쓰지 마세요

  • aria-valuemax를 aria-valuemin보다 작게 설정하지 않습니다.
  • 최댓값을 모르는 진행 상황(전체 크기를 알 수 없는 다운로드 등)에 임의의 최댓값을 넣지 않습니다. 이때는 aria-valuenow를 생략해 "진행 중(불확정)" 상태로 둡니다.
  • 네이티브 <input type="range">에 max와 다른 aria-valuemax를 덧붙이지 않습니다.
  • "100"이라는 기본값이 실제 범위와 다른데도 생략하지 않습니다.

사용할 수 있는 역할

sliderspinbuttonprogressbarmeterscrollbarseparator
aria-valueminaria-valuenowaria-valuetextaria-orientation

이 속성을 쓰는 패턴

슬라이더

참고 자료