Toggle
먼저 보고, 그다음 계약을 읽습니다
하나의 on/off 누름 상태를 갖는 단일 standalone 토글 버튼.
Component intent의도와 경계 읽기
음소거·별표·굵게처럼 **하나의** 눌림(pressed) 상태가 필요한 곳에 쓰는 두-상태 누름 버튼. 네이티브 <button type="button"> 에 aria-pressed 만 얹은 외부 dep 0 구현이며 스타일은 100% CSS 클래스(.axe-toggle)로 처리한다. 묶음이 필요하면 ToggleGroup, 폼 필드 의미의 켜짐/꺼짐이면 Switch, 항상 하나만 선택되는 필수 선택이면 Seg 를 쓴다. controlled 전용 — pressed/onPressedChange 를 항상 함께 넘긴다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { Toggle } from "@axe/ui";import { useState } from "react";function MuteButton() { const [muted, setMuted] = useState(false); return ( <Toggle pressed={muted} onPressedChange={setMuted} ariaLabel="음소거"> {muted ? "🔇" : "🔈"} </Toggle> );}<button type="button" class="axe-toggle" aria-pressed="true" aria-label="별표">★</button>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
pressed | boolean | 필수 | — | 눌린 상태 (controlled). |
onPressedChange | (pressed: boolean) => void | 필수 | — | 토글 콜백 — 다음 pressed 값을 인자로 넘김. |
size | "sm" | "md" | — | "md" | 버튼 크기. |
disabled | boolean | — | false | 비활성화 — 네이티브 disabled 속성. |
ariaLabel | string | — | — | 접근성 라벨 — 아이콘-only(가시 텍스트 없음)일 때 필수. |
...rest | Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange' | 'aria-pressed' | 'type'> | — | — | className·children·onClick 등 나머지는 루트 <button> 으로 전파. 소비자 onClick 은 내부 onPressedChange 보다 먼저 호출되며 e.preventDefault() 하면 그 클릭의 토글을 억제한다. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-toggle | stable | 토글 버튼 루트 — 자체 border/bg 를 들고 다니는 standalone 변형. |
.axe-toggle--sm | stable | sm 크기 변형 (높이 24px). |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- Enter/Space 로 눌러 pressed 토글 (네이티브 <button>)
네이티브 <button type="button"> 에 aria-pressed={pressed}(true/false) 로 눌림 상태 표시 — toggle button 패턴. 아이콘-only 일 땐 ariaLabel 로 접근명을 반드시 제공(없으면 접근명 부재).
disabled 시 네이티브 disabled 속성 부여 → 포커스·클릭 불가. pressed 는 클래스가 아니라 aria-pressed 속성으로만 표현된다.