Cascade List

Display hierarchy levels side by side and select a leaf directly.

Usage

Location

Keep region, country, and city columns visible while choosing one destination.

DestinationAsia / South Korea / Seoul

<!-- Cascade List / Location -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

Disabled

Keep an unavailable branch visible while navigation continues through the remaining choices.

DestinationAsia / South Korea / Seoul

<!-- Cascade List / Disabled -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

Controlled

Let the parent own the selected destination while the hierarchy stays available for navigation.

DestinationEurope / France / Paris

<!-- Cascade List / Controlled -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

When to use it

Cascade List keeps each hierarchy level visible side by side. It fits filter panels, settings navigation, and condition builders where people need to compare the chosen path with the available next step. Use Cascade Select when the same hierarchy belongs in a compact trigger and popup.

Component	Layout	Selection flow
Cascade List	Keeps columns in the page layout	Choosing a branch reveals the next column; choosing a leaf commits the value
Cascade Select	Places the columns in a popup below a trigger	Uses the same branch navigation and leaf selection inside the popup

Both components share tree validation, active-item movement, disabled-item handling, and value selection rules. Their presentation differs to serve different layouts.

State ownership

Branch navigation updates highlightedValue and path; leaf selection commits modelValue. Start with internal state through defaultValue, or let the parent own the value with v-model. The columns remain in the page, so Escape keeps its surrounding page behavior.

API

Vue package: @sectile/vue/cascade-list

Components

CascadeListRoot
CascadeListValue
CascadeListColumn
CascadeListItem
CascadeListItemIndicator
CascadeListItemChevron

Props

`CascadeListRootProps`

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.
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.
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 CascadeListItemDefinition<string>[]DefaultRequired
Flat hierarchy used to build the tree.
policies: TypeCascadeListPolicies<string>Defaultundefined
Behavior policies that customize validation, movement, or selection.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
required: TypebooleanDefaultfalse
Whether the control must contain a valid value before submission.
textValue: Type(id: string) => stringDefaultundefined
Returns searchable or presentational text for an item value.

`CascadeListColumnProps`

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.

`CascadeListItemProps`

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.

`CascadeListPartProps`

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

`CascadeListRootSlotProps`

columns: Typereadonly (readonly string[])[]
Visible cascade hierarchy columns.
disabled: Typeboolean
Whether interaction is unavailable.
highlightedValue: Typestring | null
Value currently highlighted for interaction.
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.

`CascadeListColumnSlotProps`

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.

`CascadeListItemSlotProps`

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

`CascadeListRoot`

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

Other types

`CascadeListTextValueResolver`

type CascadeListTextValueResolver = NonNullable<CascadeListRootProps['textValue']>

`CascadeListValueChangeHandler`

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

`CascadeListHighlightHandler`

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

Parts

Shared scope: [data-scope="cascade-list"]. 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.	—
`value`	`[data-part="value"]`	Displays the current committed value.	—
`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 Up` / `Arrow Down`	Move between eligible items in the current column.
`Arrow Left` / `Arrow Right`	Move to the parent column or enter the highlighted branch.
`Home` / `End`	Move to the first or last eligible item in the current column.
`Enter` / `Space`	Open the highlighted branch or select the highlighted leaf.

Accessibility

Every visible hierarchy level is a labeled listbox; options expose selection, branch, expanded, and disabled state.

Cascade List ​

Usage ​

Location ​

Disabled ​

Controlled ​

When to use it ​

State ownership ​

API ​

Props ​

CascadeListRootProps ​

CascadeListColumnProps ​

CascadeListItemProps ​

CascadeListPartProps ​

Slots ​

CascadeListRootSlotProps ​

CascadeListColumnSlotProps ​

CascadeListItemSlotProps ​

Events ​

CascadeListRoot ​

Other types ​

CascadeListTextValueResolver ​

CascadeListValueChangeHandler ​

CascadeListHighlightHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​