Cascade Select

Choose a leaf value by moving through progressive hierarchy columns.

Usage

Location

Choose a location progressively from country to city.

<!-- 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>

Disabled

Remove the control from keyboard and pointer interaction.

<!-- 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>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

<!-- 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 positioning

This component uses the shared positioning engine. Use the live positioning example to change side, align, offsets, collision boundaries, strategy, and tracking while inspecting the resolved placement.

API

Vue package: @sectile/vue/cascade-select

Components

CascadeSelectRoot
CascadeSelectTrigger
CascadeSelectValue
CascadeSelectContent
CascadeSelectColumn
CascadeSelectItem
CascadeSelectItemIndicator
CascadeSelectItemChevron

Props

`CascadeSelectRootProps`

align: TypePositionAlignDefault'start'
Alignment of positioned content relative to its anchor.
as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
avoidCollisions: TypebooleanDefaulttrue
Whether positioned content may flip or shift to remain visible.
collisionBoundary: TypePositionBoundaryDefaultundefined
Boundary used to keep positioned content visible.
collisionPadding: TypePositionPaddingDefault8
Space kept between positioned content and its collision boundary.
defaultOpen: TypebooleanDefaultfalse
Initial uncontrolled open state.
defaultValue: Typestring | nullDefaultnull
Initial value used when the component owns its state.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
disabledItems: Typereadonly string[]Default[]
Item values excluded from focus and selection.
form: TypestringDefaultundefined
ID of the native form associated with the control.
hideWhenDetached: TypebooleanDefaultfalse
Whether positioned content hides when its anchor leaves the layout.
label: TypestringDefaultundefined
Accessible name announced for the control.
modelValue: Typestring | nullDefaultundefined
Current value when state is controlled by the parent.
name: TypestringDefaultundefined
Name used for native form submission.
nodes: Typereadonly CascadeSelectItemDefinition<string>[]DefaultRequired
Flat hierarchy used to build the tree.
open: TypebooleanDefaultundefined
Whether the associated popup or disclosure is open.
policies: TypeCascadeSelectPolicies<string>Defaultundefined
Behavior policies that customize validation, movement, or selection.
position: TypebooleanDefaulttrue
Whether the popup is positioned relative to its trigger.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
required: TypebooleanDefaultfalse
Whether the control must contain a valid value before submission.
side: TypePositionSideDefault'bottom'
Preferred side of the anchor for positioned content.
sideOffset: TypenumberDefault8
Distance between positioned content and its anchor.
strategy: TypePositionStrategyDefault'absolute'
CSS positioning strategy used for anchored content.
textValue: Type(id: string) => stringDefaultundefined
Returns searchable or presentational text for an item value.
tracking: TypePositionTrackingDefault'events'
Update strategy used while anchored content is open.

`CascadeSelectColumnProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
depth: TypenumberDefaultRequired
Zero-based depth of this column in a cascading selection.
label: TypestringDefaultundefined
Accessible name announced for the control.

`CascadeSelectItemProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
value: TypestringDefaultRequired
Current value exposed by this contract.

`CascadeSelectPartProps`

as: TypePrimitiveAsDefaultVaries by part
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.

Slots

`CascadeSelectRootSlotProps`

columns: Typereadonly (readonly string[])[]
Visible cascade hierarchy columns.
disabled: Typeboolean
Whether interaction is unavailable.
highlightedValue: Typestring | null
Value currently highlighted for interaction.
open: Typeboolean
Whether the associated popup or disclosure is open.
path: Typereadonly string[]
Current selected path.
readonly: Typeboolean
Whether the value can be inspected but not changed.
value: Typestring | null
Current value exposed by this contract.
valuePath: Typereadonly string[]
Current selected values from root to leaf.

`CascadeSelectColumnSlotProps`

depth: Typenumber
Depth of the current hierarchical item.
items: Typereadonly string[]
Current derived item collection.
parentValue: Typestring | null
Value that owns the current cascade column.

`CascadeSelectItemSlotProps`

branch: Typeboolean
Whether this item owns descendants.
disabled: Typeboolean
Whether interaction is unavailable.
expanded: Typeboolean
Whether descendants are visible.
highlighted: Typeboolean
Whether this item is highlighted for interaction.
selected: Typeboolean
Whether this item is selected.
value: Typestring
Current value exposed by this contract.

Events

`CascadeSelectRoot`

highlight: Payloadstring | null
Emitted when the highlighted item changes.
update:modelValue: Payloadstring | null
Emitted when the component requests a new controlled value.
update:open: Payloadboolean
Emitted when the component requests a new open state.

Other types

`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

Parts

Shared scope: [data-scope="cascade-select"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`trigger`	`[data-part="trigger"]`	Opens, closes, or activates the associated content.	—
`value`	`[data-part="value"]`	Displays the current committed value.	—
`content`	`[data-part="content"]`	Contains the component content shown for the active state.	—
`column`	`[data-part="column"]`	Groups one level of hierarchical choices.	—
`item`	`[data-part="item"]`	Represents one selectable or actionable item.	—
`item-indicator`	`[data-part="item-indicator"]`	Shows the item selection state.	—
`item-chevron`	`[data-part="item-chevron"]`	Shows that an item opens a deeper level.	—

Keyboard interaction

Key	Behavior
`Arrow keys`	Move the active option in the visible orientation.
`Home` / `End`	Move to the first or last eligible option.
`Enter` / `Space`	Select or activate the current option.
`Printable text`	Move to the next matching option when typeahead is available.

Accessibility

Each visible column is a labeled listbox; options expose selection, branch, and disabled state.

Cascade Select ​

Usage ​

Location ​

Disabled ​

Controlled ​

Floating positioning ​

API ​

Props ​

CascadeSelectRootProps ​

CascadeSelectColumnProps ​

CascadeSelectItemProps ​

CascadeSelectPartProps ​

Slots ​

CascadeSelectRootSlotProps ​

CascadeSelectColumnSlotProps ​

CascadeSelectItemSlotProps ​

Events ​

CascadeSelectRoot ​

Other types ​

CascadeSelectTextValueResolver ​

CascadeSelectValueChangeHandler ​

CascadeSelectOpenChangeHandler ​

CascadeSelectHighlightHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​