0
# RC Cascader
1

2
RC Cascader is a comprehensive cascading select component for React applications that enables hierarchical option selection through a dropdown interface. It offers extensive customization options including custom field mapping, dynamic data loading, search functionality, multiple selection modes, and flexible styling through CSS classes and inline styles.
3

4
## Package Information
5

6
- **Package Name**: rc-cascader
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rc-cascader`
10
- **CSS Import**: Import styles from `rc-cascader/assets/index.css`
11

12
## Core Imports
13

14
```typescript
15
import Cascader from "rc-cascader";
16
import { Panel } from "rc-cascader";
17

18
// Access constants via destructuring
19
const { SHOW_PARENT, SHOW_CHILD } = Cascader;
20

21
// Or use Panel from Cascader
22
const Panel = Cascader.Panel;
23
```
24

25
For CommonJS:
26

27
```javascript
28
const Cascader = require("rc-cascader");
29
const { Panel } = require("rc-cascader");
30

31
// Access constants
32
const { SHOW_PARENT, SHOW_CHILD } = Cascader;
33
```
34

35
## Basic Usage
36

37
```typescript
38
import React, { useState } from 'react';
39
import Cascader from 'rc-cascader';
40
import 'rc-cascader/assets/index.css';
41

42
const options = [
43
  {
44
    label: '福建',
45
    value: 'fj',
46
    children: [
47
      {
48
        label: '福州',
49
        value: 'fuzhou',
50
        children: [
51
          {
52
            label: '马尾',
53
            value: 'mawei',
54
          },
55
        ],
56
      },
57
      {
58
        label: '泉州',
59
        value: 'quanzhou',
60
      },
61
    ],
62
  },
63
  {
64
    label: '浙江',
65
    value: 'zj',
66
    children: [
67
      {
68
        label: '杭州',
69
        value: 'hangzhou',
70
        children: [
71
          {
72
            label: '余杭',
73
            value: 'yuhang',
74
          },
75
        ],
76
      },
77
    ],
78
  },
79
];
80

81
const App = () => {
82
  const [value, setValue] = useState([]);
83

84
  const onChange = (value, selectedOptions) => {
85
    console.log(value, selectedOptions);
86
    setValue(value);
87
  };
88

89
  return (
90
    <Cascader options={options} value={value} onChange={onChange}>
91
      <input placeholder="Please select" />
92
    </Cascader>
93
  );
94
};
95
```
96

97
## Architecture
98

99
RC Cascader is built around several key components:
100

101
- **Main Cascader Component**: Full-featured dropdown cascader with trigger element integration
102
- **Panel Component**: Standalone cascader panel for custom layouts without dropdown behavior
103
- **Option List System**: Multi-column option display with keyboard navigation and accessibility
104
- **Search Engine**: Advanced search with filtering, sorting, and custom rendering capabilities
105
- **Value Management**: Supports both single and multiple selection modes with various display strategies
106
- **Dynamic Loading**: Lazy loading of option data with loading states and error handling
107

108
## Capabilities
109

110
### Core Cascader Component
111

112
The main cascading select component providing dropdown interface with hierarchical option selection.
113

114
```typescript { .api }
115
function Cascader<
116
  OptionType extends DefaultOptionType = DefaultOptionType,
117
  ValueField extends keyof OptionType = keyof OptionType,
118
  Multiple extends boolean | React.ReactNode = false
119
>(props: CascaderProps<OptionType, ValueField, Multiple>): JSX.Element;
120

121
interface CascaderProps<
122
  OptionType extends DefaultOptionType = DefaultOptionType,
123
  ValueField extends keyof OptionType = keyof OptionType,
124
  Multiple extends boolean | React.ReactNode = false
125
> {
126
  // Core data and selection
127
  options?: OptionType[];
128
  value?: GetValueType<OptionType, ValueField, Multiple>;
129
  defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
130
  onChange?: (
131
    value: GetValueType<OptionType, ValueField, Multiple>,
132
    selectOptions: GetOptionType<OptionType, Multiple>
133
  ) => void;
134
  
135
  // Selection behavior
136
  checkable?: Multiple;
137
  changeOnSelect?: boolean;
138
  showCheckedStrategy?: ShowCheckedStrategy;
139
  
140
  // Field customization
141
  fieldNames?: FieldNames<OptionType, ValueField>;
142
  
143
  // Dynamic loading
144
  loadData?: (selectOptions: OptionType[]) => void;
145
  
146
  // Search functionality
147
  showSearch?: boolean | ShowSearchType<OptionType>;
148
  searchValue?: string;
149
  onSearch?: (value: string) => void;
150
  autoClearSearchValue?: boolean;
151
  
152
  // Dropdown behavior
153
  open?: boolean;
154
  onOpenChange?: (open: boolean) => void;
155
  placement?: Placement;
156
  builtinPlacements?: BuildInPlacements;
157
  getPopupContainer?: (trigger: Node) => Node;
158
  dropdownMatchSelectWidth?: boolean;
159
  
160
  // Styling and display
161
  prefixCls?: string;
162
  className?: string;
163
  style?: React.CSSProperties;
164
  dropdownClassName?: string;
165
  dropdownMenuColumnStyle?: React.CSSProperties;
166
  dropdownStyle?: React.CSSProperties;
167
  animation?: string;
168
  transitionName?: string;
169
  
170
  // Custom rendering
171
  displayRender?: (label: string[], selectedOptions?: OptionType[]) => React.ReactNode;
172
  optionRender?: (option: OptionType) => React.ReactNode;
173
  
174
  // Icons
175
  expandIcon?: React.ReactNode;
176
  loadingIcon?: React.ReactNode;
177
  
178
  // Interaction
179
  expandTrigger?: 'hover' | 'click';
180
  disabled?: boolean;
181
  placeholder?: string;
182
  notFoundContent?: React.ReactNode;
183
}
184
```
185

186
[Cascader Component](./cascader.md)
187

188
### Panel Component
189

190
Standalone cascader panel for custom layouts without dropdown behavior.
191

192
```typescript { .api }
193
function Panel<
194
  OptionType extends DefaultOptionType = DefaultOptionType,
195
  ValueField extends keyof OptionType = keyof OptionType,
196
  Multiple extends boolean | React.ReactNode = false
197
>(props: PanelProps<OptionType, ValueField, Multiple>): JSX.Element;
198

199
interface PanelProps<
200
  OptionType extends DefaultOptionType = DefaultOptionType,
201
  ValueField extends keyof OptionType = keyof OptionType,
202
  Multiple extends boolean | React.ReactNode = false
203
> {
204
  value?: GetValueType<OptionType, ValueField, Multiple>;
205
  defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
206
  changeOnSelect?: boolean;
207
  onChange?: (
208
    value: GetValueType<OptionType, ValueField, Multiple>,
209
    selectOptions: GetOptionType<OptionType, Multiple>
210
  ) => void;
211
  options?: OptionType[];
212
  prefixCls?: string;
213
  checkable?: Multiple;
214
  fieldNames?: FieldNames<OptionType, ValueField>;
215
  showCheckedStrategy?: ShowCheckedStrategy;
216
  loadData?: (selectOptions: OptionType[]) => void;
217
  expandTrigger?: 'hover' | 'click';
218
  expandIcon?: React.ReactNode;
219
  loadingIcon?: React.ReactNode;
220
  className?: string;
221
  style?: React.CSSProperties;
222
  direction?: 'ltr' | 'rtl';
223
  notFoundContent?: React.ReactNode;
224
  disabled?: boolean;
225
}
226
```
227

228
[Panel Component](./panel.md)
229

230
### Search Functionality
231

232
Advanced search capabilities with filtering, custom rendering, and result limiting.
233

234
```typescript { .api }
235
interface ShowSearchType<
236
  OptionType extends DefaultOptionType = DefaultOptionType,
237
  ValueField extends keyof OptionType = keyof OptionType
238
> {
239
  filter?: (
240
    inputValue: string,
241
    options: OptionType[],
242
    fieldNames: FieldNames<OptionType, ValueField>
243
  ) => boolean;
244
  render?: (
245
    inputValue: string,
246
    path: OptionType[],
247
    prefixCls: string,
248
    fieldNames: FieldNames<OptionType, ValueField>
249
  ) => React.ReactNode;
250
  sort?: (
251
    a: OptionType[],
252
    b: OptionType[],
253
    inputValue: string,
254
    fieldNames: FieldNames<OptionType, ValueField>
255
  ) => number;
256
  matchInputWidth?: boolean;
257
  limit?: number | false;
258
}
259
```
260

261
[Search Configuration](./search.md)
262

263
### Multiple Selection
264

265
Multiple selection capabilities with different display strategies and checkbox support.
266

267
```typescript { .api }
268
// Enable multiple selection
269
checkable: true
270

271
// Control display strategy
272
showCheckedStrategy: 'SHOW_PARENT' | 'SHOW_CHILD'
273

274
// Multiple selection value type
275
type MultipleValueType = (string | number)[][];
276

277
// Multiple selection change handler
278
onChange: (value: MultipleValueType, selectOptions: OptionType[][]) => void;
279
```
280

281
[Multiple Selection](./multiple-selection.md)
282

283
## Core Types
284

285
```typescript { .api }
286
interface BaseOptionType {
287
  disabled?: boolean;
288
  disableCheckbox?: boolean;
289
  label?: React.ReactNode;
290
  value?: string | number | null;
291
  children?: DefaultOptionType[];
292
}
293

294
type DefaultOptionType = BaseOptionType & Record<string, any>;
295

296
interface FieldNames<
297
  OptionType extends DefaultOptionType = DefaultOptionType,
298
  ValueField extends keyof OptionType = keyof OptionType
299
> {
300
  label?: keyof OptionType;
301
  value?: keyof OptionType | ValueField;
302
  children?: keyof OptionType;
303
}
304

305
type ShowCheckedStrategy = 'SHOW_PARENT' | 'SHOW_CHILD';
306

307
// Constants available on Cascader component
308
Cascader.SHOW_PARENT: 'SHOW_PARENT';
309
Cascader.SHOW_CHILD: 'SHOW_CHILD';
310

311
interface CascaderRef {
312
  focus: () => void;
313
  blur: () => void;
314
}
315

316
type GetValueType<
317
  OptionType extends DefaultOptionType = DefaultOptionType,
318
  ValueField extends keyof OptionType = keyof OptionType,
319
  Multiple extends boolean | React.ReactNode = false
320
> = false extends Multiple
321
  ? (string | number)[]
322
  : (string | number)[][];
323

324
type GetOptionType<
325
  OptionType extends DefaultOptionType = DefaultOptionType,
326
  Multiple extends boolean | React.ReactNode = false
327
> = false extends Multiple 
328
  ? OptionType[] 
329
  : OptionType[][];
330

331
// Dropdown positioning types
332
type Placement = 
333
  | 'bottomLeft' 
334
  | 'bottomRight' 
335
  | 'topLeft' 
336
  | 'topRight' 
337
  | 'bottom' 
338
  | 'top';
339

340
interface BuildInPlacements {
341
  [key: string]: {
342
    points: string[];
343
    offset?: number[];
344
    targetOffset?: number[];
345
    overflow?: {
346
      adjustX?: boolean;
347
      adjustY?: boolean;
348
    };
349
  };
350
}
351
```