react-component/cascader

README

@rc-component/cascader

_{Part of the Ant Design ecosystem.}

🧭 React Cascader component for selecting values from hierarchical option trees, with search, multiple selection, async loading, and custom rendering.

English | 简体中文

Highlights

Area	Support
Data	Nested options, field name mapping, disabled nodes
Selection	Single, multiple, checkable, and change-on-select flows
Search	Controlled search, custom filter, custom sort, custom render
Loading	Async option loading with `loadData`
Rendering	Custom option label, dropdown content, icons, and expand trigger

Install

npm install @rc-component/cascader

Usage

import Cascader from '@rc-component/cascader';

const options = [
  {
    label: 'Zhejiang',
    value: 'zhejiang',
    children: [
      {
        label: 'Hangzhou',
        value: 'hangzhou',
        children: [{ label: 'Xihu', value: 'xihu' }],
      },
    ],
  },
  {
    label: 'Jiangsu',
    value: 'jiangsu',
    children: [{ label: 'Nanjing', value: 'nanjing' }],
  },
];

export default () => (
  <Cascader options={options}>
    <button type="button">Please select</button>
  </Cascader>
);

Examples

Run the local dumi site:

npm install
npm start

Then open http://localhost:8000.

API

Cascader

Property	Type	Default	Description
autoClearSearchValue	boolean	true	Deprecated. Use `showSearch.autoClearSearchValue` instead.
builtinPlacements	BuildInPlacements	-	Custom popup placements.
changeOnSelect	boolean	false	Trigger `onChange` when selecting each level.
checkable	boolean \| ReactNode	false	Enable multiple selection with checkbox UI.
checkStrictly	boolean	false	Only for `checkable`. Parent/children checked independently (no conduction, no half-checked); `showCheckedStrategy` ignored.
children	ReactElement	-	Trigger element.
classNames	Semantic class name map	-	Semantic class names for selector and popup elements.
defaultValue	string[] \| number[] \| Array<string[] \| number[]>	-	Initial selected value.
displayRender	`(label, selectedOptions) => ReactNode`	-	Render selected labels.
expandIcon	ReactNode	`>`	Custom expand icon.
expandTrigger	`click` \| `hover`	`click`	Trigger action for expanding the next option level.
fieldNames	`{ label?: string; value?: string; children?: string }`	`{ label: 'label', value: 'value', children: 'children' }`	Custom option field names.
loadData	`(selectedOptions) => void`	-	Load child options asynchronously.
loadingIcon	ReactNode	-	Custom loading icon.
onChange	`(value, selectedOptions) => void`	-	Called when selection changes.
onPopupVisibleChange	`(open: boolean) => void`	-	Called when popup visibility changes.
onSearch	`(value: string) => void`	-	Deprecated. Use `showSearch.onSearch` instead.
open	boolean	-	Controlled popup visibility.
optionRender	`(option) => ReactNode`	-	Custom option renderer.
options	Option[]	-	Hierarchical option data.
placement	Select placement	-	Popup placement.
popupClassName	string	-	Popup class name.
popupMenuColumnStyle	CSSProperties	-	Style for each popup menu column.
prefixCls	string	`rc-cascader`	Class name prefix.
searchValue	string	-	Deprecated. Use `showSearch.searchValue` instead.
showCheckedStrategy	`SHOW_PARENT` \| `SHOW_CHILD`	`SHOW_PARENT`	Strategy for rendering checked values in multiple mode.
showSearch	boolean \| SearchConfig	false	Enable and configure search.
styles	Semantic style map	-	Semantic styles for selector and popup elements.
value	string[] \| number[] \| Array<string[] \| number[]>	-	Controlled selected value.

Cascader also accepts public props from @rc-component/select BaseSelect, except private select-only props such as mode, labelInValue, showSearch, and tokenSeparators.

SearchConfig

Property	Type	Default	Description
autoClearSearchValue	boolean	true	Clear search text after selecting an item.
filter	`(inputValue, options, fieldNames) => boolean`	-	Return `true` to include an option path in search results.
limit	number \| false	50	Limit the number of filtered items.
matchInputWidth	boolean	true	Whether the search result width matches the input width.
onSearch	`(value: string) => void`	-	Called when search text changes.
render	`(inputValue, path, prefixCls, fieldNames) => ReactNode`	-	Render a filtered option path.
searchValue	string	-	Controlled search text.
sort	`(a, b, inputValue, fieldNames) => number`	-	Sort filtered option paths.

Option

Property	Type	Default	Description
children	Option[]	-	Child options.
disabled	boolean	false	Disable this option.
disableCheckbox	boolean	false	Disable this option's checkbox in multiple mode.
label	ReactNode	-	Display label.
value	string \| number \| null	-	Option value.

Development

npm install
npm start

The dumi site runs at http://localhost:8000 by default.

Common commands:

npm run lint
npm test
npm run tsc
npm run lint:tsc
npm run compile

Release

npm run prepublishOnly

The release flow is handled by @rc-component/np through the rc-np command after the package build.

License

@rc-component/cascader is released under the MIT license.

Clear configuration

allowClear accepts a boolean or an AllowClearConfig object from @rc-component/util:

interface AllowClearConfig {
  clearIcon?: React.ReactNode;
  disabled?: boolean;
  tabIndex?: number;
  label?: string;
}

All fields are optional. disabled: true behaves like allowClear={false}: the clear button and space reserved solely for it are removed; the input remains editable. Existing suffixes and other content are preserved. This changes the previous hidden-button spacing behavior where applicable.

tabIndex affects only the clear button; -1 removes it from Tab navigation while retaining mouse activation. label supplies its accessible name through aria-label. Defaults, clear values, callbacks, and component state restrictions are unchanged.