0
# Cascader Component
1
2
The main cascading select component providing dropdown interface with hierarchical option selection. Supports single and multiple selection modes, search functionality, dynamic loading, and extensive customization options.
3
4
## Capabilities
5
6
### Main Cascader Component
7
8
Creates a cascading select dropdown with trigger element integration.
9
10
```typescript { .api }
11
/**
12
* Main cascading select component with dropdown interface
13
* @param props - Cascader configuration props
14
* @returns JSX.Element
15
*/
16
function Cascader<
17
OptionType extends DefaultOptionType = DefaultOptionType,
18
ValueField extends keyof OptionType = keyof OptionType,
19
Multiple extends boolean | React.ReactNode = false
20
>(props: CascaderProps<OptionType, ValueField, Multiple>): JSX.Element;
21
```
22
23
### Core Data Props
24
25
Properties for managing options data and selection values.
26
27
```typescript { .api }
28
interface CoreDataProps<
29
OptionType extends DefaultOptionType,
30
ValueField extends keyof OptionType,
31
Multiple extends boolean | React.ReactNode
32
> {
33
/** Hierarchical options data array */
34
options?: OptionType[];
35
36
/** Controlled selected value */
37
value?: GetValueType<OptionType, ValueField, Multiple>;
38
39
/** Initial selected value for uncontrolled mode */
40
defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
41
42
/** Selection change callback */
43
onChange?: (
44
value: GetValueType<OptionType, ValueField, Multiple>,
45
selectOptions: GetOptionType<OptionType, Multiple>
46
) => void;
47
}
48
```
49
50
### Selection Behavior Props
51
52
Configure how selections are handled and displayed.
53
54
```typescript { .api }
55
interface SelectionBehaviorProps<Multiple extends boolean | React.ReactNode> {
56
/** Enable multiple selection mode */
57
checkable?: Multiple;
58
59
/** Trigger onChange on each level selection, not just leaf nodes */
60
changeOnSelect?: boolean;
61
62
/** Strategy for displaying selected items in multiple mode */
63
showCheckedStrategy?: ShowCheckedStrategy;
64
}
65
```
66
67
### Field Customization Props
68
69
Customize how option object fields are interpreted.
70
71
```typescript { .api }
72
interface FieldCustomizationProps<
73
OptionType extends DefaultOptionType,
74
ValueField extends keyof OptionType
75
> {
76
/** Custom field name mapping */
77
fieldNames?: FieldNames<OptionType, ValueField>;
78
}
79
80
interface FieldNames<
81
OptionType extends DefaultOptionType = DefaultOptionType,
82
ValueField extends keyof OptionType = keyof OptionType
83
> {
84
/** Field name for option display label (default: 'label') */
85
label?: keyof OptionType;
86
87
/** Field name for option value (default: 'value') */
88
value?: keyof OptionType | ValueField;
89
90
/** Field name for child options (default: 'children') */
91
children?: keyof OptionType;
92
}
93
```
94
95
### Dynamic Loading Props
96
97
Support for lazy loading of option data.
98
99
```typescript { .api }
100
interface DynamicLoadingProps<OptionType extends DefaultOptionType> {
101
/** Callback for loading child options dynamically */
102
loadData?: (selectOptions: OptionType[]) => void;
103
104
/** Custom loading icon */
105
loadingIcon?: React.ReactNode;
106
}
107
```
108
109
### Search Props
110
111
Search functionality configuration.
112
113
```typescript { .api }
114
interface SearchProps<
115
OptionType extends DefaultOptionType,
116
ValueField extends keyof OptionType
117
> {
118
/** Enable search with boolean or advanced configuration */
119
showSearch?: boolean | ShowSearchType<OptionType, ValueField>;
120
121
/** Controlled search input value */
122
searchValue?: string;
123
124
/** Search input change callback */
125
onSearch?: (value: string) => void;
126
127
/** Clear search value when selecting an item (multiple mode only) */
128
autoClearSearchValue?: boolean;
129
}
130
```
131
132
### Dropdown Behavior Props
133
134
Control dropdown visibility and positioning.
135
136
```typescript { .api }
137
interface DropdownBehaviorProps {
138
/** Control dropdown visibility */
139
open?: boolean;
140
141
/** Dropdown visibility change callback */
142
onOpenChange?: (open: boolean) => void;
143
144
/** Dropdown placement relative to trigger */
145
placement?: Placement;
146
147
/** Custom placement configurations */
148
builtinPlacements?: BuildInPlacements;
149
150
/** Custom container for dropdown portal */
151
getPopupContainer?: (trigger: Node) => Node;
152
}
153
```
154
155
### Styling Props
156
157
Appearance and styling customization.
158
159
```typescript { .api }
160
interface StylingProps {
161
/** CSS class prefix (default: 'rc-cascader') */
162
prefixCls?: string;
163
164
/** Additional CSS classes for root element */
165
className?: string;
166
167
/** Inline styles for root element */
168
style?: React.CSSProperties;
169
170
/** Additional CSS classes for dropdown */
171
dropdownClassName?: string;
172
173
/** Inline styles for dropdown menu columns */
174
dropdownMenuColumnStyle?: React.CSSProperties;
175
}
176
```
177
178
### Custom Rendering Props
179
180
Customize how options and selections are displayed.
181
182
```typescript { .api }
183
interface CustomRenderingProps<OptionType extends DefaultOptionType> {
184
/** Custom display rendering for selected values */
185
displayRender?: (
186
label: string[],
187
selectedOptions?: OptionType[]
188
) => React.ReactNode;
189
190
/** Custom rendering for individual options */
191
optionRender?: (option: OptionType) => React.ReactNode;
192
}
193
```
194
195
### Interaction Props
196
197
Control user interaction behavior.
198
199
```typescript { .api }
200
interface InteractionProps {
201
/** How to expand option menus: 'hover' or 'click' */
202
expandTrigger?: 'hover' | 'click';
203
204
/** Disable the entire component */
205
disabled?: boolean;
206
207
/** Placeholder text for trigger input */
208
placeholder?: string;
209
210
/** Content to show when no options found */
211
notFoundContent?: React.ReactNode;
212
213
/** Custom expand icon */
214
expandIcon?: React.ReactNode;
215
}
216
```
217
218
## Usage Examples
219
220
### Basic Single Selection
221
222
```typescript
223
import React, { useState } from 'react';
224
import Cascader from 'rc-cascader';
225
226
const options = [
227
{
228
label: 'Zhejiang',
229
value: 'zhejiang',
230
children: [
231
{
232
label: 'Hangzhou',
233
value: 'hangzhou',
234
children: [
235
{ label: 'West Lake', value: 'xihu' }
236
]
237
}
238
]
239
}
240
];
241
242
const BasicExample = () => {
243
const [value, setValue] = useState([]);
244
245
return (
246
<Cascader
247
options={options}
248
value={value}
249
onChange={(value, selectedOptions) => {
250
setValue(value);
251
console.log('Selected:', value, selectedOptions);
252
}}
253
placeholder="Please select"
254
/>
255
);
256
};
257
```
258
259
### With Search
260
261
```typescript
262
const SearchExample = () => {
263
return (
264
<Cascader
265
options={options}
266
showSearch={{
267
filter: (inputValue, path) =>
268
path.some(option =>
269
option.label.toLowerCase().includes(inputValue.toLowerCase())
270
),
271
limit: 50
272
}}
273
placeholder="Search locations"
274
/>
275
);
276
};
277
```
278
279
### Dynamic Loading
280
281
```typescript
282
const DynamicExample = () => {
283
const [options, setOptions] = useState(initialOptions);
284
285
const loadData = (selectedOptions) => {
286
const targetOption = selectedOptions[selectedOptions.length - 1];
287
targetOption.loading = true;
288
289
// Simulate API call
290
setTimeout(() => {
291
targetOption.loading = false;
292
targetOption.children = [
293
{ label: 'Dynamic Child 1', value: 'child1' },
294
{ label: 'Dynamic Child 2', value: 'child2' }
295
];
296
setOptions([...options]);
297
}, 1000);
298
};
299
300
return (
301
<Cascader
302
options={options}
303
loadData={loadData}
304
changeOnSelect
305
/>
306
);
307
};
308
```
309
310
### Custom Field Names
311
312
```typescript
313
const customOptions = [
314
{
315
title: 'Group 1',
316
id: 'group1',
317
items: [
318
{ title: 'Item 1', id: 'item1' }
319
]
320
}
321
];
322
323
const CustomFieldsExample = () => {
324
return (
325
<Cascader
326
options={customOptions}
327
fieldNames={{
328
label: 'title',
329
value: 'id',
330
children: 'items'
331
}}
332
/>
333
);
334
};
335
```