ARIA 접근성 가이드

속성 · 값·범위

aria-valuetext

현재 값을 숫자 대신 사람이 이해하기 쉬운 문장으로 알립니다. (예: "보통", "오후 3시", "70,000원")

중급

한눈에 보기

구분
속성 (Property)
분류
값·범위
값 형식
문자열 (string)
기본값
없음
적용 범위
특정 역할에만 사용
HTML 대체
없음 (네이티브 <input type="range">에도 같은 목적으로 aria-valuetext를 씁니다)

설명

aria-valuetext는 aria-valuenow의 숫자를 사람이 읽기 좋은 텍스트로 바꿔 알려 줍니다. 이 속성이 있으면 보조기술은 숫자 대신 이 텍스트를 읽습니다. 예를 들어 글자 크기 슬라이더의 값이 1~5라면 aria-valuenow="3"과 함께 aria-valuetext="보통"을 넣어 "3" 대신 "보통"이 들리게 합니다.

명세는 숫자만으로 값을 의미 있게 표현할 수 없을 때만 쓰라고 권고합니다. 단계 이름(작게·보통·크게), 요일·시간, 통화·단위가 중요한 값(70,000원, 영하 18도), "12개 중 6개 완료"처럼 문맥이 필요한 진행률이 대표적입니다. 단순한 0~100 숫자라면 굳이 넣지 않아도 됩니다.

aria-valuetext를 쓰더라도 aria-valuenow는 함께 유지합니다. 일부 보조기술은 숫자 값으로 위치를 계산하기 때문입니다(값을 알 수 없는 불확정 진행 표시줄만 예외). 두 속성은 늘 같은 값을 가리켜야 하므로, 값이 바뀔 때 함께 갱신합니다.

텍스트는 짧고 값 자체에 집중해야 합니다. 값이 바뀔 때마다 읽히기 때문에 "현재 선택된 글자 크기는 보통입니다"처럼 길면 조작할 때마다 같은 말이 반복됩니다. 이름(“글자 크기”)은 접근 가능한 이름에, 값(“보통”)만 이 속성에 넣습니다. 네이티브 <input type="range">에도 aria-valuetext를 붙일 수 있습니다.

검수할 때는 값을 바꿀 때마다 텍스트가 같이 바뀌는지(처음 값에 멈춰 있지 않은지), 숫자 값과 텍스트가 같은 상태를 가리키는지, 텍스트에 이름이 중복되지 않았는지 확인합니다.

값

값
값의미
<문자열>현재 값을 사람이 읽기 좋게 표현한 텍스트입니다. (예: 보통, 오후 3시, 70,000원)

사용 예

단계 이름을 읽어 주는 슬라이더

권장HTML
<span id="fs-label">글자 크기</span>
<div role="slider" tabindex="0" aria-labelledby="fs-label"
     aria-valuemin="1" aria-valuemax="5"
     aria-valuenow="3" aria-valuetext="보통"></div>

값과 텍스트를 함께 갱신하기

JavaScript
const LABELS = ['아주 작게', '작게', '보통', '크게', '아주 크게'];
function setSize(slider, v) {
  slider.setAttribute('aria-valuenow', String(v));
  slider.setAttribute('aria-valuetext', LABELS[v - 1]);
}

숫자만 있을 때와 문장이 필요한 때

HTML
<!-- 비권장: 이름이 반복되고 문장이 길어 조작할 때마다 다 읽힘 -->
<div role="slider" aria-label="온도" aria-valuenow="22"
     aria-valuetext="현재 온도 설정 값은 섭씨 22도입니다"
     aria-valuemin="16" aria-valuemax="30" tabindex="0"></div>

<!-- 권장: 값만 짧게 -->
<div role="slider" aria-label="온도" aria-valuenow="22"
     aria-valuetext="섭씨 22도"
     aria-valuemin="16" aria-valuemax="30" tabindex="0"></div>

네이티브 range 입력에 붙이기

권장HTML
<label for="day">요일</label>
<input type="range" id="day" min="1" max="7" value="3" aria-valuetext="수요일">

직접 해 보기

글자 크기 슬라이더입니다. 값을 바꾸면 aria-valuenow와 aria-valuetext가 함께 바뀝니다. 화면낭독기는 숫자 대신 "보통", "크게"처럼 텍스트를 읽습니다.

글자 크기

방향키로 1씩, Page Up / Page Down으로 1씩, Home / End로 최솟값·최댓값으로 이동합니다. 마우스로 트랙을 눌러도 됩니다.

화면낭독기에서는

화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
상황들리는 안내 (예)
슬라이더에 포커스글자 크기, 슬라이더, 보통
오른쪽 방향키를 누름크게
aria-valuetext가 없을 때 같은 조작4

사용 지침

이렇게 쓰세요

  • 숫자만으로 의미가 전달되지 않을 때(단계 이름, 시간, 통화·단위)만 씁니다.
  • aria-valuenow와 항상 같은 값을 가리키도록 함께 갱신합니다.
  • 짧게 값만 적습니다. 이름은 aria-label이나 aria-labelledby로 따로 줍니다.
  • 화면에 보이는 값 표기와 같은 표현을 씁니다.

이렇게 쓰지 마세요

  • 값이 바뀌어도 처음 텍스트를 그대로 두지 않습니다.
  • aria-valuenow 없이 aria-valuetext만 쓰지 않습니다(불확정 진행 표시줄 제외).
  • 조작 방법 안내("방향키로 조절하세요")를 넣지 않습니다. 필요한 안내는 aria-describedby로 연결합니다.

사용할 수 있는 역할

sliderspinbuttonprogressbarmeterscrollbarseparator
aria-valuenowaria-valueminaria-valuemaxaria-labelaria-describedby

이 속성을 쓰는 패턴

슬라이더

참고 자료