> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/cascader.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# 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.


Project category

Choose a category

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/basic.tsx"
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>
  );
}
```

Expand code


## 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.


Delivery region

Zhejiang / Hangzhou / Xihu

Selected path: ["zhejiang","hangzhou","xihu"]

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/controlled.tsx"
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>
  );
}
```

Expand code

### Search

`showSearch` displays matching paths. Search covers supplied or already loaded options; it does not fetch remote results.


Region

Choose a region

search.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/search.tsx"
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>
  );
}
```

Expand code

### 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.


Region

Zhejiang / HangzhouJiangsu / Nanjing

Selected paths: 2

multiple.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/multiple.tsx"
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>
  );
}
```

Expand code

### 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.


Product team

Product team / Product experience designProduct team / Frontend developmentProduct team / Mobile development+3

single-line.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/single-line.tsx"
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>
  );
}
```

Expand code

### Disabled and read-only

`disabled` prevents interaction. `readOnly` keeps the trigger focusable but prevents opening the popup, clearing or changing the value.


Disabled

Design / Interface design

Read-only

Design / Interface design

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/states.tsx"
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>
  );
}
```

Expand code

### Intermediate levels

[](#)
`changeOnSelect` allows committing intermediate paths. Selecting a node with children keeps the popup open so selection can continue down the hierarchy.


Region

Please select

Selected path: []

intermediate.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/intermediate.tsx"
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>
  );
}
```

Expand code

### 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.


Remote categories

Expand a category

lazy.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/lazy.tsx"
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>
  );
}
```

Expand code

### 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.


Remote categories

Expand a category

Refresh data

Cache version: v1; Loaded version: Not loaded

cache.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/cache.tsx"
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>
  );
}
```

Expand code

### Popup width

`popupWidth="auto"` fits the content, and `popupMaxWidth` caps its width. Without a width override, the popup matches the trigger. See [shared popup options](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for other popup settings.


Region

Choose a region

popup.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/cascader/popup.tsx"
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>
  );
}
```

Expand code

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](https://ifhover.github.io/leaf-ui/en/components/form.md) for labels and errors, and [ConfigProvider](https://ifhover.github.io/leaf-ui/en/components/config-provider.md) for built-in translations.


## API

### Cascader API

Other native `button` and `aria-*` attributes reach the trigger. `className` / `style` apply to the outer container.

| Property            | Type                                                                                                                                                                                 | Default        | Description                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options`           | `readonly `[`CascaderOption`](#cascaderoption)`[]`                                                                                                                                   | Required       | Hierarchical options                                                                                                                                                   |
| `value`             | `readonly string[] \| readonly (readonly string[])[]`                                                                                                                                | —              | Controlled path; the internal uncontrolled value is used when omitted.                                                                                                 |
| `defaultValue`      | `readonly string[] \| readonly (readonly string[])[]`                                                                                                                                | `[]`           | Initial path for uncontrolled usage; native form reset is supported.                                                                                                   |
| `onChange`          | `((value: string[], selectedOptions: `[`CascaderOption`](#cascaderoption)`[]) => void) \| ((value: string[][], selectedOptions: `[`CascaderOption`](#cascaderoption)`[][]) => void)` | —              | Return a path and its options in single mode or path and option arrays in multiple mode; called on selection, removal or clearing, with two empty arrays when cleared. |
| `multiple`          | `false \| true`                                                                                                                                                                      | `false`        | Enable multiple selection; value and callback types change accordingly.                                                                                                |
| `placeholder`       | `string`                                                                                                                                                                             | Locale default | Placeholder when empty; localized by ConfigProvider                                                                                                                    |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                                               | `'md'`         | Control size                                                                                                                                                           |
| `status`            | `'error' \| 'warning'`                                                                                                                                                               | —              | Validation appearance                                                                                                                                                  |
| `disabled`          | `boolean`                                                                                                                                                                            | `false`        | Disable interaction.                                                                                                                                                   |
| `readOnly`          | `boolean`                                                                                                                                                                            | —              | Lock the value against typing, selection, clearing and removal.                                                                                                        |
| `allowClear`        | `boolean`                                                                                                                                                                            | `true`         | Clearing returns two empty arrays                                                                                                                                      |
| `showSearch`        | `boolean`                                                                                                                                                                            | —              | Enable search input.                                                                                                                                                   |
| `changeOnSelect`    | `boolean`                                                                                                                                                                            | —              | Allow selecting intermediate levels.                                                                                                                                   |
| `tagWrap`           | `boolean`                                                                                                                                                                            | `true`         | Allow selected tags to wrap; false keeps one line and collapses overflow.                                                                                              |
| `maxTagCount`       | `number \| 'responsive'`                                                                                                                                                             | —              | Maximum visible tags; responsive collapses them to the available width.                                                                                                |
| `displayRender`     | `(labels: ReactNode[], selectedOptions: `[`CascaderOption`](#cascaderoption)`[]) => ReactNode`                                                                                       | —              | Customize each selected path using its labels and options.                                                                                                             |
| `optionRender`      | `(option: `[`CascaderOption`](#cascaderoption)`) => ReactNode`                                                                                                                       | —              | Customize option content.                                                                                                                                              |
| `loadData`          | `(option: `[`CascaderOption`](#cascaderoption)`, signal: AbortSignal) => Promise<readonly `[`CascaderOption`](#cascaderoption)`[]>`                                                  | —              | Load children when expanding a node with isLeaf false and no supplied children; use signal to handle cancellation.                                                     |
| `onLoadError`       | `(error: unknown, option: `[`CascaderOption`](#cascaderoption)`) => void`                                                                                                            | —              | Called on loading failure, for retry feedback.                                                                                                                         |
| `cacheKey`          | `string \| number`                                                                                                                                                                   | —              | Changing the data version clears lazy caches and cancels stale requests.                                                                                               |
| `open`              | `boolean`                                                                                                                                                                            | —              | Controlled open state.                                                                                                                                                 |
| `defaultOpen`       | `boolean`                                                                                                                                                                            | `false`        | Initial open state for uncontrolled usage.                                                                                                                             |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                                            | —              | Panel open-state changes                                                                                                                                               |
| `popupWidth`        | `number \| string`                                                                                                                                                                   | `'trigger'`    | Popup width; trigger matches the trigger, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported.                       |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                                   | —              | Optional maximum popup width; no additional limit when unset, still bounded by the viewport.                                                                           |
| `name`              | `string`                                                                                                                                                                             | —              | Native FormData field name; nonempty values submit JSON paths and empty values submit an empty string.                                                                 |
| `form`              | `string`                                                                                                                                                                             | —              | ID of the associated native form.                                                                                                                                      |
| `required`          | `boolean`                                                                                                                                                                            | `false`        | Require a non-empty value; compound controls validate once.                                                                                                            |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`                 | —              | Placement relative to the trigger.                                                                                                                                     |
| `popupClassName`    | `string`                                                                                                                                                                             | —              | Custom class for the popup.                                                                                                                                            |
| `popupStyle`        | `CSSProperties`                                                                                                                                                                      | —              | Custom popup styles.                                                                                                                                                   |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                                      | —              | Wrap or extend popup content; retain the supplied content to preserve interaction.                                                                                     |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                                  | —              | Return a popup container, including a ShadowRoot.                                                                                                                      |
| `ref`               | `Ref<HTMLButtonElement>`                                                                                                                                                             | —              | DOM reference                                                                                                                                                          |

### CascaderOption

The cascader option data structure, with child options organized through `children`.

| Property      | Type                                               | Default  | Description                                                                                                   |
| ------------- | -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `value`       | `string`                                           | Required | Option value; unique among siblings for static data and across the tree for lazy nodes to distinguish caches. |
| `label`       | `ReactNode`                                        | Required | Visible option content.                                                                                       |
| `searchLabel` | `string`                                           | —        | Plain text used to search a rich label.                                                                       |
| `isLeaf`      | `boolean`                                          | —        | Identify a leaf node explicitly, including in lazy data.                                                      |
| `disabled`    | `boolean`                                          | `false`  | Disable this option and all descendants.                                                                      |
| `children`    | `readonly `[`CascaderOption`](#cascaderoption)`[]` | —        | Child options.                                                                                                |

### 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.

```ts
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',
});
```

| Property   | Type     | Default | Description                                            |
| ---------- | -------- | ------- | ------------------------------------------------------ |
| `value`    | `string` | —       | Business-object field containing the option value.     |
| `label`    | `string` | —       | Business-object field containing the visible label.    |
| `children` | `string` | —       | Business-object field containing the child-node array. |
| `disabled` | `string` | —       | Business-object field containing the disabled state.   |
| `isLeaf`   | `string` | —       | Business-object field containing the leaf marker.      |
