ARIA 접근성 가이드

속성 · 관계

aria-setsize

목록·트리·메뉴 같은 집합의 전체 항목 수를 알립니다. 모르면 -1을 씁니다.

중급

한눈에 보기

구분
속성 (Property)
분류
관계
값 형식
정수 (integer), 전체 개수 또는 -1
기본값
자동 계산
적용 범위
특정 역할에만 사용
HTML 대체
<ol>·<ul>, <select> (모든 항목이 DOM에 있으면 브라우저가 자동 계산)

설명

aria-setsize는 항목이 속한 집합의 전체 개수를 알립니다. aria-posinset와 짝을 이루어 "16개 중 5번째"의 "16"을 담당합니다. 이름과 달리 컨테이너가 아니라 집합의 각 구성원(listitem, option, treeitem, menuitem, radio, tab, row, article 등)에 붙입니다.

모든 항목이 DOM에 있다면 브라우저가 자동으로 계산하므로 필요 없습니다. 가상 스크롤, 페이지 단위 로딩, 무한 스크롤처럼 일부만 DOM에 있을 때 실제 전체 개수를 알리려고 씁니다.

전체 개수를 알 수 없으면 -1을 넣습니다(명세 권고). 무한 스크롤 피드처럼 끝이 정해지지 않은 경우입니다. 이때 화면낭독기는 위치만 읽고 전체 개수는 읽지 않습니다. 메뉴에서는 separator를 빼고 셉니다.

같은 집합의 항목들은 모두 같은 값을 가져야 합니다. 서버에서 전체 개수가 바뀌면(새 항목 추가, 필터 변경) 화면에 있는 모든 항목의 값을 함께 갱신합니다.

검수할 때는 일부만 렌더링된 목록에서 화면낭독기가 실제 전체 개수를 읽는지, 화면에 표시된 "총 50건" 같은 숫자와 일치하는지, 같은 집합 안에서 값이 서로 다르지 않은지 확인합니다.

값

값
값의미
<정수 ≥ 1>집합의 전체 항목 수입니다.
-1전체 개수를 알 수 없습니다. 보조기술은 전체 개수를 계산하거나 안내하지 않습니다.
(생략) 기본값브라우저가 DOM 안 형제 항목 수를 세어 자동 계산합니다.

사용 예

전체 200개 중 일부만 렌더링한 옵션

권장HTML
<ul role="listbox" aria-label="국가" tabindex="0">
  <li role="option" aria-setsize="200" aria-posinset="41" aria-selected="false">대한민국</li>
  <li role="option" aria-setsize="200" aria-posinset="42" aria-selected="false">덴마크</li>
</ul>

끝을 모르는 피드

권장HTML
<div role="feed" aria-label="새 소식">
  <article aria-posinset="1" aria-setsize="-1">...</article>
  <article aria-posinset="2" aria-setsize="-1">...</article>
</div>

전체 개수가 바뀌면 모두 갱신

JavaScript
function updateTotal(list, total) {
  list.querySelectorAll('[aria-setsize]').forEach((item) => {
    item.setAttribute('aria-setsize', String(total));
  });
}

컨테이너에 붙임

비권장HTML
<!-- 비권장: 컨테이너에는 효과가 없습니다 -->
<ul aria-setsize="200">
  <li>대한민국</li>
</ul>

직접 해 보기

전체 50건 중 4건만 그리는 목록입니다. "전체 개수를 모르는 경우"를 체크하면 모든 항목의 aria-setsize가 -1로 바뀝니다.

최근 주문 (전체 50건 중 4건만 DOM에 그려진 목록)

    화면낭독기에서는

    화면낭독기 안내 예시 (표현은 화면낭독기·브라우저·버전에 따라 조금씩 다릅니다)
    상황들리는 안내 (예)
    목록 항목에 도달 (setsize="50")주문 #1001, 50개 중 1
    같은 항목 (setsize="-1")주문 #1001, 1 (전체 개수 생략)
    속성 없이 4개만 렌더링된 경우주문 #1001, 4개 중 1

    사용 지침

    이렇게 쓰세요

    • 집합의 일부만 DOM에 있을 때 각 항목에 넣습니다.
    • 전체 개수를 모르면 -1을 씁니다.
    • 같은 집합의 모든 항목에 같은 값을 넣고, 전체 개수가 바뀌면 함께 갱신합니다.

    이렇게 쓰지 마세요

    • 컨테이너 요소에 붙이지 않습니다.
    • 실제보다 크거나 작은 추정값을 넣지 않습니다. 모르면 -1입니다.
    • 모든 항목이 DOM에 있는 일반 목록에 불필요하게 넣지 않습니다.

    사용할 수 있는 역할

    listitemoptiontreeitemmenuitemmenuitemcheckboxmenuitemradioradiotabrowarticle
    aria-posinsetaria-levelaria-rowcountaria-busy

    이 속성을 쓰는 패턴

    리스트박스

    참고 자료