Skip to main content
Design system

Input Search

Input Search is a component that allows users to enter keywords and receive matching search results.

Bundle size: 178.44 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { InputSearch } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github
Primitive:  View their docs

Anatomy

Note: Image not to scale

  1. Label/Placeholder
  2. Input
  3. Clear button
  4. Search button
  5. Value
  6. Divider
  7. Result
  8. 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

PropDescriptionTypeDefaultRequired
disabledWhether the input field should be disabled or not
enum
boolean
false False
asWPDS provides an as prop for changing which tag a component outputs.
"div"
----False
aria-labelDefines a string value that labels the current element. @see Docs https://reach.tech/combobox#accessibility
string
----False
aria-labelledbyIdentifies 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
enum
ReactNode | ((props: ComboboxContextValue) => ReactNode)
----
True
onSelectCalled 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
openOnFocusIf true, the popover opens when focus is on the text box. @see Docs https://reach.tech/combobox#combobox-openonfocus
enum
boolean
----False
portal
enum
boolean | false
----False
cssWPDS 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

PropDescriptionTypeDefaultRequired
labelThe input's label text, required for accessibility
string
Search False
asWPDS provides an as prop for changing which tag a component outputs.
"input"
----False
defaultValueThe initial input element value for uncontrolled components
enum
(string | number | readonly string[]) & string
----False
idThe id for the underlying input element. Required for accessibility
string
----False
placeholderplaceholder text
string
----False
childrenUsed to insert Icons in the input, only a single child is accepted
enum
ReactNode
----False
onFocusCallback executed when the input fires a focus event
FocusEventHandler<HTMLInputElement>
----False
onBlurCallback executed when the input fires a blur event
FocusEventHandler<HTMLInputElement>
----False
onChangeCallback executed when the input fires a change event
ChangeEventHandler<HTMLInputElement> & ((event: ChangeEvent<HTMLInputElement>) => void)
----False
disabledThe underlying input element disabled attribute
enum
boolean
----False
errorIndicates there is an error
enum
boolean
----False
successindicates there is a success
enum
boolean
----False
iconThe position of the icon in the input
enum
none | left | right
none False
cssWPDS 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?: ScaleValue | Globals | Index | AlignContent; alignItems?: ScaleValue | Globals | Index | AlignItems; ... 425 more ...; vectorEffect?: ScaleValue | ... 2 more ... | VectorEffect; } & {} & {} & { ...; }
----False
nameThe name for the underlying input element
string
----False
requiredThe input elements required attribute
enum
boolean
----False
typeSupported input element types
enum
HTMLInputTypeAttribute & (search | text | tel | url | email | password)
text False
valueThe input element value for controlled components @see Docs https://reach.tech/combobox#comboboxinput-value
string
----False
selectOnClickIf 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
enum
boolean
----False
autocompleteDetermines 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
enum
boolean
----False
buttonIconTextAccessible text for button icon, required for right icons
string
----False
buttonIconTypeExplicit button icon typing for use in forms
enum
button | reset | submit
----False
errorMessageText displayed below the input to describe the cause of the error
enum
ReactNode
----False
helperTextText displayed below the input to provide additional context
enum
ReactNode
----False
onButtonIconClickCallback executed when the button icon on the right is click to perform an action
(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void
----False

InputSearchPopover

PropDescriptionTypeDefaultRequired
asWPDS provides an as prop for changing which tag a component outputs.
"div"
----False
hiddenRender 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.
enum
boolean
----False
position
Position
----False
portalIf 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
enum
boolean
true False
targetRef
RefObject<PossibleNode>
----False
floating
enum
boolean | true
----False
cssWPDS 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

PropDescriptionTypeDefaultRequired
asWPDS provides an as prop for changing which tag a component outputs.
"ul"
----False
persistSelectionDefaults 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
enum
boolean
----False
cssWPDS 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

PropDescriptionTypeDefaultRequired
asWPDS provides an as prop for changing which tag a component outputs.
"li"
----False
childrenOptional. 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
enum
ReactNode | ((props: ComboboxOptionContextValue) => ReactNode)
----False
cssWPDS 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
valueThe value to match against when suggesting. @see Docs https://reach.tech/combobox#comboboxoption-value
string
----
True

InputSearchItemText

PropDescriptionTypeDefaultRequired
cssWPDS 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

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child
enum
ReactNode
----False
cssWPDS 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

PropDescriptionTypeDefaultRequired
cssWPDS 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
textText Displayed
enum
ReactNode
No results found False

InputSearchLoadingState

PropDescriptionTypeDefaultRequired
cssWPDS 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