# Cascader

- Page: https://jiguang132.com/resources/ant-design-mobile/docs/cascader
- Resource: Ant Design Mobile (https://jiguang132.com/resources/ant-design-mobile.md)
- All guides: https://jiguang132.com/resources/ant-design-mobile/docs.md

Selection of multi-level data.

## Install

```bash
npm install antd-mobile@5.43.0
```

antd-mobile is for mobile web, not React Native or Mini Programs. React 19 projects must register `createRoot` with `unstableSetRender` at the entry, or imperative APIs such as Toast and Dialog cannot render. Switch dark mode with `<html data-prefers-color-scheme="dark">`.

Examples come from the official Ant Design Mobile repository (MIT) at the commit published as npm 5.43.0. Presentation helpers such as `DemoBlock` are JGuang rewrites, not antd-mobile APIs.

Selection of multi-level data.

## When to Use

You need to select from a set of related data sets, such as provinces, municipalities, company levels, classifications of things, etc.

## Demos

## Cascader

### Props

```typescript | pure
type CascaderValue = string | null

type CascaderOption = {
  label: string
  value: string
  disabled?: boolean
  children?: CascaderOption[]
}

type CascaderValueExtend = {
  items: (CascaderOption | null)[]
  isLeaf: boolean
}
```

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| activeIcon | The icon displayed when selected | `ReactNode` | - |
| cancelText | Text of the cancel button | `ReactNode` | `'取消'` |
| children | Render function of the selected options | `(items: CascaderOption[], actions: CascaderActions) => ReactNode` | - |
| confirmText | Text of the ok button | `ReactNode` | `'确定'` |
| defaultValue | Default selected options | `CascaderValue[]` | `[]` |
| destroyOnClose | Destroy `dom` when not visible | `boolean` | `true` |
| forceRender | Render content forcely | `boolean` | `false` |
| onCancel | Triggered when cancelling | `() => void` | - |
| onClose | Triggered when confirming or cancelling | `() => void` | - |
| onConfirm | Triggered when confirming | `(value: CascaderValue[], extend: CascaderValueExtend) => void` | - |
| onSelect | Triggered when the selected options are changed | `(value: CascaderValue[], extend: CascaderValueExtend) => void` | - |
| onTabsChange | Callback when switching panel | `(index: number) => void` | - |
| options | Data of the cascade options | `CascaderOption[]` | - |
| placeholder | Hint text | `string` | `'请选择'` |
| title | Title | `ReactNode` | - |
| value | Selected options | `CascaderValue[]` | - |
| visible | Whether to show or hide the Picker | `boolean` | `false` |
| loading | Open the skeleton screen | `boolean` | `false` |
| optionRender | Custom render function for options | `(option: CascaderOption, info: { depth: number, active: boolean }) => ReactNode` | - |

Please pay attention to the `children` property of `CascaderOption`. If the `children` of an `option` is `[]`, then when the user selects this `option`, the Cascader component will automatically jump to the next level, even if There are currently no options at this level (because Cascader has no way to determine whether this empty array will become an array with content in subsequent updates). Therefore, please make sure that the `children` property of the last level option (aka "leaf node") does not exist or has the value `undefined`, so that the Cascader component can correctly recognize it.

### CascaderActions

| Name   | Description                           | Type         |
| ------ | ------------------------------------- | ------------ |
| close  | Close Cascader.                       | `() => void` |
| open   | Open Cascader.                        | `() => void` |
| toggle | Toggle the visible state of Cascader. | `() => void` |

### Ref

Same as CascaderActions.

### Loading <Experimental></Experimental>

You can pass `Cascader.optionSkeleton` as `CascaderOption[]` to the `options` property of Cascader or the `children` of `CascaderOption`. Cascader will recognize it and display the skeleton screen effect.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt