Paragon Design System

Technical Documentation

Theme

PlaygroundBeta

npm_versionnpm Paragon package page

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

Any Paragon component or export may be added to the code example.

With an initial value

Any Paragon component or export may be added to the code example.

With a placeholder

Any Paragon component or export may be added to the code example.

With callbacks

Any Paragon component or export may be added to the code example.

With a custom label

Any Paragon component or export may be added to the code example.

With custom screenreader text

Any Paragon component or export may be added to the code example.

With the submit button outside the input

Any Paragon component or export may be added to the code example.

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

Any Paragon component or export may be added to the code example.

With an initial value

Any Paragon component or export may be added to the code example.

With a placeholder

Any Paragon component or export may be added to the code example.

With no clear button

Any Paragon component or export may be added to the code example.

With no submit or clear buttons

Any Paragon component or export may be added to the code example.

Advanced usage with the submit button outside the input

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

Any Paragon component or export may be added to the code example.

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;
$search-border-focus-color:            $black !default;
$search-border-focus-width:            .3125rem !default;

Props API#

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'

Usage Insights#

SearchField

Project NameParagon VersionInstance Count
frontend-app-admin-portal20.26.31
frontend-app-discussions20.15.01
frontend-app-gradebook19.25.41
frontend-app-library-authoring20.30.11
frontend-app-program-console20.28.41
frontend-app-publisher20.28.51
studio-frontend3.4.81

SearchFieldAdvanced

Project NameParagon VersionInstance Count
frontend-app-discussions20.15.02
catalog-search19.25.11
prospectus20.28.34

SearchFieldClearButton

Project NameParagon VersionInstance Count
catalog-search19.25.11
prospectus20.28.34

SearchFieldInput

Project NameParagon VersionInstance Count
frontend-app-discussions20.15.02
catalog-search19.25.11
prospectus20.28.34

SearchFieldLabel

Project NameParagon VersionInstance Count
frontend-app-discussions20.15.02

SearchFieldSubmitButton

Project NameParagon VersionInstance Count
catalog-search19.25.11
prospectus20.28.35

Contents

All components (A-Z)