WPDS Documentation & Resources

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.


Open in Playroom

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 in Playroom

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.


Open in Playroom

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.


Open in Playroom

Disabled


Open in Playroom

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.


Open in Playroom

Overflow

The results container has a default max-height of 300px and when there are more results it will overflow with a default scrollbar.


Open in Playroom

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.


Open in Playroom

Loading results

When results are being loaded a default behavior of a loading state will be shown.


Open in Playroom

Empty: No Results

When there are no matching results the default behavior is to show them empty no result state.


Open in Playroom

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.


Open in Playroom

Results :Hover

When a result is hovered with a mouse it will change background color $faint.


Open in Playroom

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.


Open in Playroom

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.


Open in Playroom

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.


Open in Playroom

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.


Open in Playroom

Pre-populated results

Pre-populate the dropdown when the search is in focus, letting users quickly scan and refine their choice before even searching.


Open in Playroom

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
disabled	Whether the input field should be disabled or not	boolean	false	False
as	WPDS provides an as prop for changing which tag a component outputs.	"div"	----	False
aria-label	Defines a string value that labels the current element. @see Docs https://reach.tech/combobox#accessibility	string	----	False
aria-labelledby	Identifies the element (or elements) that labels the current element. @see Docs https://reach.tech/combobox#accessibility	string	----	False
children	@see Docs https://reach.tech/combobox#combobox-children	ReactNode \| ((props: ComboboxContextValue) => ReactNode)	----	True
onSelect	Called with the selection value when the user makes a selection from the list. @see Docs https://reach.tech/combobox#combobox-onselect	(value: string) => void	----	False
openOnFocus	If true, the popover opens when focus is on the text box. @see Docs https://reach.tech/combobox#combobox-openonfocus	boolean	----	False
portal		boolean \| "false" \| ({ "@sm"?: boolean \| "false"; "@md"?: boolean \| "false"; "@lg"?: boolean \| "false"; "@xl"?: boolean \| "false"; "@xxl"?: boolean \| "false"; "@notSm"?: boolean \| "false"; "@notMd"?: boolean \| "false"; ... 17 more ...; "@initial"?: 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

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
as	WPDS provides an as prop for changing which tag a component outputs.	"input"	----	False
defaultValue	The initial input element value for uncontrolled components	(string \| number \| readonly string[]) & string	----	False
id	The id for the underlying input element. Required for accessibility	string	----	False
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	ChangeEventHandler<HTMLInputElement> & ((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; ... 425 more ...; vectorEffect?: VectorEffect \| ... 2 more ... \| Index; } & {} & {} & { ...; }	----	False
required	The input elements required attribute	boolean	----	False
name	The name for the underlying input element	string	----	False
type	Supported input element types	HTMLInputTypeAttribute & ("text" \| "search" \| "tel" \| "url" \| "email" \| "password")	text	False
value	The input element value for controlled components @see Docs https://reach.tech/combobox#comboboxinput-value	string	----	False
selectOnClick	If true, when the user clicks inside the text box the current value will be selected. Use this if the user is likely to delete all the text anyway (like the URL bar in browsers). However, if the user is likely to want to tweak the value, leave this false, like a google search--the user is likely wanting to edit their search, not replace it completely. @see Docs https://reach.tech/combobox#comboboxinput-selectonclick	boolean	----	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. @see Docs https://reach.tech/combobox#comboboxinput-autocomplete	boolean	----	False
buttonIconText	Accessible text for button icon, required for right icons	string	----	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

InputSearchPopover

Prop	Description	Type	Default	Required
position		Position	----	False
hidden	Render the popover markup, but hide it – used by MenuButton so that it can have an `aria-controls` attribute even when its menu isn't open, and used inside `Popover` as a hint that we can tell `useRect` to stop observing for better performance.	boolean	----	False
portal	If you pass `<ComboboxPopover portal={false} />` the popover will not render inside of a portal, but in the same order as the React tree. This is mostly useful for styling the entire component together, like the pink focus outline in the example earlier in this page. @see Docs https://reach.tech/combobox#comboboxpopover-portal	boolean	true	False
as	WPDS provides an as prop for changing which tag a component outputs.	"div"	----	False
targetRef		RefObject<PossibleNode>	----	False
floating		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

InputSearchList

Prop	Description	Type	Default	Required
as	WPDS provides an as prop for changing which tag a component outputs.	"ul"	----	False
persistSelection	Defaults to false. When true and the list is opened, if an option's value matches the value in the input, it will automatically be highlighted and be the starting point for any keyboard navigation of the list. This allows you to treat a Combobox more like a `<select>` than an `<input/>`, but be mindful that the user is still able to put any arbitrary value into the input, so if the only valid values for the input are from the list, your app will need to do that validation on blur or submit of the form. @see Docs https://reach.tech/combobox#comboboxlist-persistselection	boolean	----	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

InputSearchListItem

Prop	Description	Type	Default	Required
as	WPDS provides an as prop for changing which tag a component outputs.	"li"	----	False
children	Optional. If omitted, the `value` will be used as the children like as: `<ComboboxOption value="Seattle, Tacoma, Washington" />`. But if you need to control a bit more, you can put whatever children you want, but make sure to render a `ComboboxOptionText` as well, so the value is still displayed with the text highlighting on the matched portions. @example <ComboboxOption value="Apple" /> 🍎 <ComboboxOptionText /> </ComboboxOption> @see Docs https://reach.tech/combobox#comboboxoption-children	ReactNode \| ((props: ComboboxOptionContextValue) => 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<{ 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
value	The value to match against when suggesting. @see Docs https://reach.tech/combobox#comboboxoption-value	string	----	True

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

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

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

Input Search

Table of Contents