0
# Search Configuration
1
2
Advanced search capabilities with filtering, custom rendering, sorting, and result limiting. Enables users to quickly find options in large hierarchical datasets through text input.
3
4
## Capabilities
5
6
### Search Configuration Interface
7
8
Configure search behavior with filtering, rendering, and sorting options.
9
10
```typescript { .api }
11
interface ShowSearchType<
12
OptionType extends DefaultOptionType = DefaultOptionType,
13
ValueField extends keyof OptionType = keyof OptionType
14
> {
15
/** Custom filter function for search matching */
16
filter?: (
17
inputValue: string,
18
options: OptionType[],
19
fieldNames: FieldNames<OptionType, ValueField>
20
) => boolean;
21
22
/** Custom rendering for search result items */
23
render?: (
24
inputValue: string,
25
path: OptionType[],
26
prefixCls: string,
27
fieldNames: FieldNames<OptionType, ValueField>
28
) => React.ReactNode;
29
30
/** Custom sorting function for search results */
31
sort?: (
32
a: OptionType[],
33
b: OptionType[],
34
inputValue: string,
35
fieldNames: FieldNames<OptionType, ValueField>
36
) => number;
37
38
/** Whether search dropdown should match input width */
39
matchInputWidth?: boolean;
40
41
/** Maximum number of search results to display (false for unlimited) */
42
limit?: number | false;
43
}
44
```
45
46
### Basic Search Props
47
48
Simple search enablement and control.
49
50
```typescript { .api }
51
interface BasicSearchProps<
52
OptionType extends DefaultOptionType,
53
ValueField extends keyof OptionType
54
> {
55
/** Enable search with boolean or advanced configuration */
56
showSearch?: boolean | ShowSearchType<OptionType, ValueField>;
57
58
/** Controlled search input value */
59
searchValue?: string;
60
61
/** Search input change callback */
62
onSearch?: (value: string) => void;
63
64
/** Clear search value when selecting an item (multiple mode only) */
65
autoClearSearchValue?: boolean;
66
}
67
```
68
69
### Search Filter Function
70
71
Custom filtering logic for search matching.
72
73
```typescript { .api }
74
/**
75
* Custom filter function for search matching
76
* @param inputValue - Current search input text
77
* @param options - Array of options in the current path
78
* @param fieldNames - Field name mapping configuration
79
* @returns true if the path should be included in search results
80
*/
81
type SearchFilter<
82
OptionType extends DefaultOptionType,
83
ValueField extends keyof OptionType
84
> = (
85
inputValue: string,
86
options: OptionType[],
87
fieldNames: FieldNames<OptionType, ValueField>
88
) => boolean;
89
```
90
91
### Search Render Function
92
93
Custom rendering for search result items.
94
95
```typescript { .api }
96
/**
97
* Custom rendering for search result items
98
* @param inputValue - Current search input text
99
* @param path - Array of options representing the path to this result
100
* @param prefixCls - CSS class prefix for styling
101
* @param fieldNames - Field name mapping configuration
102
* @returns Custom rendered content for the search result
103
*/
104
type SearchRender<
105
OptionType extends DefaultOptionType,
106
ValueField extends keyof OptionType
107
> = (
108
inputValue: string,
109
path: OptionType[],
110
prefixCls: string,
111
fieldNames: FieldNames<OptionType, ValueField>
112
) => React.ReactNode;
113
```
114
115
### Search Sort Function
116
117
Custom sorting logic for search results.
118
119
```typescript { .api }
120
/**
121
* Custom sorting function for search results
122
* @param a - First option path for comparison
123
* @param b - Second option path for comparison
124
* @param inputValue - Current search input text
125
* @param fieldNames - Field name mapping configuration
126
* @returns Negative, zero, or positive number for sorting order
127
*/
128
type SearchSort<
129
OptionType extends DefaultOptionType,
130
ValueField extends keyof OptionType
131
> = (
132
a: OptionType[],
133
b: OptionType[],
134
inputValue: string,
135
fieldNames: FieldNames<OptionType, ValueField>
136
) => number;
137
```
138
139
## Usage Examples
140
141
### Basic Search
142
143
```typescript
144
import React from 'react';
145
import Cascader from 'rc-cascader';
146
147
const options = [
148
{
149
label: 'Zhejiang',
150
value: 'zhejiang',
151
children: [
152
{
153
label: 'Hangzhou',
154
value: 'hangzhou',
155
children: [
156
{ label: 'West Lake', value: 'xihu' },
157
{ label: 'Xiaoshan', value: 'xiaoshan' }
158
]
159
},
160
{ label: 'Ningbo', value: 'ningbo' }
161
]
162
},
163
{
164
label: 'Jiangsu',
165
value: 'jiangsu',
166
children: [
167
{ label: 'Nanjing', value: 'nanjing' },
168
{ label: 'Suzhou', value: 'suzhou' }
169
]
170
}
171
];
172
173
const BasicSearchExample = () => {
174
return (
175
<Cascader
176
options={options}
177
showSearch
178
placeholder="Search locations"
179
style={{ width: 300 }}
180
/>
181
);
182
};
183
```
184
185
### Custom Filter Search
186
187
```typescript
188
const CustomFilterExample = () => {
189
return (
190
<Cascader
191
options={options}
192
showSearch={{
193
filter: (inputValue, path, fieldNames) => {
194
// Search in any level of the path
195
return path.some(option =>
196
option[fieldNames.label]
197
.toLowerCase()
198
.includes(inputValue.toLowerCase())
199
);
200
}
201
}}
202
placeholder="Custom filter search"
203
/>
204
);
205
};
206
```
207
208
### Search with Custom Rendering
209
210
```typescript
211
const CustomRenderExample = () => {
212
return (
213
<Cascader
214
options={options}
215
showSearch={{
216
render: (inputValue, path, prefixCls, fieldNames) => {
217
const labels = path.map(option => option[fieldNames.label]);
218
const fullPath = labels.join(' / ');
219
220
// Highlight matched text
221
const regex = new RegExp(`(${inputValue})`, 'gi');
222
const highlightedPath = fullPath.replace(
223
regex,
224
'<mark>$1</mark>'
225
);
226
227
return (
228
<div
229
className={`${prefixCls}-menu-item-search-result`}
230
dangerouslySetInnerHTML={{ __html: highlightedPath }}
231
/>
232
);
233
}
234
}}
235
placeholder="Custom render search"
236
/>
237
);
238
};
239
```
240
241
### Search with Sorting and Limiting
242
243
```typescript
244
const SortedLimitedSearchExample = () => {
245
return (
246
<Cascader
247
options={options}
248
showSearch={{
249
filter: (inputValue, path) =>
250
path.some(option =>
251
option.label.toLowerCase().includes(inputValue.toLowerCase())
252
),
253
sort: (a, b, inputValue) => {
254
// Sort by relevance - exact matches first
255
const aLabel = a[a.length - 1].label.toLowerCase();
256
const bLabel = b[b.length - 1].label.toLowerCase();
257
const input = inputValue.toLowerCase();
258
259
const aExact = aLabel.startsWith(input) ? 0 : 1;
260
const bExact = bLabel.startsWith(input) ? 0 : 1;
261
262
if (aExact !== bExact) return aExact - bExact;
263
264
// Then sort alphabetically
265
return aLabel.localeCompare(bLabel);
266
},
267
limit: 50,
268
matchInputWidth: true
269
}}
270
placeholder="Sorted and limited search"
271
/>
272
);
273
};
274
```
275
276
### Controlled Search
277
278
```typescript
279
const ControlledSearchExample = () => {
280
const [searchValue, setSearchValue] = useState('');
281
const [value, setValue] = useState([]);
282
283
return (
284
<div>
285
<Cascader
286
options={options}
287
showSearch={{
288
filter: (inputValue, path) =>
289
path.some(option =>
290
option.label.toLowerCase().includes(inputValue.toLowerCase())
291
)
292
}}
293
searchValue={searchValue}
294
onSearch={setSearchValue}
295
value={value}
296
onChange={setValue}
297
placeholder="Controlled search"
298
/>
299
<p>Current search: {searchValue}</p>
300
<p>Selected value: {JSON.stringify(value)}</p>
301
</div>
302
);
303
};
304
```
305
306
### Search with Auto Clear
307
308
```typescript
309
const AutoClearSearchExample = () => {
310
return (
311
<Cascader
312
checkable
313
options={options}
314
showSearch
315
autoClearSearchValue={true}
316
placeholder="Search clears on selection"
317
style={{ width: 300 }}
318
/>
319
);
320
};
321
```
322
323
### Advanced Multi-Field Search
324
325
```typescript
326
const products = [
327
{
328
name: 'Electronics',
329
id: 'electronics',
330
description: 'Electronic devices and gadgets',
331
children: [
332
{
333
name: 'Laptops',
334
id: 'laptops',
335
description: 'Portable computers',
336
children: [
337
{ name: 'Gaming Laptop', id: 'gaming-laptop', description: 'High performance gaming' },
338
{ name: 'Business Laptop', id: 'business-laptop', description: 'Professional computing' }
339
]
340
}
341
]
342
}
343
];
344
345
const MultiFieldSearchExample = () => {
346
return (
347
<Cascader
348
options={products}
349
fieldNames={{
350
label: 'name',
351
value: 'id',
352
children: 'children'
353
}}
354
showSearch={{
355
filter: (inputValue, path) => {
356
const input = inputValue.toLowerCase();
357
return path.some(option =>
358
option.name.toLowerCase().includes(input) ||
359
option.description?.toLowerCase().includes(input)
360
);
361
},
362
render: (inputValue, path) => {
363
const item = path[path.length - 1];
364
const pathNames = path.map(p => p.name).join(' / ');
365
366
return (
367
<div>
368
<div style={{ fontWeight: 'bold' }}>{pathNames}</div>
369
{item.description && (
370
<div style={{ fontSize: '12px', color: '#666' }}>
371
{item.description}
372
</div>
373
)}
374
</div>
375
);
376
}
377
}}
378
placeholder="Search products and descriptions"
379
style={{ width: 400 }}
380
/>
381
);
382
};
383
```
384
385
### Search Performance Optimization
386
387
```typescript
388
import { useMemo } from 'react';
389
390
const OptimizedSearchExample = () => {
391
// Memoize search configuration to prevent re-renders
392
const searchConfig = useMemo(() => ({
393
filter: (inputValue, path, fieldNames) => {
394
if (!inputValue) return false;
395
396
const input = inputValue.toLowerCase();
397
return path.some(option => {
398
const label = option[fieldNames.label];
399
return typeof label === 'string' &&
400
label.toLowerCase().includes(input);
401
});
402
},
403
limit: 100,
404
matchInputWidth: false
405
}), []);
406
407
return (
408
<Cascader
409
options={options}
410
showSearch={searchConfig}
411
placeholder="Optimized search"
412
/>
413
);
414
};
415
```