Paragon Design System

Technical Documentation

npm_version
Changelog
GitHub

SearchField

Search allows users to quickly find content. The Search field is made up of the Text field component and an optional Button component.

Basic Usage

With an initial value

With a placeholder

With callbacks

With a custom label

With custom screenreader text

With the submit button outside the input

Advanced Usage

For needs that deviate from the basic usage above, use <SearchField.Advanced />. The children elements must contain the SearchField.Label and SearchField.Input components at a minimum.

With a custom label

With an initial value

With a placeholder

With no clear button

With no submit or clear buttons

Advanced usage with the submit button outside the input

Use class pgn__searchfield_wrapper to group input elements apart from the submit button.

Theme Variables (SCSS)#

$search-btn-variants: (
        "light":  $primary-500,
        "dark":   $brand-500,
);
$search-border-radius:                0 !default;
$search-line-height:                  1.5rem !default;
$search-border-color:                 $gray-500 !default;
$search-border-color-interaction:     $black !default;
$search-border-width:                 .0625rem !default;
$search-border-width-interaction:     .125rem !default;
$search-disabled-opacity:             .3 !default;
$search-button-margin:                .5rem !default;
$input-height-search:                 calc(#{$input-line-height * 1em} + #{$input-padding-y * 2}) !default;
SearchField Props API
  • onSubmit
    func Required

    Specifies a callback function for when the SearchField is submitted by the user. For example:

    <SearchField onSubmit={(value) => { console.log(value); } />
  • label
    string | element

    Specifies the label to use for the input field (e.g., for i18n translations).

  • className
    string

    Specifies a custom class name.

  • onBlur
    func

    Specifies a callback function for when the user loses focus in the SearchField component. The default is an empty function. For example:

    <SearchField onBlur={event => console.log(event)} />
    Default() => {}
  • onChange
    func

    Specifies a callback function for when the value in SearchField is changed by the user. The default is an empty function. For example:

    <SearchField onChange={value => console.log(value)} />
    Default() => {}
  • onClear
    func

    Specifies a callback function for when the value in SearchField is cleared by the user. The default is an empty function. For example:

    <SearchField onClear={() => console.log('search cleared')} />
    Default() => {}
  • onFocus
    func

    Specifies a callback function for when the user focuses in the SearchField component. The default is an empty function. For example:

    <SearchField onFocus={event => console.log(event)} />
    Default() => {}
  • placeholder
    string

    Specifies the placeholder text for the input.

  • screenReaderText
    shape {
    label: string | element Required,
    submitButton: string | element Required,
    clearButton: string | element,
    }

    Specifies the screenreader text for both the clear and submit buttons (e.g., for i18n translations). The default is { label: 'search', clearButton: 'clear search', searchButton: 'submit search' }.

    Default{ label: SEARCH_FIELD_SCREEN_READER_TEXT_LABEL, submitButton: SEARCH_FIELD_SCREEN_READER_TEXT_SUBMIT_BUTTON, clearButton: SEARCH_FIELD_SCREEN_READER_TEXT_CLEAR_BUTTON, }
  • value
    string

    Specifies the initial value for the input. The default is an empty string.

    Default''
  • icons
    shape {
    submit: element Required,
    clear: element,
    }

    Specifies the icon element(s) to use for the clear and submit buttons. The default is:

    {
  submit: import {Search} from '@edx/paragon/icons';,
  clear: import {Close} from '@edx/paragon/icons'.
}
    Default{ clear: <Icon src={Close} />, submit: <Icon src={Search} />, }
  • formAriaLabel
    string

    Specifies the aria-label attribute on the form element. This is useful if you use the SearchField component more than once on a page.

  • inputProps
    shape {}

    Props to be passed to the form input

    Default{}
  • variant
    enum'light' | 'dark'

    The button style variant to use.

    Default'light'
  • disabled
    bool

    Specifies whether the SearchField is disabled.

    Defaultfalse
  • submitButtonLocation
    enum'internal' | 'external'

    Controls whether the search button is internal as an icon or external as a button.

    Default'internal'
  • buttonText
    string

    Specifies a text that is displayed on the button. The submitButtonLocation prop should be set to external.

    Default'search'
SearchFieldAdvanced Props API
  • children
    node Required

    specifies the nested child elements. At a minimum, SearchField.Label and SearchField.Input are required.

  • onSubmit
    func Required

    specifies a callback function for when the SearchField is submitted by the user. For example:

    <SearchField onSubmit={(value) => { console.log(value); } />
  • className
    string

    specifies a custom class name.

  • onBlur
    func

    specifies a callback function for when the user loses focus in the SearchField component. The default is an empty function. For example:

    <SearchField onBlur={event => console.log(event)} />
    Default() => {}
  • onChange
    func

    specifies a callback function for when the value in SearchField is changed by the user. The default is an empty function. For example:

    <SearchField onChange={value => console.log(value)} />
    Default() => {}
  • onClear
    func

    specifies a callback function for when the value in SearchField is cleared by the user. The default is an empty function. For example:

    <SearchField onClear={() => console.log('search cleared')} />
    Default() => {}
  • onFocus
    func

    specifies a callback function for when the user focuses in the SearchField component. The default is an empty function. For example:

    <SearchField onFocus={event => console.log(event)} />
    Default() => {}
  • screenReaderText
    shape {
    label: string | element Required,
    submitButton: string | element Required,
    clearButton: string | element,
    }

    specifies the screenreader text for both the clear and submit buttons (e.g., for i18n translations). The default is { label: 'search', clearButton: 'clear search', searchButton: 'submit search' }.

    Default{ label: 'search', submitButton: 'submit search', clearButton: 'clear search', }
  • value
    string

    specifies the initial value for the input. The default is an empty string.

    Default''
  • icons
    shape {
    submit: element Required,
    clear: element,
    }

    specifies the icon element(s) to use for the clear and submit buttons.

    Default{ clear: <Icon src={Close} />, submit: <Icon src={Search} />, }
  • formAriaLabel
    string

    specifies the aria-label attribute on the form element. This is useful if you use the SearchField component more than once on a page.

  • disabled
    bool

    Specifies whether the SearchField is disabled.

    Defaultfalse
  • submitButtonLocation
    enum'internal' | 'external'

    Controls whether the search button is internal as an icon or external as a button.

    Default'internal'
SearchFieldClearButton Props API
This component does not receive any props.
SearchFieldInput Props API
  • className
    string

    specifies a custom class name.

  • placeholder
    string

    specifies the placeholder text for the input.

SearchFieldLabel Props API
  • children
    string | element

    specifies the label to use for the input field (e.g., for i18n translations). Note: if children is not provided, a screenreader-only label will be used in its placed based on the screenReaderText.label prop for SearchField.Advanced.

SearchFieldSubmitButton Props API
  • variant
    enum'light' | 'dark'

    The button style variant to use.

    Default'light'
  • submitButtonLocation
    enum'internal' | 'external'

    Controls whether the search button is internal as an icon or external as a button.

    Default'internal'
  • buttonText
    string

    Specifies a text that is displayed on the button. The submitButtonLocation prop should be set to external.

    Default'Search'

Contents

Guides

Foundations

Components

Buttonlike
Choreography
Content
Forms
Forms (deprecated)
Hooks
Imagery & Iconography
Layout
Navigation
Overlays
Status & metadata
Table

All components (A-Z)