CascadeSelect

Nested options, one column per level

For values that live in a hierarchy — country → city → area, category → subcategory — where a flat select would be hundreds of entries. Each level opens as its own column, so the user always sees where they are; the trigger shows the full path or just the leaf.

If the hierarchy is deep or ragged, BlessTreeSelect (a tree in a popover) is usually the better fit. If the options are flat but many, BlessCombobox.

The model is the leaf's value; select emits (option, path) with the whole trail when you need the parents too. Keyboard: ↑ / ↓ move in a column, → drills into children, ← backs out (both follow reading direction in RTL), Enter picks, Esc closes. Inside a BlessField the trigger takes the field's label; label is only for a select with no visible label.

Basic

Where

Japan›

Korea›

China

— · ↑↓ move, → drill, ← back, Enter pick

Leaf only

Japan›

Korea›

China

<script setup lang="ts">
import { ref } from "vue";
import { BlessCascadeSelect, BlessLabel, type BlessCascadeOption } from "blessing-ui";
const options: BlessCascadeOption<string>[] = [
  {
    value: "jp",
    label: "Japan",
    children: [
      {
        value: "tokyo",
        label: "Tokyo",
        children: [
          { value: "shinjuku", label: "Shinjuku" },
          { value: "akiba", label: "Akihabara" },
          { value: "ikebukuro", label: "Ikebukuro" },
        ],
      },
      {
        value: "osaka",
        label: "Osaka",
        children: [
          { value: "namba", label: "Namba" },
          { value: "umeda", label: "Umeda" },
        ],
      },
      { value: "kyoto", label: "Kyoto" },
    ],
  },
  { value: "kr", label: "Korea", children: [{ value: "seoul", label: "Seoul" }] },
  { value: "cn", label: "China", disabled: true },
];
const place = ref<string>();
const area = ref<string>("akiba");
</script>

<template>
  <div class="row" style="align-items: flex-start">
    <div class="col">
      <BlessLabel>Where</BlessLabel>
      <BlessCascadeSelect v-model="place" :options placeholder="Country › City › Area" />
      <small>{{ place ?? "—" }} · ↑↓ move, → drill, ← back, Enter pick</small>
    </div>
    <div class="col">
      <BlessLabel>Leaf only</BlessLabel>
      <BlessCascadeSelect v-model="area" :options :show-path="false" size="sm" />
    </div>
  </div>
</template>

Not inside <p>

The floating panel is a <div>. HTML closes a <p> when it meets a <div>, so a trigger placed inside a paragraph renders differently on the server and the client. Wrap with <span>/<div> instead.

Usage

import { BlessCascadeSelect } from "blessing-ui";

API

Props

Name	Type	Default	Description
options*	BlessCascadeOption<T>[]	—
placeholder	string	"Select…"
showPath	boolean	true	show the full path in the trigger (A › B › C) or only the leaf
separator	string	" › "
disabled	boolean	—
invalid	boolean	—
label	string	—	accessible name when there is no visible label; the shown value is announced either way
id	string	—
size	"md" | "sm" | "lg"	"md"
modelValue	T	—

Events

Name	Payload	Description
select	[option: BlessCascadeOption<T>, path: BlessCascadeOption<T>[]]
update:modelValue	[value: T | undefined]