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
InputSearchListItem
Prop | Description | Type | Default | Required |
---|---|---|---|---|
value | string & (string | number | readonly string[]) | ---- | False | |
disabled | boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; "@notMd"?: boolean | "true"; ... 17 more ...; "@initial"?: boolean | "true"; } & { ...; }) | ---- | False | |
selected | boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; "@notMd"?: boolean | "true"; ... 17 more ...; "@initial"?: boolean | "true"; } & { ...; }) | ---- | False | |
focused | boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; "@notMd"?: boolean | "true"; ... 17 more ...; "@initial"?: boolean | "true"; } & { ...; }) | ---- | 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<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
InputSearchListHeading
Prop | Description | Type | Default | Required |
---|---|---|---|---|
children | Any React node may be used as a child | 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 |
title | string | ---- | False |
InputSearchRoot
Prop | Description | Type | Default | Required |
---|---|---|---|---|
aria-label | Defines a string value that labels the current element. @see aria-labelledby. | string | ---- | False |
aria-labelledby | Identifies the element (or elements) that labels the current element. @see aria-describedby. | string | ---- | False |
children | InputSearch.Root expects to receive InputSearch.Input and InputSearch.Popover as children. | 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 |
disabled | Whether the input field should be disabled or not | boolean | ---- | False |
openOnFocus | If true, the popover opens when focus is on the text box. | boolean | ---- | False |
onSelect | Called with the selection value when the user makes a selection from the list. | ((value: string) => void) & ReactEventHandler<HTMLDivElement> | ---- | False |
InputSearchInput
Prop | Description | Type | Default | Required |
---|---|---|---|---|
icon | The position of the icon in the input | "left" | "right" | "none" | none | False |
error | Indicates there is an error | boolean | ---- | False |
success | indicates there is a success | boolean | ---- | False |
disabled | The underlying input element disabled attribute | boolean | ---- | False |
label | The input's label text, required for accessibility | string | Search | False |
value | The input element value for controlled components | string | ---- | False |
defaultValue | The initial input element value for uncontrolled components | string | ---- | False |
id | The id for the underlying input element. Required for accessibility | string | ---- | True |
placeholder | placeholder text | string | ---- | False |
children | Used to insert Icons in the input, only a single child is accepted | ReactNode | ---- | False |
onFocus | Callback executed when the input fires a focus event | FocusEventHandler<HTMLInputElement> | ---- | False |
onBlur | Callback executed when the input fires a blur event | FocusEventHandler<HTMLInputElement> | ---- | False |
onChange | Callback executed when the input fires a change event | (event: ChangeEvent<HTMLInputElement>) => void | ---- | 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. | {} & { alignContent?: AlignContent | ScaleValue | Globals | Index; alignItems?: AlignItems | ScaleValue | Globals | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & {} & {} & { ...; } | ---- | False |
buttonIconText | Accessible text for button icon, required for right icons | string | ---- | False |
name | The name for the underlying input element | string | ---- | True |
required | The input elements required attribute | boolean | ---- | False |
type | Supported input element types | "text" | "search" | "tel" | "url" | "email" | "password" | text | False |
buttonIconType | Explicit button icon typing for use in forms | "button" | "reset" | "submit" | ---- | False |
errorMessage | Text displayed below the input to describe the cause of the error | ReactNode | ---- | False |
helperText | Text displayed below the input to provide additional context | ReactNode | ---- | False |
onButtonIconClick | Callback executed when the button icon on the right is click to perform an action | (event: MouseEvent<HTMLButtonElement, MouseEvent>) => void | ---- | False |
autocomplete | Determines if the value in the input changes or not as the user navigates with the keyboard. If true, the value changes, if false the value doesn't change. Set this to false when you don't really need the value from the input but want to populate some other state (like the recipient selector in Gmail). But if your input is more like a normal `<input type="text"/>`, then leave the `true` default. | boolean | true | False |
InputSearchPopover
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 |
sideOffset | Distance between trigger and content | number | Token<"100" | "125" | "150" | "175" | "200" | "225" | "250" | "275" | "300" | "350" | "400" | "450" | "500" | "075" | "087" | "025" | "050", string, "space", "wpds"> | ---- | False |
width | Width of the popover content | number | ---- | False |
density | "default" | "compact" | ({ "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; "@xxl"?: "default" | "compact"; "@notSm"?: "default" | "compact"; ... 18 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | ---- | False | |
sticky | "always" | "partial" | ---- | False | |
asChild | boolean | ---- | False | |
side | "bottom" | "left" | "right" | "top" | ---- | False | |
align | "center" | "end" | "start" | ---- | False | |
alignOffset | number | ---- | False | |
arrowPadding | number | ---- | False | |
avoidCollisions | boolean | ---- | False | |
collisionBoundary | Element | Element[] | ---- | False | |
collisionPadding | number | Partial<Record<"bottom" | "left" | "right" | "top", number>> | ---- | False | |
hideWhenDetached | boolean | ---- | False | |
updatePositionStrategy | "always" | "optimized" | ---- | False | |
onEscapeKeyDown | Event handler called when the escape key is down. Can be prevented. | (event: KeyboardEvent) => void | ---- | False |
onPointerDownOutside | Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. | (event: PointerDownOutsideEvent) => void | ---- | False |
onFocusOutside | Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. | (event: FocusOutsideEvent) => void | ---- | False |
onInteractOutside | Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. | (event: PointerDownOutsideEvent | FocusOutsideEvent) => void | ---- | False |
onOpenAutoFocus | Event handler called when auto-focusing on open. Can be prevented. | (event: Event) => void | ---- | False |
onCloseAutoFocus | Event handler called when auto-focusing on close. Can be prevented. | (event: Event) => void | ---- | False |
forceMount | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. | true | ---- | False |
portal | boolean | true | False | |
portalDomNode | HTMLElement | ---- | False |
InputSearchList
Prop | Description | Type | Default | Required |
---|---|---|---|---|
persistSelection | boolean | false | 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<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
InputSearchItemText
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<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | 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 | 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 |