0
# Multiple Selection
1

2
Multiple selection capabilities with checkbox support, different display strategies, and hierarchical selection management. Enables users to select multiple items across different levels of the cascading hierarchy.
3

4
## Capabilities
5

6
### Multiple Selection Configuration
7

8
Enable and configure multiple selection behavior.
9

10
```typescript { .api }
11
interface MultipleSelectionProps<
12
  OptionType extends DefaultOptionType,
13
  ValueField extends keyof OptionType
14
> {
15
  /** Enable multiple selection mode */
16
  checkable: true | React.ReactNode;
17
  
18
  /** Strategy for displaying selected items */
19
  showCheckedStrategy?: ShowCheckedStrategy;
20
  
21
  /** Clear search value when selecting an item */
22
  autoClearSearchValue?: boolean;
23
  
24
  /** Multiple selection value type */
25
  value?: (string | number)[][];
26
  
27
  /** Multiple selection change handler */
28
  onChange?: (
29
    value: (string | number)[][],
30
    selectOptions: OptionType[][]
31
  ) => void;
32
}
33
```
34

35
### Show Checked Strategy
36

37
Control how selected items are displayed in multiple selection mode.
38

39
```typescript { .api }
40
type ShowCheckedStrategy = 'SHOW_PARENT' | 'SHOW_CHILD';
41

42
// Available as constants on Cascader component
43
Cascader.SHOW_PARENT: 'SHOW_PARENT';
44
Cascader.SHOW_CHILD: 'SHOW_CHILD';
45

46
// Access via destructuring
47
const { SHOW_PARENT, SHOW_CHILD } = Cascader;
48
```
49

50
### Multiple Selection Value Types
51

52
Type definitions for multiple selection values and callbacks.
53

54
```typescript { .api }
55
/** Multiple selection value format - array of value paths */
56
type MultipleValueType = (string | number)[][];
57

58
/** Multiple selection options format - array of option paths */
59
type MultipleOptionsType<OptionType> = OptionType[][];
60

61
/** Multiple selection change callback */
62
interface MultipleChangeCallback<OptionType> {
63
  (value: MultipleValueType, selectOptions: MultipleOptionsType<OptionType>): void;
64
}
65
```
66

67
### Option Checkbox Configuration
68

69
Configure checkbox behavior for individual options.
70

71
```typescript { .api }
72
interface CheckboxOptionType extends BaseOptionType {
73
  /** Disable checkbox for this specific option */
74
  disableCheckbox?: boolean;
75
  
76
  /** Disable the entire option (selection and checkbox) */
77
  disabled?: boolean;
78
}
79
```
80

81
## Usage Examples
82

83
### Basic Multiple Selection
84

85
```typescript
86
import React, { useState } from 'react';
87
import Cascader from 'rc-cascader';
88

89
const options = [
90
  {
91
    label: 'Technology',
92
    value: 'tech',
93
    children: [
94
      {
95
        label: 'Frontend',
96
        value: 'frontend',
97
        children: [
98
          { label: 'React', value: 'react' },
99
          { label: 'Vue', value: 'vue' },
100
          { label: 'Angular', value: 'angular' }
101
        ]
102
      },
103
      {
104
        label: 'Backend',
105
        value: 'backend',
106
        children: [
107
          { label: 'Node.js', value: 'nodejs' },
108
          { label: 'Python', value: 'python' }
109
        ]
110
      }
111
    ]
112
  }
113
];
114

115
const BasicMultipleExample = () => {
116
  const [value, setValue] = useState([]);
117

118
  const onChange = (value, selectedOptions) => {
119
    console.log('Selected values:', value);
120
    console.log('Selected options:', selectedOptions);
121
    setValue(value);
122
  };
123

124
  return (
125
    <Cascader
126
      checkable
127
      options={options}
128
      value={value}
129
      onChange={onChange}
130
      placeholder="Select multiple technologies"
131
      style={{ width: 300 }}
132
    />
133
  );
134
};
135
```
136

137
### Show Parent Strategy
138

139
Display only parent items when all children are selected.
140

141
```typescript
142
const ShowParentExample = () => {
143
  const [value, setValue] = useState([]);
144

145
  return (
146
    <Cascader
147
      checkable
148
      options={options}
149
      value={value}
150
      onChange={setValue}
151
      showCheckedStrategy={Cascader.SHOW_PARENT}
152
      placeholder="Show parent strategy"
153
    />
154
  );
155
};
156
```
157

158
### Show Child Strategy
159

160
Always display individual selected items, never parent groups.
161

162
```typescript
163
const ShowChildExample = () => {
164
  const [value, setValue] = useState([]);
165

166
  return (
167
    <Cascader
168
      checkable
169
      options={options}
170
      value={value}
171
      onChange={setValue}
172
      showCheckedStrategy={Cascader.SHOW_CHILD}
173
      placeholder="Show child strategy"
174
    />
175
  );
176
};
177
```
178

179
### Custom Checkbox Icon
180

181
```typescript
182
const CustomCheckboxExample = () => {
183
  const [value, setValue] = useState([]);
184

185
  return (
186
    <Cascader
187
      checkable={<span style={{ color: 'blue' }}>✓</span>}
188
      options={options}
189
      value={value}
190
      onChange={setValue}
191
      placeholder="Custom checkbox icon"
192
    />
193
  );
194
};
195
```
196

197
### Controlled Multiple Selection
198

199
```typescript
200
const ControlledMultipleExample = () => {
201
  const [value, setValue] = useState([
202
    ['tech', 'frontend', 'react'],
203
    ['tech', 'backend', 'nodejs']
204
  ]);
205

206
  const handleChange = (newValue, selectedOptions) => {
207
    console.log('Value changed from:', value);
208
    console.log('Value changed to:', newValue);
209
    setValue(newValue);
210
  };
211

212
  const handleClear = () => {
213
    setValue([]);
214
  };
215

216
  return (
217
    <div>
218
      <Cascader
219
        checkable
220
        options={options}
221
        value={value}
222
        onChange={handleChange}
223
        placeholder="Controlled selection"
224
      />
225
      <button onClick={handleClear} style={{ marginLeft: 8 }}>
226
        Clear All
227
      </button>
228
      <div style={{ marginTop: 8 }}>
229
        Selected: {JSON.stringify(value, null, 2)}
230
      </div>
231
    </div>
232
  );
233
};
234
```
235

236
### Disabled Checkboxes
237

238
```typescript
239
const disabledOptions = [
240
  {
241
    label: 'Skills',
242
    value: 'skills',
243
    children: [
244
      {
245
        label: 'Programming',
246
        value: 'programming',
247
        disableCheckbox: true,  // Can't select this level
248
        children: [
249
          { label: 'JavaScript', value: 'js' },
250
          { label: 'Python', value: 'python', disabled: true },  // Completely disabled
251
          { label: 'Java', value: 'java' }
252
        ]
253
      },
254
      {
255
        label: 'Design',
256
        value: 'design',
257
        children: [
258
          { label: 'UI Design', value: 'ui' },
259
          { label: 'UX Design', value: 'ux', disableCheckbox: true }
260
        ]
261
      }
262
    ]
263
  }
264
];
265

266
const DisabledCheckboxExample = () => {
267
  const [value, setValue] = useState([]);
268

269
  return (
270
    <Cascader
271
      checkable
272
      options={disabledOptions}
273
      value={value}
274
      onChange={setValue}
275
      placeholder="Some checkboxes disabled"
276
    />
277
  );
278
};
279
```
280

281
### Multiple Selection with Search
282

283
```typescript
284
const MultipleWithSearchExample = () => {
285
  const [value, setValue] = useState([]);
286

287
  return (
288
    <Cascader
289
      checkable
290
      options={options}
291
      value={value}
292
      onChange={setValue}
293
      showSearch
294
      autoClearSearchValue={false}  // Keep search text after selection
295
      placeholder="Multiple selection with search"
296
      style={{ width: 400 }}
297
    />
298
  );
299
};
300
```
301

302
### Dynamic Multiple Selection
303

304
```typescript
305
const DynamicMultipleExample = () => {
306
  const [options, setOptions] = useState([
307
    {
308
      label: 'Categories',
309
      value: 'categories',
310
      isLeaf: false
311
    }
312
  ]);
313
  const [value, setValue] = useState([]);
314

315
  const loadData = (selectedOptions) => {
316
    const targetOption = selectedOptions[selectedOptions.length - 1];
317
    targetOption.loading = true;
318

319
    setTimeout(() => {
320
      targetOption.loading = false;
321
      targetOption.children = [
322
        { label: 'Sub Category 1', value: 'sub1' },
323
        { label: 'Sub Category 2', value: 'sub2', disableCheckbox: true },
324
        { label: 'Sub Category 3', value: 'sub3' }
325
      ];
326
      setOptions([...options]);
327
    }, 1000);
328
  };
329

330
  return (
331
    <Cascader
332
      checkable
333
      options={options}
334
      value={value}
335
      onChange={setValue}
336
      loadData={loadData}
337
      changeOnSelect
338
      placeholder="Dynamic multiple selection"
339
    />
340
  );
341
};
342
```
343

344
### Custom Display for Multiple Selection
345

346
```typescript
347
const CustomDisplayMultipleExample = () => {
348
  const [value, setValue] = useState([]);
349

350
  const displayRender = (labels, selectedOptions) => {
351
    if (labels.length === 0) return 'Select items';
352
    
353
    if (labels.length <= 2) {
354
      return labels.map(labelArray => labelArray.join(' > ')).join(', ');
355
    }
356
    
357
    return `${labels.length} items selected`;
358
  };
359

360
  return (
361
    <Cascader
362
      checkable
363
      options={options}
364
      value={value}
365
      onChange={setValue}
366
      displayRender={displayRender}
367
      placeholder="Custom display rendering"
368
      style={{ width: 300 }}
369
    />
370
  );
371
};
372
```
373

374
### Form Integration with Multiple Selection
375

376
```typescript
377
const FormMultipleExample = () => {
378
  const [formData, setFormData] = useState({
379
    skills: [],
380
    interests: []
381
  });
382

383
  const handleSkillsChange = (value, selectedOptions) => {
384
    setFormData(prev => ({
385
      ...prev,
386
      skills: value
387
    }));
388
  };
389

390
  const handleSubmit = (e) => {
391
    e.preventDefault();
392
    console.log('Form data:', formData);
393
  };
394

395
  return (
396
    <form onSubmit={handleSubmit}>
397
      <div style={{ marginBottom: 16 }}>
398
        <label>Skills:</label>
399
        <Cascader
400
          checkable
401
          options={skillsOptions}
402
          value={formData.skills}
403
          onChange={handleSkillsChange}
404
          showCheckedStrategy={Cascader.SHOW_CHILD}
405
          placeholder="Select your skills"
406
          style={{ width: '100%', marginTop: 4 }}
407
        />
408
      </div>
409
      
410
      <div style={{ marginBottom: 16 }}>
411
        <label>Interests:</label>
412
        <Cascader
413
          checkable
414
          options={interestsOptions}
415
          value={formData.interests}
416
          onChange={(value) => 
417
            setFormData(prev => ({ ...prev, interests: value }))
418
          }
419
          placeholder="Select your interests"
420
          style={{ width: '100%', marginTop: 4 }}
421
        />
422
      </div>
423
      
424
      <button type="submit">Submit</button>
425
    </form>
426
  );
427
};
428
```
429

430
### Validation with Multiple Selection
431

432
```typescript
433
const ValidationMultipleExample = () => {
434
  const [value, setValue] = useState([]);
435
  const [error, setError] = useState('');
436

437
  const handleChange = (newValue, selectedOptions) => {
438
    setValue(newValue);
439
    
440
    // Validation logic
441
    if (newValue.length === 0) {
442
      setError('Please select at least one item');
443
    } else if (newValue.length > 5) {
444
      setError('Maximum 5 items can be selected');
445
    } else {
446
      setError('');
447
    }
448
  };
449

450
  return (
451
    <div>
452
      <Cascader
453
        checkable
454
        options={options}
455
        value={value}
456
        onChange={handleChange}
457
        placeholder="Select 1-5 items"
458
        style={{ 
459
          width: 300,
460
          borderColor: error ? 'red' : undefined
461
        }}
462
      />
463
      {error && (
464
        <div style={{ color: 'red', fontSize: '12px', marginTop: 4 }}>
465
          {error}
466
        </div>
467
      )}
468
      <div style={{ marginTop: 8, fontSize: '12px', color: '#666' }}>
469
        Selected: {value.length}/5
470
      </div>
471
    </div>
472
  );
473
};
474
```