SearchField

SearchField accepts query text for search.

Users may clear the field by hitting the Esc key or by clicking the clear button. When users hit Enter key or click the search icon, the onSubmit event handler will be fired.

Demo

Usage

Import the SearchField primitive, and provide a label for accessibility/usability.

import { SearchField } from '@aws-amplify/ui-react';

export const DefaultSearchFieldExample = () => <SearchField label="search" />;

Note: The clear text (x) button will show after user has entered text.

Controlled component

import { SearchField } from '@aws-amplify/ui-react';
import * as React from 'react';

export const SearchFieldControlledExample = () => {
  const [value, setValue] = React.useState('');

  const onChange = (event) => {
    setValue(event.target.value);
  };

  // It is your responsibility to set up onClear
  const onClear = () => {
    setValue('');
  };

  return (
    <SearchField
      label="search"
      onChange={onChange}
      onClear={onClear}
      value={value}
    />
  );
};

Note: When you use SearchField in controlled way, it is your responsibility to set up onClear other than onChange since the input value is under your control.

Accessibility / Label behavior

Placeholder

Text that appears in the form control when it has no value set.

import { SearchField } from '@aws-amplify/ui-react';

export const PlaceholderSearchFieldExample = () => (
  <SearchField label="search" placeholder="Search..." />
);

Sizes

Use the size prop to change SearchField size. Available options are small, large, and none (default).

import { SearchField, Flex } from '@aws-amplify/ui-react';

export const SizeSearchFieldExample = () => (
  <Flex direction="column">
    <SearchField label="search" size="small" />
    <SearchField label="search" />
    <SearchField label="search" size="large" />
  </Flex>
);

Variations

There are two variation styles available: default and quiet.

import { SearchField, Flex } from '@aws-amplify/ui-react';

export const VariationSearchFieldExample = () => (
  <Flex direction="column">
    <SearchField label="search" />
    <SearchField label="search" variation="quiet" />
  </Flex>
);

Forward refs

The standard ref prop will forward to the input element, the searchButtonRef prop forwards to the search button element.

The following is a contrived example demonstrating use of the ref props:

import * as React from 'react';
import { SearchField } from '@aws-amplify/ui-react';

export const RefExample = () => {
  const inputRef = React.useRef(null);
  const searchButtonRef = React.useRef(null);

  const onClick = React.useCallback(() => {
    inputRef.current.focus();
    alert(`You searched for: ${inputRef.current.value}`);
  }, []);

  React.useEffect(() => {
    const searchButtonRefCurrent = searchButtonRef.current;
    if (searchButtonRef && searchButtonRefCurrent) {
      // Note: this example is contrived to demonstrate using refs.
      // Use the `onSubmit` prop on `SearchField` instead which
      // responds to input field `Enter` keypresses and Submit button clicks.
      searchButtonRefCurrent.addEventListener('click', onClick, false);
      return () => {
        searchButtonRefCurrent.removeEventListener('click', onClick, false);
      };
    }
  }, [onClick]);

  return (
    <SearchField
      label="Password"
      ref={inputRef}
      searchButtonRef={searchButtonRef}
    />
  );
};

Standard HTML attributes

The SearchField will accept any of the standard HTML attributes that a <input> element accepts. Standard <input> attributes can be found in the MDN Documentation

<SearchField label="Search" name="search"/>

Styling

Theme

You can customize the appearance of all SearchField components in your application with a Theme.

SearchField Theme Source

import { SearchField, ThemeProvider, Theme } from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'searchfield-theme',
  tokens: {
    components: {
      searchfield: {
        button: {
          color: { value: '{colors.blue.80}' },
          backgroundColor: { value: '{colors.blue.20}' },
          _focus: {
            backgroundColor: {
              value: '{colors.blue.60}',
            },
            color: { value: 'white' },
          },
          _hover: {
            backgroundColor: {
              value: '{colors.blue.80}',
            },
            color: { value: 'white' },
          },
        },
      },
    },
  },
};

export const SearchFieldThemeExample = () => {
  return (
    <ThemeProvider theme={theme} colorMode="light">
      <SearchField label="search" />
    </ThemeProvider>
  );
};

Icons

import { SearchField, IconsProvider } from '@aws-amplify/ui-react';
import { FiSearch } from 'react-icons/fi';

export const SearchFieldIconExample = () => (
  <IconsProvider
    icons={{
      searchField: {
        search: <FiSearch />,
      },
    }}
  >
    <SearchField label="Password" />
  </IconsProvider>
);

Target classes

Class	Description
`amplify-searchfield`	Top level element that wraps the SearchField primitive
`amplify-searchfield__clear`	Class applied to the search field clear button
`amplify-searchfield__search`	Class applied to the search button

--amplify-components-searchfield-button-active-background-color
--amplify-components-searchfield-button-active-border-color
--amplify-components-searchfield-button-active-color
--amplify-components-searchfield-button-background-color
--amplify-components-searchfield-button-color
--amplify-components-searchfield-button-disabled-background-color
--amplify-components-searchfield-button-disabled-border-color
--amplify-components-searchfield-button-disabled-color
--amplify-components-searchfield-button-focus-background-color
--amplify-components-searchfield-button-focus-border-color
--amplify-components-searchfield-button-focus-color
--amplify-components-searchfield-button-hover-background-color
--amplify-components-searchfield-button-hover-border-color
--amplify-components-searchfield-button-hover-color
--amplify-components-searchfield-color

Global styling

To override styling on all SearchField primitives, you can set the Amplify CSS variables or use the built-in .amplify-searchfield class.

/* styles.css */
:root {
  --amplify-components-button-color: black;
  --amplify-components-button-border-color: black;
  --amplify-components-fieldcontrol-border-color: black;
}
/* OR */
.amplify-searchfield {
  --amplify-components-button-color: black;
  --amplify-components-button-border-color: black;
  --amplify-components-fieldcontrol-border-color: black;
}

/* styles.css */
.amplify-searchfield {
  --amplify-components-button-color: rebeccapurple;
  --amplify-components-button-border-color: rebeccapurple;
  --amplify-components-fieldcontrol-border-color: rebeccapurple;
}

Local styling

To override styling on a specific SearchField, you can use a class selector or style props.

Using a class selector:

/* styles.css */
.custom-searchfield-class .amplify-input,
.custom-searchfield-class .amplify-button {
  border-radius: 0;
}

Using style props:

All style props will be applied to the Flex wrapper of the SearchField. To style the input of the SearchField, you can pass a inputStyles prop with the style props you want to apply to the input.

import { SearchField, useTheme } from '@aws-amplify/ui-react';

export const SearchFieldStyledPropsExample = () => {
  const { tokens } = useTheme();

  return (
    <>
      <SearchField
        label="search"
        padding="xl"
        border={`1px solid ${tokens.colors.primary[60]}`}
      />
      <SearchField
        label="search"
        inputStyles={{
          border: `1px solid ${tokens.colors.primary[60]}`,
          backgroundColor: tokens.colors.primary[10],
        }}
      />
    </>
  );
};