Anatomy
Note: Image not to scale
- Label/Placeholder
- Input
- Clear button
- Search button
- Value
- Divider
- Result
- Result container
Options
Portal
Determine whether the result container should be rendered as part of the search component and occupy space, or act more like a popover with a positional relationship.
Grouping
The search component supports a default group label that includes an optional icon. This feature can be utilized to help organize content and support multiple result groups. By default, the component returns results as a single list of items. The order in which they are returned depends on how the data is sorted prior to being passed.
Open on focus
Setting 'open on focus' to false will prevent the result container from appearing when there is no value in the input, or the value has not changed.
Behavior
Autocomplete
Determines if the value is the input changes or not as the user navigates with the keyboard. If true, the value changes. If false, the value doesn't change.
Disabled
Selected
When a user has made a selection, the results container will collapse when the portal is set to false or disappear when the portal is set to true.
Overflow
The results container has a default max-height of 300px and when there are more results it will overflow with a default scrollbar.
Input with value
When the input has a text value, a clear button will appear to allow the user to easily clear the input value and set it to an empty value.
Loading results
When results are being loaded a default behavior of a loading state will be shown.
Empty: No Results
When there are no matching results the default behavior is to show them empty no result state.
Matching results
When a result is matched to the keyword the font weight will be light to the matching keys and the rest of the characters as bold.
Results :Hover
When a result is hovered with a mouse it will change background color $faint.
Guidance
Results can be more than text
Results can be more than just a list of text. Depending on how you handle matching results, there could be space for recirculation, a different hierarchy in how results are displayed, and a more intuitive and visual discovery process.
When to use icons
Results can be overwhelming depending on the query. To differentiate between different types of results, use icons to help users wayfind and scan the results.
Helpful filtering
Helpful filtering can help folks get to their results faster without having to type in the correct keywords. Some ideas can include inputs like switches, and tabs.
Mobile best practices
There might be instances where a dedicated search view might be more appropriate. Utilizing the pattern of our drawer can be an effective way to do this.
Pre-populated results
Pre-populate the dropdown when the search is in focus, letting users quickly scan and refine their choice before even searching.
Accessibility
Color contrast
All colors in the default combobox have been reviewed to ensure they meet the AA WCAG contrast requirement of at least 4.5:1 for normal text and 3:1 for large text.
Keyboard controls
Users can navigate search results using arrow keys on their keyboard and select a result by pressing the return key. This feature streamlines the search experience, reduces search time, and improves accessibility.
API Reference
InputSearchRoot
| Prop | Description | Type | Default | Required |
|---|
InputSearchPopover
| Prop | Description | Type | Default | Required |
|---|
InputSearchList
| Prop | Description | Type | Default | Required |
|---|
InputSearchListItem
| Prop | Description | Type | Default | Required |
|---|
InputSearchItemText
| Prop | Description | Type | Default | Required |
|---|
InputSearchListHeading
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Any React node may be used as a child | React.ReactNode | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
InputSearchEmptyState
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| text | Text Displayed | React.ReactNode | No results found | False |
InputSearchLoadingState
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |