Cascader

Basic selection

Selection commits on a leaf by default. Use change-on-select to commit at any level. The legacy clearable and check-strictly properties remain compatible.

Code copied

<template>
  <div class="demo-row">
    <s-cascader v-model="value" :options="options" />
    <s-cascader
      v-model="branchValue"
      :options="options"
      change-on-select
      placeholder="Select any level"
    />
  </div>
  <p class="value">Selected path: {{ value.join(' / ') || 'none' }}</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref(['guide', 'components'])
const branchValue = ref([])
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      { value: 'components', label: 'Components' },
      { value: 'theming', label: 'Theming' },
    ],
  },
  { value: 'api', label: 'API' },
]
</script>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}

.value {
  margin: 10px 2px 0;
  color: var(--s-text-color-secondary);
  font-size: 12px;
}
</style>

Search and field mapping

show-search searches complete paths and highlights matches. Its object form accepts filter, sort, and limit; field-names maps non-standard option data.

Code copied

<script setup lang="ts">
import { computed, ref } from 'vue'
import { useRoute } from 'vue-router'
import type { CascaderOption } from '@vuesax-alpha/components/cascader'

const route = useRoute()
const isZh = computed(() => route.path.startsWith('/zh/'))
const value = ref<Array<string | number>>([])
const customValue = ref<Array<string | number>>([])
const departments = [
  {
    id: 'engineering',
    name: 'Engineering',
    items: [
      { id: 'frontend', name: 'Frontend platform' },
      { id: 'quality', name: 'Quality assurance' },
    ],
  },
  {
    id: 'product',
    name: 'Product',
    items: [
      { id: 'design', name: 'Experience design' },
      { id: 'research', name: 'User research' },
    ],
  },
]

const matchLastLevel = (query: string, path: CascaderOption[]) =>
  String(path[path.length - 1]?.name ?? '')
    .toLowerCase()
    .includes(query.toLowerCase())
</script>

<template>
  <div class="demo-row">
    <div class="search-example">
      <span class="search-example__label">
        {{ isZh ? '完整路径匹配' : 'Full path search' }}
      </span>
      <s-cascader
        v-model="value"
        :options="departments"
        :field-names="{ value: 'id', label: 'name', children: 'items' }"
        show-search
        placeholder="Engineering"
      />
      <span class="search-example__hint">
        {{
          isZh
            ? '输入 Engineering：匹配两个子项'
            : 'Try Engineering: matches two children'
        }}
      </span>
    </div>

    <div class="search-example">
      <span class="search-example__label">
        {{ isZh ? '仅末级匹配' : 'Final level only' }}
      </span>
      <s-cascader
        v-model="customValue"
        :options="departments"
        :field-names="{ value: 'id', label: 'name', children: 'items' }"
        :show-search="{ filter: matchLastLevel }"
        placeholder="Engineering"
      />
      <span class="search-example__hint">
        {{
          isZh
            ? '输入 Engineering：不匹配任何末级项'
            : 'Try Engineering: no final-level match'
        }}
      </span>
    </div>
  </div>
</template>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  align-items: flex-start;
  gap: 18px;
}

.search-example {
  display: flex;
  width: 220px;
  flex-direction: column;
  gap: 6px;
}

.search-example__label {
  color: var(--sax-text-color);
  font-size: 0.75rem;
  font-weight: 600;
}

.search-example__hint {
  color: rgba(var(--sax-text), 0.58);
  font-size: 0.7rem;
  line-height: 1.4;
}
</style>

Multiple and display strategy

multiple enables associated parent-child selection. SHOW_PARENT compresses fully selected branches; SHOW_CHILD keeps leaf paths. Tags collapse into +N according to available width by default.

Code copied

<template>
  <div class="demo-row">
    <s-cascader
      v-model="parentValues"
      :options="options"
      multiple
      show-search
      placeholder="SHOW_PARENT"
    />
    <s-cascader
      v-model="childValues"
      :options="options"
      multiple
      show-search
      show-checked-strategy="SHOW_CHILD"
      :max-tag-count="2"
      placeholder="SHOW_CHILD"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const parentValues = ref<Array<Array<string | number>>>([])
const childValues = ref<Array<Array<string | number>>>([
  ['documents', 'guides'],
  ['documents', 'api'],
  ['assets', 'icons'],
])
const options = [
  {
    value: 'documents',
    label: 'Documents',
    children: [
      { value: 'guides', label: 'Guides' },
      { value: 'api', label: 'API reference' },
      { value: 'releases', label: 'Release notes' },
    ],
  },
  {
    value: 'assets',
    label: 'Assets',
    children: [
      { value: 'icons', label: 'Icons' },
      { value: 'tokens', label: 'Design tokens' },
    ],
  },
]
</script>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
</style>

Hover expansion and lazy loading

Use expand-trigger="hover" to expand on hover. For lazy nodes, set isLeaf to false and assign children in load-data; lazy loading and local path search are mutually exclusive.

Code copied

<template>
  <div class="demo-row">
    <s-cascader
      v-model="value"
      :options="options"
      :load-data="loadData"
      placeholder="Lazy load teams"
    />
    <s-cascader
      v-model="hoverValue"
      :options="staticOptions"
      expand-trigger="hover"
      placeholder="Hover to expand"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { CascaderOption } from '@vuesax-alpha/components/cascader'

const value = ref<Array<string | number>>([])
const hoverValue = ref<Array<string | number>>([])
const options = ref<CascaderOption[]>([
  { value: 'engineering', label: 'Engineering', isLeaf: false },
  { value: 'product', label: 'Product', isLeaf: false },
])
const staticOptions = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      { value: 'shanghai', label: 'Shanghai' },
      { value: 'singapore', label: 'Singapore' },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [{ value: 'london', label: 'London' }],
  },
]

const loadData = async (selectedOptions: CascaderOption[]) => {
  const target = selectedOptions[selectedOptions.length - 1]
  if (!target || target.children) return
  await new Promise((resolve) => setTimeout(resolve, 500))
  target.children = [
    { value: `${target.value}-platform`, label: 'Platform team' },
    { value: `${target.value}-experience`, label: 'Experience team' },
  ]
}
</script>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
</style>

Popup and content customization

popup-config matches Select and supports trigger width matching, size constraints, mount targets, offsets, and styles. Use header, footer, and option slots to customize content.

Code copied

<template>
  <div class="demo-row">
    <s-cascader
      v-model="value"
      :options="options"
      :popup-config="{
        full: true,
        maxHeight: 260,
        offset: 8,
        appendTo: 'body',
        className: 'cascader-popup-demo',
      }"
      block
    >
      <template #header>Select a documentation destination</template>
      <template #option="{ option }">
        <span class="custom-option">{{ option.label }}</span>
      </template>
      <template #footer>The popup follows the full trigger width.</template>
    </s-cascader>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref<Array<string | number>>([])
const options = [
  {
    value: 'docs',
    label: 'Documentation',
    children: [
      { value: 'start', label: 'Getting started' },
      { value: 'components', label: 'Components' },
    ],
  },
  { value: 'playground', label: 'Playground' },
]
</script>

<style scoped>
.demo-row {
  width: min(440px, 100%);
}

.custom-option {
  font-weight: 600;
}
</style>

API