v0.10.0

ComponentsP3 본문

Slider

네이티브 input[type="range"] 기반 슬라이더 — 키보드/ARIA는 네이티브가 보장하고, 토큰 스타일 트랙·썸에 현재값 라벨(showValue) 옵션. 비제어(defaultValue) 우선.

마지막 업데이트 2026-06-11

한눈에#

볼륨·밝기처럼 정확한 숫자보다 "대략 어느 정도"가 중요한 단일 연속값을 어림으로 조절합니다.

  • 네이티브 input range
  • 단일 연속값
  • showValue 라벨
  • 44px 히트 영역

키보드·ARIA는 네이티브가 보장하고, 트랙·썸만 토큰으로 스타일합니다

사용 시점#

단일 연속값을 어림잡아 조절하면 Slider — 두 값(범위)이나 정밀 정수는 다른 컴포넌트입니다.

쓴다

볼륨·밝기·불투명도처럼 단일 연속값을 어림으로 조절(정확한 숫자보다 시각이 중요)

대신 RangeSlider
RangeSlider

가격대·연식처럼 시작~끝 두 값(범위)을 고를 때

대신 QuantityStepper
QuantityStepper

수량처럼 정수를 정밀하게 증감해야 할 때

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { Slider } from '@wds/ui-web';

<Slider aria-label="볼륨" step={10} />

변형#

showValue — 현재값 라벨이 실시간 갱신
min · max · step — 네이티브 속성 그대로

크기#

단일 크기입니다 — 4px(space.1) 트랙 + 18px(icon.size-md) 썸. 입력 높이는 control.height-md(44px)로 썸보다 큰 터치 타깃을 확보합니다.

상태#

Disabled
  • Focus — 썸 :focus-visible에 primary 링 (Tab으로 확인하세요)
  • Disabled — 트랙·썸이 color.border-subtle/color.border 톤으로 가라앉고 커서 차단

Props#

Prop타입기본값설명
defaultValuenumber—초기값 — 없으면 (min+max)/2 (네이티브 range 규칙). 이후 상태는 내부 소유
showValuebooleanfalse현재값 라벨 표시 — 시각 보조용(aria-hidden)
min · max · stepnumber0 · 100 · —네이티브 range 속성 그대로 전달
formatLabel(value: number) => ReactNode—showValue 라벨 포매터(예: (v) => `${v}%`) + SR용 aria-valuetext 노출 (ADR-012 B-P1)
showTicksbooleanfalsestep 간격 눈금(네이티브 datalist) — step이 있어야 표시, 과다 시 생략 (ADR-012 B-P1)
…restOmit<InputHTMLAttributes, 'type' | 'value' | 'defaultValue'>—aria-label · onChange(네이티브 이벤트) · disabled 등 전달

className은 래퍼(div)에 적용됩니다 — 폭 제어 등 레이아웃 조정용.

접근성#

네이티브 input[type="range"]라 키보드·ARIA가 브라우저에서 보장됩니다.

키동작 (네이티브)
→ / ↑step만큼 증가
← / ↓step만큼 감소
Home / Endmin / 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 라벨