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

    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

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)