Cascade Select

계층을 열 단위로 좁혀 가며 마지막 값을 선택합니다.

용법

지역

국가에서 도시까지 위치를 단계별로 선택합니다.

<!-- Cascade Select / Location -->
<script setup lang="ts">
import { CascadeSelectColumn, CascadeSelectContent, CascadeSelectItem, CascadeSelectRoot, CascadeSelectTrigger, CascadeSelectValue } from '@sectile/vue/cascade-select'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeSelectRoot :nodes="nodes" default-value="seoul" v-slot="{ columns }">
    <CascadeSelectTrigger><CascadeSelectValue placeholder="Choose a destination" /></CascadeSelectTrigger>
    <CascadeSelectContent>
      <CascadeSelectColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeSelectItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeSelectItem>
      </CascadeSelectColumn>
    </CascadeSelectContent>
  </CascadeSelectRoot>
</template>

비활성 항목

비활성 상태에서 키보드와 포인터 입력을 차단합니다.

<!-- Cascade Select / Disabled -->
<script setup lang="ts">
import { CascadeSelectColumn, CascadeSelectContent, CascadeSelectItem, CascadeSelectRoot, CascadeSelectTrigger, CascadeSelectValue } from '@sectile/vue/cascade-select'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeSelectRoot :nodes="nodes" default-value="seoul" v-slot="{ columns }">
    <CascadeSelectTrigger><CascadeSelectValue placeholder="Choose a destination" /></CascadeSelectTrigger>
    <CascadeSelectContent>
      <CascadeSelectColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeSelectItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeSelectItem>
      </CascadeSelectColumn>
    </CascadeSelectContent>
  </CascadeSelectRoot>
</template>

외부 상태 관리

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

<!-- Cascade Select / Controlled -->
<script setup lang="ts">
import { CascadeSelectColumn, CascadeSelectContent, CascadeSelectItem, CascadeSelectRoot, CascadeSelectTrigger, CascadeSelectValue } from '@sectile/vue/cascade-select'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeSelectRoot :nodes="nodes" default-value="seoul" v-slot="{ columns }">
    <CascadeSelectTrigger><CascadeSelectValue placeholder="Choose a destination" /></CascadeSelectTrigger>
    <CascadeSelectContent>
      <CascadeSelectColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeSelectItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeSelectItem>
      </CascadeSelectColumn>
    </CascadeSelectContent>
  </CascadeSelectRoot>
</template>

Floating 위치

이 컴포넌트는 공통 위치 엔진을 사용합니다. 실시간 위치 예시에서 side, align, 간격, 충돌 경계, strategy, tracking을 바꾸며 계산 결과를 확인할 수 있습니다.

API

Vue 패키지: @sectile/vue/cascade-select

컴포넌트

CascadeSelectRoot
CascadeSelectTrigger
CascadeSelectValue
CascadeSelectContent
CascadeSelectColumn
CascadeSelectItem
CascadeSelectItemIndicator
CascadeSelectItemChevron

Props

`CascadeSelectRootProps`

align: 타입PositionAlign기본값'start'
기준 요소를 중심으로 팝업 내용을 정렬할 위치입니다.
as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
avoidCollisions: 타입boolean기본값true
팝업이 화면 안에 남도록 위치를 뒤집거나 이동할지 여부입니다.
collisionBoundary: 타입PositionBoundary기본값undefined
팝업을 화면 안에 유지할 때 사용할 경계입니다.
collisionPadding: 타입PositionPadding기본값8
팝업과 충돌 경계 사이에 둘 간격입니다.
defaultOpen: 타입boolean기본값false
컴포넌트가 관리하는 초기 열림 상태입니다.
defaultValue: 타입string | null기본값null
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
disabledItems: 타입readonly string[]기본값[]
포커스와 선택 대상에서 제외할 항목 값입니다.
form: 타입string기본값undefined
컨트롤을 연결할 네이티브 form 요소의 ID입니다.
hideWhenDetached: 타입boolean기본값false
기준 요소가 레이아웃에서 벗어나면 팝업을 숨길지 여부입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입string | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
name: 타입string기본값undefined
네이티브 폼 제출에 사용할 이름입니다.
nodes: 타입readonly CascadeSelectItemDefinition<string>[]기본값필수
계층을 구성할 평면 노드 목록입니다.
open: 타입boolean기본값undefined
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.
policies: 타입CascadeSelectPolicies<string>기본값undefined
검증, 이동, 선택 동작을 조정하는 정책입니다.
position: 타입boolean기본값true
실행 요소를 기준으로 팝업 위치를 계산할지 여부입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.
side: 타입PositionSide기본값'bottom'
기준 요소를 중심으로 팝업을 우선 배치할 방향입니다.
sideOffset: 타입number기본값8
팝업과 기준 요소 사이 거리입니다.
strategy: 타입PositionStrategy기본값'absolute'
기준 요소에 연결된 콘텐츠의 CSS 위치 전략입니다.
textValue: 타입(id: string) => string기본값undefined
항목 값을 검색 또는 표시 문자열로 바꾸는 함수입니다.
tracking: 타입PositionTracking기본값'events'
기준 요소에 연결된 콘텐츠가 열린 동안 위치를 갱신할 방식입니다.

`CascadeSelectColumnProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
depth: 타입number기본값필수
단계별 선택에서 이 열의 0부터 시작하는 깊이입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.

`CascadeSelectItemProps`

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

`CascadeSelectPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

`CascadeSelectRootSlotProps`

columns: 타입readonly (readonly string[])[]
현재 표시 중인 단계별 선택 열입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입string | null
조작 대상으로 강조된 현재 값입니다.
open: 타입boolean
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.
path: 타입readonly string[]
현재 선택 경로입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입string | null
이 계약이 노출하는 현재 값입니다.
valuePath: 타입readonly string[]
루트부터 마지막 항목까지의 현재 선택값입니다.

`CascadeSelectColumnSlotProps`

depth: 타입number
현재 계층 항목의 깊이입니다.
items: 타입readonly string[]
현재 계산된 항목 컬렉션입니다.
parentValue: 타입string | null
현재 단계별 선택 열을 소유한 값입니다.

`CascadeSelectItemSlotProps`

branch: 타입boolean
이 항목이 하위 항목을 소유하는지 여부입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
expanded: 타입boolean
하위 항목이 보이는지 여부입니다.
highlighted: 타입boolean
조작 대상으로 강조된 항목인지 여부입니다.
selected: 타입boolean
현재 선택된 항목인지 여부입니다.
value: 타입string
이 계약이 노출하는 현재 값입니다.

이벤트

`CascadeSelectRoot`

highlight: 페이로드string | null
강조된 항목이 바뀔 때 발생합니다.
update:modelValue: 페이로드string | null
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.
update:open: 페이로드boolean
컴포넌트가 새 열림 상태를 요청할 때 발생합니다.

기타 타입

`CascadeSelectTextValueResolver`

type CascadeSelectTextValueResolver = NonNullable<CascadeSelectRootProps['textValue']>

`CascadeSelectValueChangeHandler`

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

`CascadeSelectOpenChangeHandler`

type CascadeSelectOpenChangeHandler = (value: boolean) => void

`CascadeSelectHighlightHandler`

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

파트

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

파트	선택자	역할	추가 속성
`root`	`[data-part="root"]`	컴포넌트 경계와 내부 파트를 묶습니다.	—
`trigger`	`[data-part="trigger"]`	연결된 콘텐츠를 열고 닫거나 활성화합니다.	—
`value`	`[data-part="value"]`	현재 확정 값을 표시합니다.	—
`content`	`[data-part="content"]`	현재 상태에 맞는 컴포넌트 콘텐츠를 담습니다.	—
`column`	`[data-part="column"]`	계층형 선택 항목의 한 단계를 묶습니다.	—
`item`	`[data-part="item"]`	선택하거나 실행할 수 있는 항목 하나입니다.	—
`item-indicator`	`[data-part="item-indicator"]`	항목의 선택 상태를 표시합니다.	—
`item-chevron`	`[data-part="item-chevron"]`	항목에 하위 단계가 있음을 표시합니다.	—

키보드 동작

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

접근성

각 열은 이름이 있는 목록 상자이며 항목은 선택·하위 가지·비활성 상태를 노출합니다.

Cascade Select ​

용법 ​

지역 ​

비활성 항목 ​

외부 상태 관리 ​

Floating 위치 ​

API ​

Props ​

CascadeSelectRootProps ​

CascadeSelectColumnProps ​

CascadeSelectItemProps ​

CascadeSelectPartProps ​

슬롯 ​

CascadeSelectRootSlotProps ​

CascadeSelectColumnSlotProps ​

CascadeSelectItemSlotProps ​

이벤트 ​

CascadeSelectRoot ​

기타 타입 ​

CascadeSelectTextValueResolver ​

CascadeSelectValueChangeHandler ​

CascadeSelectOpenChangeHandler ​

CascadeSelectHighlightHandler ​

파트 ​

키보드 동작 ​

접근성 ​