SearchInput

core package3.2.2

Note: All components shown on this site are supported by the Constellation design system. To learn how to configure Theme Cosmos, visit Pega Community.

SearchInputs collect search queries and can accept any user input.

Usage

The SearchInput component can be an either controlled or uncontrolled input. If you wish to use a controlled SearchInput, utilize the value and onSearchChange props. For an uncontrolled SearchInput, use the defaultValue prop.

This component has a default placeholder of Search..., which can be configured to specify which resources are being searched. When the Enter key is hit while the SearchInput is in focus, an onSearchSubmit callback function is trigged.

Accessibility

Using the <form> element in conjunction with a declaration of role="search" will provide the largest amount of accessibility support.

<form role="search">
  <SearchInput searchInputAriaLabel="global" />
</form>

Generally, this is used for a global search, which typically only has one occurrence on a page. If more than one occurrence is anticipated, please be aware that each <form role="search" /> will appear as a search landmark and could potentially make the page "busy" for screen readers.

When not wrapping the Field in a <form />, please be sure to provide the searchInputAriaLabel to the SearchInput.

Note: There is no need to use the word "search" again in value, the screen reader will pick that name with role=”search” attribute itself.

<form role="search" aria-label="Global Search">
  <input type="search" name="test" />
</form>

Screen reader will read "Global search search landmark"

Example

Advanced search options

The SearchInput component allows for advanced search capabilities through a series of props such as filters, defaultFilter, onFilterChange, searchResults, recentSearches, loading, and advancedSearchLink. It is not required to include all of these props. Each one of them will enhance the SearchInput's core functionality.

Filters are included as a dropdown menu alongside the SearchInput. They should be used to restrict a search to a particular scope. The advancedSearchLink is intended to navigate a user to another page, such as SearchResults, and maintain the user's search query in that new view.

Example

Related components

Properties

NameDescriptionDefaultType
advancedSearchLinkProp passed to the advanced search page link.OmitStrict<LinkProps, 'children'>
defaultFilterThe selected scope filter on initial render.string
filtersA list of user selectable scopes to filter search with.string[]
loadingPlaces the menu into an indeterminate loading state.boolean
onFilterChange(value: string) => void
onSearchChange(value: string) => void
onSearchSubmit(value: string) => void
placeholderPlaceholder text. The default value is a locale translation of 'Search…'"Search…"string
recentSearchesA list of recent searches presented in the input's dropdown menu.RecentSearch[]
resultsPopoverBoolean for determining for whether the search results will render in a popover.trueboolean
searchInputAriaLabelAria label for search input, used by screen readers.string
searchResultsA list of matching results presented in the input's dropdown menu.SearchResult[]
valueCreates a controlled input and sets the value. Requires an onChange handler to update value. value + onChange is the recommended method per React team.string

Custom theming

You can override the styles of the SearchInput component by setting a custom theme on the Configuration component.

Theme properties

{
      •       'border-radius': 9999
      •     }
    •   }
}