Skip to content
Latestv1.0.63

Cascader ​

When a dataset has a clear hierarchical structure such as regions, departments, categories, or resource trees, use YhCascader for step-by-step selection.

Basic Usage ​

Use v-model with hierarchical options data for the standard single-select path mode.

Basic Usage

Initial Value ​

As long as the v-model value shape matches the current emit-path mode, the component can display the initial selection for both single and multiple selection.

Initial Value

Disabled ​

You can disable the entire component or mark specific options as disabled in the option tree.

Disabled

Multiple Selection ​

Enable multiple for multi-select and combine it with collapse-tags to reduce the displayed tag count.

Multiple Selection

Check Strictly ​

When check-strictly is enabled, parent and child nodes can be selected independently.

Check Strictly

Leaf Value Mode ​

By default, the component returns the full path. Set emit-path="false" to return only the selected leaf value.

Leaf Value Mode

Filterable ​

Enable filterable to search against the joined path label. You can also provide filter-method for custom matching logic.

Filterable

Custom Node Content ​

Use the default slot to customize how each node is rendered in the dropdown panel.

Custom Node Content

Custom Field Mapping ​

If your option data does not use value / label / children, map the field names with the props option.

Custom Field Mapping

Virtual List ​

Enable virtual to render large cascader datasets more efficiently.

Virtual List

Use in Nuxt ​

After installing @yh-ui/nuxt, you can use YhCascader directly in Nuxt 3/4. The input shell and selected values render in SSR, while the dropdown panel is displayed on the client through Teleport.

Use in Nuxt

API ​

Props ​

PropDescriptionTypeDefault
model-value / v-modelBound valuestring | number | (string | number)[] | (string | number)[][]undefined
optionsOption tree dataYhCascaderOption[]undefined
placeholderPlaceholder textstringundefined
disabledDisable the componentbooleanfalse
clearableShow clear button on hover when a value existsbooleanfalse
sizeComponent size'large' | 'default' | 'small'undefined
filterableEnable client-side filteringbooleanfalse
filter-methodCustom filter function(node: YhCascaderOption, keyword: string) => booleanundefined
separatorPath separator textstring' / '
show-all-levelsShow the full label path in single-select mode and tagsbooleantrue
collapse-tagsCollapse tags in multiple modebooleanfalse
collapse-tags-tooltipWhether to show a tooltip summary when tags are collapsedbooleanfalse
max-collapse-tagsMaximum visible tags before collapsingnumber1
multipleEnable multiple selectionbooleanfalse
check-strictlyAllow parent and child nodes to be selected independentlybooleanfalse
expand-triggerNode expansion trigger'click' | 'hover'undefined
emit-pathReturn full path instead of leaf valuebooleantrue
virtualEnable virtual rendering in the panelbooleanfalse
virtual-item-heightVirtual row heightnumber34
propsField mapping and cascader configPartial<CascaderConfig>undefined
popper-classExtra class name for the dropdown panelstringundefined
teleportedTeleport the dropdown to bodybooleantrue
tag-typeTag style in multiple mode'success' | 'info' | 'warning' | 'danger' | ''''
validate-eventTrigger form validation on value changes and blurbooleantrue
theme-overridesComponent theme override variablesComponentThemeVarsundefined

YhCascaderOption ​

FieldDescriptionType
valueNode valuestring | number
labelNode labelstring
childrenChild nodesYhCascaderOption[] | undefined
disabledDisable the current nodeboolean | undefined
leafMark the current node as a leafboolean | undefined

CascaderConfig ​

FieldDescriptionTypeDefault
expandTriggerNode expansion trigger'click' | 'hover''click'
multipleEnable multiple selectionbooleanfalse
checkStrictlyAllow independent parent and child selectionbooleanfalse
emitPathReturn the full path valuebooleantrue
lazyLazy load child optionsbooleanfalse
lazyLoadLazy load callback(node: YhCascaderOption, resolve: (children: YhCascaderOption[]) => void) => voidundefined
valueValue field namestring'value'
labelLabel field namestring'label'
childrenChildren field namestring'children'
disabledDisabled field namestring'disabled'
leafLeaf field namestring'leaf'

Events ​

EventDescriptionParameters
update:modelValueTriggered when the bound value changes(value: string | number | (string | number)[] | (string | number)[][] | undefined) => void
changeTriggered after the selection changes(value: string | number | (string | number)[] | (string | number)[][] | undefined) => void
focusTriggered when the input receives focus(event: FocusEvent) => void
blurTriggered when the input loses focus(event: FocusEvent) => void
clearTriggered when the clear icon is clicked() => void
expand-changeTriggered when the expanded path changes(value: (string | number)[]) => void
visible-changeTriggered when the dropdown opens or closes(visible: boolean) => void

Slots ​

SlotDescriptionParameters
defaultCustom node content{ node: YhCascaderOption, data: YhCascaderOption }
emptyContent shown when filtering returns no matches-

Expose ​

NameDescriptionType
focusFocus the input element() => void
blurBlur the input element() => void
getCheckedNodesGet the selected option nodes(leafOnly?: boolean) => YhCascaderOption[]
inputRefInput element refRef<HTMLInputElement | undefined>

Type Exports ​

NameDescription
YhCascaderPropsProps type for YhCascader
YhCascaderEmitsEmits type for YhCascader
YhCascaderExposeExpose type for YhCascader
YhCascaderOptionCascader option node type
YhCascaderInstancePublic instance type for YhCascader
YhCascaderPanelInstancePublic instance type for YhCascaderPanel

Theme Variables ​

YhCascader supports themeOverrides and consumes the following CSS variables in its component styles.

VariableDescriptionDefault
--yh-cascader-heightDefault input height32px
--yh-cascader-height-largeLarge size height40px
--yh-cascader-height-smallSmall size height24px
--yh-cascader-bg-colorInput background colorvar(--yh-fill-color-blank, #fff)
--yh-cascader-border-colorInput border colorvar(--yh-border-color, #dcdfe6)
--yh-cascader-border-color-hoverHover border colorvar(--yh-border-color-hover, #c0c4cc)
--yh-cascader-border-color-focusFocus border colorvar(--yh-color-primary, #409eff)
--yh-cascader-border-radiusBorder radiusvar(--yh-border-radius-base, 4px)
--yh-cascader-text-colorInput text colorvar(--yh-text-color-regular, #606266)
--yh-cascader-placeholder-colorPlaceholder colorvar(--yh-text-color-placeholder, #a8abb2)
--yh-cascader-disabled-bg-colorDisabled background colorvar(--yh-fill-color-light, #f5f7fa)
--yh-cascader-disabled-text-colorDisabled text colorvar(--yh-text-color-placeholder, #a8abb2)
--yh-cascader-node-heightPanel node height34px
--yh-cascader-node-bg-color-hoverNode hover backgroundvar(--yh-fill-color-light, #f5f7fa)
--yh-cascader-node-text-color-hoverNode hover text colorvar(--yh-text-color-regular, #606266)
--yh-cascader-node-bg-color-activeActive node backgroundvar(--yh-fill-color-light, #f5f7fa)
--yh-cascader-node-text-color-activeActive node text colorvar(--yh-color-primary, #409eff)
--yh-cascader-dropdown-bg-colorDropdown background colorvar(--yh-bg-color-overlay, #fff)
--yh-cascader-dropdown-border-colorDropdown border colorvar(--yh-border-color-light, #e4e7ed)
--yh-cascader-dropdown-shadowDropdown shadowvar(--yh-box-shadow-light, 0 2px 12px 0 rgba(0, 0, 0, 0.1))
--yh-cascader-menu-min-widthMinimum panel width180px
--yh-cascader-menu-max-heightMaximum panel height274px
--yh-cascader-menu-border-colorPanel separator colorvar(--yh-border-color-light, #e4e7ed)

Released under the MIT License.