Cascader
Select hierarchical options such as regions or categories.
Basic usage
children defines nested options. Expand a parent and select a leaf to commit the full path. disabled disables a whole branch.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
value: 'design',
label: 'Design',
children: [
{ value: 'interface', label: 'Interface design' },
{ value: 'brand', label: 'Brand design' },
],
},
{
value: 'engineering',
label: 'Engineering',
children: [
{ value: 'frontend', label: 'Frontend development' },
{ value: 'backend', label: 'Backend development' },
],
},
{ value: 'archived', label: 'Archived category', disabled: true },
];
export function CascaderBasic() {
return (
<Form layout="vertical">
<FormField label="Project category">
<Cascader options={options} placeholder="Choose a category" />
</FormField>
</Form>
);
}
Examples
Controlled path
value is an array of values from the root to the selected node. onChange also returns the full option path; clearing returns two empty arrays. Expanding a parent only changes the draft path. Returning to the first-level branch of a committed path restores its descendants.
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: 'Zhejiang',
children: [
{
value: 'hangzhou',
label: 'Hangzhou',
children: [
{ value: 'xihu', label: 'Xihu' },
{ value: 'yuhang', label: 'Yuhang' },
],
},
{ value: 'ningbo', label: 'Ningbo', children: [{ value: 'haishu', label: 'Haishu' }] },
],
},
{
value: 'jiangsu',
label: 'Jiangsu',
children: [
{ value: 'nanjing', label: 'Nanjing', children: [{ value: 'gulou', label: 'Gulou' }] },
{ value: 'suzhou', label: 'Suzhou', children: [{ value: 'gusu', label: 'Gusu' }] },
],
},
{ value: 'archived', label: 'Archived region', disabled: true },
];
export function CascaderControlled() {
const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
return (
<Form layout="vertical">
<FormField label="Delivery region">
<Cascader options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
Selected path: {JSON.stringify(value)}
</Text>
</Form>
);
}
Search
showSearch displays matching paths. Search covers supplied or already loaded options; it does not fetch remote results.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: 'Zhejiang',
children: [
{ value: 'hangzhou', label: 'Hangzhou' },
{ value: 'ningbo', label: 'Ningbo' },
],
},
{
value: 'jiangsu',
label: 'Jiangsu',
children: [
{ value: 'nanjing', label: 'Nanjing' },
{ value: 'suzhou', label: 'Suzhou' },
],
},
];
export function CascaderSearch() {
return (
<Form layout="vertical">
<FormField label="Region">
<Cascader options={regions} placeholder="Choose a region" showSearch />
</FormField>
</Form>
);
}
Multiple selection
With multiple, value is a string[][] containing complete paths. Selecting the same path again removes it, and the popup stays open after selection.
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: 'Zhejiang',
children: [
{ value: 'hangzhou', label: 'Hangzhou' },
{ value: 'ningbo', label: 'Ningbo' },
],
},
{
value: 'jiangsu',
label: 'Jiangsu',
children: [
{ value: 'nanjing', label: 'Nanjing' },
{ value: 'suzhou', label: 'Suzhou' },
],
},
];
export function CascaderMultiple() {
const [value, setValue] = useState<string[][]>([
['zhejiang', 'hangzhou'],
['jiangsu', 'nanjing'],
]);
return (
<Form layout="vertical">
<FormField label="Region">
<Cascader multiple options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
Selected paths: {value.length}
</Text>
</Form>
);
}
Single-line selections
tagWrap={false} keeps tags on one line and collapses overflow into +N. Use maxTagCount to limit the visible tags. Open the popup to review or change all selections.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
value: 'product',
label: 'Product team',
children: [
{ value: 'design', label: 'Product experience design' },
{ value: 'web', label: 'Frontend development' },
{ value: 'mobile', label: 'Mobile development' },
],
},
];
export function CascaderSingleLine() {
return (
<Form layout="vertical">
<FormField label="Product team">
<Cascader
multiple
tagWrap={false}
options={options}
defaultValue={[
['product', 'design'],
['product', 'web'],
['product', 'mobile'],
]}
/>
</FormField>
</Form>
);
}
Disabled and read-only
disabled prevents interaction. readOnly keeps the trigger focusable but prevents opening the popup, clearing or changing the value.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [
{
value: 'design',
label: 'Design',
children: [
{ value: 'interface', label: 'Interface design' },
{ value: 'brand', label: 'Brand design' },
],
},
{
value: 'engineering',
label: 'Engineering',
children: [
{ value: 'frontend', label: 'Frontend development' },
{ value: 'backend', label: 'Backend development' },
],
},
{ value: 'archived', label: 'Archived category', disabled: true },
];
const value = ['design', 'interface'];
export function CascaderStates() {
return (
<Form layout="vertical">
<FormField label="Disabled">
<Cascader options={options} value={value} disabled />
</FormField>
<FormField label="Read-only">
<Cascader options={options} value={value} readOnly />
</FormField>
</Form>
);
}
changeOnSelect allows committing intermediate paths. Selecting a node with children keeps the popup open so selection can continue down the hierarchy.
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: 'Zhejiang',
children: [
{ value: 'hangzhou', label: 'Hangzhou' },
{ value: 'ningbo', label: 'Ningbo' },
],
},
{
value: 'jiangsu',
label: 'Jiangsu',
children: [
{ value: 'nanjing', label: 'Nanjing' },
{ value: 'suzhou', label: 'Suzhou' },
],
},
];
export function CascaderIntermediate() {
const [value, setValue] = useState<string[]>([]);
return (
<Form layout="vertical">
<FormField label="Region">
<Cascader changeOnSelect options={regions} value={value} onChange={setValue} />
</FormField>
<Text role="status" tone="muted">
Selected path: {JSON.stringify(value)}
</Text>
</Form>
);
}
Lazy loading
Set isLeaf={false} on nodes without children; loadData returns their children on expansion. Keep options and loadData references stable, and use values unique across the entire tree.
Respect AbortSignal: changing the options, loader or cacheKey, or unmounting, cancels pending requests. Closing the popup does not. Use onLoadError for failure feedback; expand the node again to retry.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const options: CascaderOption[] = [{ value: 'remote', label: 'Remote categories', isLeaf: false }];
function waitForChildren(signal: AbortSignal) {
return new Promise<void>((resolve, reject) => {
if (signal.aborted) {
reject(new DOMException('Aborted', 'AbortError'));
return;
}
const onAbort = () => {
clearTimeout(timer);
reject(new DOMException('Aborted', 'AbortError'));
};
const timer = setTimeout(() => {
signal.removeEventListener('abort', onAbort);
resolve();
}, 400);
signal.addEventListener('abort', onAbort, { once: true });
});
}
async function loadData(option: CascaderOption, signal: AbortSignal): Promise<CascaderOption[]> {
await waitForChildren(signal);
return [{ value: `${option.value}-child`, label: 'Loaded item', isLeaf: true }];
}
export function CascaderLazy() {
return (
<Form layout="vertical">
<FormField label="Remote categories">
<Cascader options={options} loadData={loadData} placeholder="Expand a category" />
</FormField>
</Form>
);
}
Refreshing cached data
Update cacheKey when the data version changes to clear loaded children and cancel old requests. This example keeps the options and loader unchanged. Expand the category again after refreshing to load the new version.
import { Button, Cascader, type CascaderOption, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useCallback, useRef, useState } from 'react';
const options: CascaderOption[] = [{ value: 'remote', label: 'Remote categories', isLeaf: false }];
function waitForChildren(signal: AbortSignal) {
return new Promise<void>((resolve, reject) => {
if (signal.aborted) {
reject(new DOMException('Aborted', 'AbortError'));
return;
}
const onAbort = () => {
clearTimeout(timer);
reject(new DOMException('Aborted', 'AbortError'));
};
const timer = setTimeout(() => {
signal.removeEventListener('abort', onAbort);
resolve();
}, 400);
signal.addEventListener('abort', onAbort, { once: true });
});
}
export function CascaderCache() {
const [version, setVersion] = useState(1);
const [loadedVersion, setLoadedVersion] = useState<number | null>(null);
const versionRef = useRef(1);
const loadData = useCallback(async (option: CascaderOption, signal: AbortSignal) => {
const requestVersion = versionRef.current;
await waitForChildren(signal);
setLoadedVersion(requestVersion);
return [
{ value: `${option.value}-child`, label: `Loaded item v${requestVersion}`, isLeaf: true },
];
}, []);
return (
<Form layout="vertical">
<FormField label="Remote categories">
<Cascader
options={options}
loadData={loadData}
cacheKey={version}
placeholder="Expand a category"
/>
</FormField>
<Flex align="start">
<Button
onClick={() => {
versionRef.current += 1;
setVersion(versionRef.current);
setLoadedVersion(null);
}}
>
Refresh data
</Button>
</Flex>
<Text role="status" tone="muted">
Cache version: v{version}; Loaded version:{' '}
{loadedVersion === null ? 'Not loaded' : `v${loadedVersion}`}
</Text>
</Form>
);
}
popupWidth="auto" fits the content, and popupMaxWidth caps its width. Without a width override, the popup matches the trigger. See shared popup options for other popup settings.
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';
const regions: CascaderOption[] = [
{
value: 'zhejiang',
label: 'Zhejiang',
children: [
{ value: 'hangzhou', label: 'Hangzhou' },
{ value: 'ningbo', label: 'Ningbo' },
],
},
{
value: 'jiangsu',
label: 'Jiangsu',
children: [
{ value: 'nanjing', label: 'Nanjing' },
{ value: 'suzhou', label: 'Suzhou' },
],
},
];
export function CascaderPopup() {
return (
<Form layout="vertical">
<FormField label="Region">
<Cascader
options={regions}
placeholder="Choose a region"
popupWidth="auto"
popupMaxWidth={320}
/>
</FormField>
</Form>
);
}
Set name to submit the path as a JSON array string; empty values submit an empty string. Uncontrolled values support form reset; reset controlled application state yourself. See Form for labels and errors, and ConfigProvider for built-in translations.
API
Cascader API
Other native button and aria-* attributes reach the trigger. className / style apply to the outer container.
CascaderOption
The cascader option data structure, with child options organized through children.
CascaderFieldNames
Use mapCascaderOptions(records, fields) to convert records to CascaderOption[], then pass the result as options. CascaderFieldNames describes the mapping fields; it is not a Cascader prop.
import { mapCascaderOptions } from '@ifhover/leaf-ui';
const records = [{ id: 'design', name: 'Design', nodes: [{ id: 'interface', name: 'Interface design' }] }];
const options = mapCascaderOptions(records, {
value: 'id',
label: 'name',
children: 'nodes',
});