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

Table of Contents

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

InputSearchListItem

PropDescriptionTypeDefaultRequired
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
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
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
title
string
----False

InputSearchRoot

PropDescriptionTypeDefaultRequired
aria-labelDefines a string value that labels the current element. @see aria-labelledby.
string
----False
aria-labelledbyIdentifies the element (or elements) that labels the current element. @see aria-describedby.
string
----False
childrenInputSearch.Root expects to receive InputSearch.Input and InputSearch.Popover as children.
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
disabledWhether the input field should be disabled or not
boolean
----False
openOnFocusIf true, the popover opens when focus is on the text box.
boolean
----False
onSelectCalled with the selection value when the user makes a selection from the list.
((value: string) => void) & ReactEventHandler<HTMLDivElement>
----False

InputSearchInput

PropDescriptionTypeDefaultRequired
iconThe position of the icon in the input
"left" | "right" | "none"
 none False
errorIndicates there is an error
boolean
----False
successindicates there is a success
boolean
----False
disabledThe underlying input element disabled attribute
boolean
----False
labelThe input's label text, required for accessibility
string
 Search False
valueThe input element value for controlled components
string
----False
defaultValueThe initial input element value for uncontrolled components
string
----False
idThe id for the underlying input element. Required for accessibility
string
----
True
placeholderplaceholder text
string
----False
childrenUsed to insert Icons in the input, only a single child is accepted
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
(event: ChangeEvent<HTMLInputElement>) => void
----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?: AlignContent | ScaleValue | Globals | Index; alignItems?: AlignItems | ScaleValue | Globals | Index; ... 425 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & {} & {} & { ...; }
----False
buttonIconTextAccessible text for button icon, required for right icons
string
----False
nameThe name for the underlying input element
string
----
True
requiredThe input elements required attribute
boolean
----False
typeSupported input element types
"text" | "search" | "tel" | "url" | "email" | "password"
 text False
buttonIconTypeExplicit button icon typing for use in forms
"button" | "reset" | "submit"
----False
errorMessageText displayed below the input to describe the cause of the error
ReactNode
----False
helperTextText displayed below the input to provide additional context
ReactNode
----False
onButtonIconClickCallback executed when the button icon on the right is click to perform an action
(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void
----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.
boolean
 true False

InputSearchPopover

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
sideOffsetDistance 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
widthWidth 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
onEscapeKeyDownEvent handler called when the escape key is down. Can be prevented.
(event: KeyboardEvent) => void
----False
onPointerDownOutsideEvent handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
(event: PointerDownOutsideEvent) => void
----False
onFocusOutsideEvent handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.
(event: FocusOutsideEvent) => void
----False
onInteractOutsideEvent 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
onOpenAutoFocusEvent handler called when auto-focusing on open. Can be prevented.
(event: Event) => void
----False
onCloseAutoFocusEvent handler called when auto-focusing on close. Can be prevented.
(event: Event) => void
----False
forceMountUsed 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

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

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

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
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
Edit this page on GitHub.
CommunityXTwittergithubGithubyoutubeYoutube