Slider
네이티브 input[type="range"] 기반 슬라이더 — 키보드/ARIA는 네이티브가 보장하고, 토큰 스타일 트랙·썸에 현재값 라벨(showValue) 옵션. 비제어(defaultValue) 우선.
마지막 업데이트 2026-06-11
한눈에#
볼륨·밝기처럼 정확한 숫자보다 “대략 어느 정도”가 중요한 단일 연속값을 어림으로 조절합니다.
- 네이티브 input range
- 단일 연속값
- showValue 라벨
- 44px 히트 영역
키보드·ARIA는 네이티브가 보장하고, 트랙·썸만 토큰으로 스타일합니다
사용 시점#
단일 연속값을 어림잡아 조절하면 Slider — 두 값(범위)이나 정밀 정수는 다른 컴포넌트입니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 볼륨·밝기·불투명도처럼 단일 연속값을 어림으로 조절(정확한 숫자보다 시각이 중요)
대신 RangeSlider — 가격대·연식처럼 시작~끝 두 값(범위)을 고를 때
대신 QuantityStepper — 수량처럼 정수를 정밀하게 증감해야 할 때
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
Slider를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형#
크기#
단일 크기입니다 — 4px(space.1) 트랙 + 18px(icon.size-md) 썸. 입력 높이는
control.height-md(44px)로 썸보다 큰 터치 타깃을 확보합니다.
상태#
- Focus — 썸
:focus-visible에 primary 링 (Tab으로 확인하세요) - Disabled — 트랙·썸이
color.border-subtle/color.border톤으로 가라앉고 커서 차단
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
defaultValue | number | — | 초기값 — 없으면 (min+max)/2 (네이티브 range 규칙). 이후 상태는 내부 소유 |
showValue | boolean | false | 현재값 라벨 표시 — 시각 보조용(스크린리더는 네이티브 슬라이더 값 읽음) |
formatLabel | (value: number) => ReactNode | — | 라벨 포매터 — 예: (v) => ${v}% (ADR-012 B-P1) |
showTicks | boolean | false | step 간격 눈금 표시 — 네이티브 datalist (step 필요) (ADR-012 B-P1) |
ref | Ref<HTMLInputElement> | — | 네이티브 <input type="range">로 직결되는 ref (React 19 ref-as-prop) |
className은 래퍼(div)에 적용됩니다 — 폭 제어 등 레이아웃 조정용.
접근성#
네이티브 input[type="range"]라 키보드·ARIA가 브라우저에서 보장됩니다.
| 키 | 동작 (네이티브) |
|---|---|
→ / ↑ | step만큼 증가 |
← / ↓ | step만큼 감소 |
Home / End | min / max로 점프 |
PageUp / PageDown | 큰 단위 이동 (브라우저 기본) |
- 스크린리더는 네이티브 슬라이더의 값·범위를 그대로 읽습니다 —
showValue라벨은 중복 낭독을 막기 위해aria-hidden formatLabel제공 시aria-valuetext노출 — SR이 원시 숫자(“50”) 대신 포맷된 값(“50%“)을 읽도록 입력에aria-valuetext를 달아 화면 표시와 일치시킵니다 (문자열·숫자 포맷만 직렬화, 복합 노드는 네이티브 값 낭독으로 폴백)- 라벨은 소비자 책임 —
aria-label또는 외부<label htmlFor>연결
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| 트랙 | color.border-subtle · 높이 space.1 |
| 썸 | color.primary 채움 + shadow.sm · 크기 icon.size-md |
| 라운드 | radius.full |
| 히트 영역 | control.height-md (44px) |
| 값 라벨 | font.size-body-2 · color.text-muted |
| 비활성 | color.border-subtle 트랙 + color.border 썸 · color.text-placeholder 라벨 |