Toggle Group

포커스가 이어지는 묶음에서 하나 또는 여러 작업의 눌림 상태를 관리합니다.

용법

하나만 선택

한 번에 하나의 값만 활성화하고 키보드나 포인터로 이동해 선택합니다.

<!-- Toggle Group / Single -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['left', 'center', 'right']
const value = ref(['left'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value">
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

여러 항목 선택

기존 선택을 유지하면서 여러 값을 각각 선택하거나 해제합니다.

<!-- Toggle Group / Multiple -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['bold', 'italic', 'underline']
const value = ref(['bold', 'italic'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value" multiple>
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

외부 상태 관리

현재 값은 부모가 관리하고, 허용된 변경을 컴포넌트에 다시 전달합니다.

<!-- Toggle Group / Controlled -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['left', 'center', 'right']
const value = ref(['left'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value">
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

API

Vue 패키지: @sectile/vue/toggle-group

컴포넌트

ToggleGroupRoot
ToggleGroupItem

Props

`ToggleGroupRootProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
defaultValue: 타입readonly string[]기본값[]
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
deselectable: 타입boolean기본값true
현재 항목을 다시 선택해 값을 지울 수 있는지 여부입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
disabledItems: 타입readonly string[]기본값[]
포커스와 선택 대상에서 제외할 항목 값입니다.
form: 타입string기본값undefined
컨트롤을 연결할 네이티브 form 요소의 ID입니다.
items: 타입readonly string[]기본값필수
컴포넌트가 관리할 순서 있는 항목 값입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입readonly string[]기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
multiple: 타입boolean기본값false
여러 값을 동시에 선택할 수 있는지 여부입니다.
name: 타입string기본값undefined
네이티브 폼 제출에 사용할 이름입니다.
orientation: 타입'horizontal' | 'vertical'기본값'horizontal'
배치와 키보드 이동에 사용할 축입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.

`ToggleGroupItemProps`

as: 타입PrimitiveAs기본값'button'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
value: 타입string기본값필수
이 계약이 노출하는 현재 값입니다.

슬롯

`ToggleGroupRootSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입string | null
조작 대상으로 강조된 현재 값입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입readonly string[]
이 계약이 노출하는 현재 값입니다.

`ToggleGroupItemSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlighted: 타입boolean
조작 대상으로 강조된 항목인지 여부입니다.
pressed: 타입boolean
토글이 눌린 상태인지 여부입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입string
이 계약이 노출하는 현재 값입니다.

이벤트

`ToggleGroupRoot`

highlight: 페이로드string | null
강조된 항목이 바뀔 때 발생합니다.
update:modelValue: 페이로드readonly string[]
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.

기타 타입

`ToggleGroupValueChangeHandler`

type ToggleGroupValueChangeHandler = (value: readonly string[]) => void

`ToggleGroupHighlightHandler`

type ToggleGroupHighlightHandler = (value: string | null) => void

파트

공통 범위: [data-scope="toggle-group"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`root`	`[data-part="root"]`	컴포넌트 경계와 내부 파트를 묶습니다.	—
`item`	`[data-part="item"]`	선택하거나 실행할 수 있는 항목 하나입니다.	—

키보드 동작

키	동작
`Arrow keys`	보이는 방향에 따라 현재 선택 항목을 이동합니다.
`Home` / `End`	선택 가능한 첫 번째 또는 마지막 항목으로 이동합니다.
`Enter` / `Space`	현재 항목을 선택하거나 실행합니다.
`Printable text`	글자 검색을 지원하면 다음 일치 항목으로 이동합니다.

접근성

이름이 있는 묶음이 각 항목을 눌림 버튼으로 노출하고 하나의 이동 탭 위치를 사용합니다.

관련 WAI-ARIA 패턴에서 호스트 접근성 규칙을 확인할 수 있습니다.

Toggle Group ​

용법 ​

하나만 선택 ​

여러 항목 선택 ​

외부 상태 관리 ​

API ​

Props ​

ToggleGroupRootProps ​

ToggleGroupItemProps ​

슬롯 ​

ToggleGroupRootSlotProps ​

ToggleGroupItemSlotProps ​

이벤트 ​

ToggleGroupRoot ​

기타 타입 ​

ToggleGroupValueChangeHandler ​

ToggleGroupHighlightHandler ​

파트 ​

키보드 동작 ​

접근성 ​