Button

Button.Root가 컨트롤입니다. Button.Icon은 컴파운드 파트입니다. 아이콘 위치는 DOM 순서를 따릅니다. 아이콘은 장식용입니다(aria-hidden). 아이콘만 있는 루트는 Button.Root에 aria-label이나 aria-labelledby가 필요합니다.

아이콘만 있는 루트는 그 이름을 팁으로 보여 줍니다. 레이블이 있는 버튼은 레이블이 넘칠 때만 전체 문자열을 팁으로 보여 줍니다. tooltip={false}로 끌 수 있습니다. 레이블이 다 들어가는 버튼은 팁을 보여 주지 않습니다. 자동 팁은 절대 인터랙티브가 아닙니다.

변형은 기존 페인트 팩을 씁니다. 기본 type은 button입니다.

앞쪽 아이콘, 뒤쪽 아이콘, 아이콘만.

넘치는 레이블.

토글

pressed나 defaultPressed를 주면 버튼이 토글이 됩니다. aria-pressed를 설정하고 클릭하면 상태가 바뀝니다. onPressedChange는 새 상태를 받습니다. 눌린 버튼은 active 색과 안쪽 테두리를 유지합니다. 토글 여러 개를 묶을 때는 ToggleGroup을 쓰세요.

<Button.Root variant="secondary" pressed={muted} onPressedChange={setMuted}>
  Mute
</Button.Root>

Button.Group

형제 외형입니다. role="group"입니다. 자식은 Button.Root입니다. 붙은 가장자리는 1px 겹치고 바깥 모서리 반경을 공유합니다. 선택 상태는 없습니다.

언제 쓰나요

Button.Root

언제: 네이티브 버튼 하나로 하는 액션 하나. 변형은 primary / secondary / ghost이고, 기본값은 type="button"입니다. 아이콘만 있으면 aria-label이 필요하며, 이를 자동으로 팁으로 보여 줍니다.

쓰지 않을 때: 이동 → 네이티브 링크(Link는 제공하지 않음). 바로 적용되는 설정 → Switch. 폼의 선택 → Checkbox. 선택된 세그먼트 → ToggleGroup(Button.Group에는 선택 상태가 없음).

Button.Icon

언제: Button.Root 안의 장식용 아이콘. 위치 = DOM 순서. 항상 aria-hidden입니다.

쓰지 않을 때: 필드 안의 아이콘 → Field.Icon. Root에 aria-label 없이 아이콘이 유일한 이름일 때. Button.Root 바깥.

Button.Group

언제: 서로 관련된 Button.Root 액션을 붙여 놓은 가로 행(role="group"). aria-label로 이름을 붙이세요.

쓰지 않을 때: 토글 → ToggleGroup(여기에는 선택 상태가 없음). 세로 행이나 줄바꿈되는 행 → Stack. 관련 없는 액션 → Stack 안의 별도 버튼.

Props

Button.Root props
이름	타입	필수	기본값	설명
variant	`"primary" \| "secondary" \| "ghost"`	아니요	"primary"	시각 스타일. primary가 아니면 data-button-variant를 설정합니다.
type	`"button" \| "submit" \| "reset"`	아니요	"button"	네이티브 버튼 type.
disabled	`boolean`	아니요	false	컨트롤을 비활성화합니다.
aria-label	`string`	아니요	—	유일한 자식이 Button.Icon일 때 필수인 접근 가능한 이름. 아이콘 전용 버튼의 자동 팁 텍스트입니다.
tooltip	`boolean`	아니요	true	아이콘 전용 버튼은 접근 가능한 이름을 팁으로 보여 줍니다. 넘치는 레이블은 전체 문자열을 팁으로 보여 줍니다. false면 끕니다. 레이블이 다 들어가는 버튼에는 팁을 띄우지 않습니다.
pressed	`boolean`	아니요	—	제어되는 눌림 상태. 버튼을 aria-pressed가 있는 토글로 만듭니다.
defaultPressed	`boolean`	아니요	—	제어되지 않는 토글의 처음 눌림 상태. 버튼을 aria-pressed가 있는 토글로 만듭니다.
onPressedChange	`(pressed: boolean) => void`	아니요	—	토글을 클릭하면 새 상태로 호출됩니다. onClick이 먼저 실행되며, 거기서 preventDefault()를 부르면 바뀌지 않습니다.
children	`React.ReactNode`	아니요	—	레이블과 선택적 Button.Icon. 순서에 따라 앞쪽 또는 뒤쪽에 놓입니다.

Button.Icon props
이름	타입	필수	기본값	설명
children	`React.ReactNode`	아니요	—	아이콘 그래픽.

Button.Group props
이름	타입	필수	기본값	설명
aria-label	`string`	아니요	—	그룹의 접근 가능한 이름.
children	`React.ReactNode`	아니요	—	Button.Root 자식. 가로 방향만 지원합니다.