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;
$search-border-focus-color:           $black !default;
$search-border-focus-width:           .3125rem !default;
SearchField Props API
  • onSubmit func Required Required

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

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

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

  • className string Required

    Specifies a custom class name.

  • onBlur func Required

    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 Required

    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 Required

    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 Required

    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 Required

    Specifies the placeholder text for the input.

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

    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 Required

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

    Default''
  • icons shape Required {
    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 Required

    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 Required {}

    Props to be passed to the form input

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

    The button style variant to use.

    Default'light'
  • disabled bool Required

    Specifies whether the SearchField is disabled.

    Defaultfalse
  • submitButtonLocation enum Required'internal' | 'external'

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

    Default'internal'
  • buttonText string Required

    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 Required

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

  • onSubmit func Required Required

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

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

    specifies a custom class name.

  • onBlur func Required

    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 Required

    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 Required

    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 Required

    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 Required {
    label: string Required | element Required Required,
    submitButton: string Required | element Required Required,
    clearButton: string Required | element Required,
    }

    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 Required

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

    Default''
  • icons shape Required {
    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 Required

    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 Required

    Specifies whether the SearchField is disabled.

    Defaultfalse
  • submitButtonLocation enum Required'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 Required

    specifies a custom class name.

  • placeholder string Required

    specifies the placeholder text for the input.

SearchFieldLabel Props API
  • children string Required | element Required Required

    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 Required'light' | 'dark'

    The button style variant to use.

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

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

    Default'internal'
  • buttonText string Required

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

    Default'Search'

Contents

Guides

Foundations

PlaygroundBeta

  • A drag-and-drop UI builder for prototyping with Paragon components.

Components

Buttonlike

Choreography

Content

Forms

Forms (deprecated)

Hooks

Imagery & Iconography

Layout

Navigation

Overlays

Status & metadata

Table

All components (A-Z)