SearchField

A search field allows a user to enter text with a keyboard into a single-line input form element, which then performs a search operation.

Install	`yarn add @diallink-corp/convergo-react-searchfield`
Version	4.1.2
Usage	import {SearchField} from '@diallink-corp/convergo-react-searchfield'

Usage

The SearchField supports an onSubmit prop to handle the submission of the search query. This is its default and intended behaviour, as it stops the backend from being queried on every keystroke and is more smooth than an onStopTyping prop.

function Example() {
  const [submittedText, setSubmittedText] = useState();

  return (
    <>
      <SearchField
        label="Search"
        placeholder="Enter user name"
        onSubmit={setSubmittedText}
      />
      <p>Searched text: {submittedText}</p>
    </>
  );
}

function Example() {
  const [submittedText, setSubmittedText] = useState();

  return (
    <>
      <SearchField
        label="Search"
        placeholder="Enter user name"
        onSubmit={setSubmittedText}
      />
      <p>Searched text: {submittedText}</p>
    </>
  );
}

function Example() {
  const [
    submittedText,
    setSubmittedText
  ] = useState();

  return (
    <>
      <SearchField
        label="Search"
        placeholder="Enter user name"
        onSubmit={setSubmittedText}
      />
      <p>
        Searched text:
        {' '}
        {submittedText}
      </p>
    </>
  );
}

Uncontrolled Value

By default, the SearchField component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<SearchField label="Email" defaultValue="alexander@diallink.com" />

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
/>

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [value, setValue] = useState('alexander@diallink.com');

  return (
    <div>
      <SearchField 
        label='Email' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [value, setValue] = useState(
    'alexander@diallink.com'
  );

  return (
    <div>
      <SearchField
        label="Email"
        value={value}
        onChange={setValue}
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'alexander@diallink.com'
  );

  return (
    <div>
      <SearchField
        label="Email"
        value={value}
        onChange={setValue}
      />

      <div>
        Value: {value}
      </div>
    </div>
  );
}

Labeling

A SearchField component should be labeled with a visual text through the label prop. If the SearchField does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<SearchField label='Email' />

<SearchField label='Email' />

<SearchField label="Email" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the SearchField component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<SearchField label='Email' labelPlacement='top end' />

<SearchField label='Email' labelPlacement='top end' />

<SearchField
  label="Email"
  labelPlacement="top end"
/>

Label Position

By default, the label of the SearchField component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<SearchField label='Email' labelPlacement='side end' />

<SearchField label='Email' labelPlacement='side end' />

<SearchField
  label="Email"
  labelPlacement="side end"
/>

Required

To indicate to the user that the SearchField is required you can use the isRequired prop.

<SearchField label='Email' isRequired />

<SearchField label='Email' isRequired />

<SearchField
  label="Email"
  isRequired
/>

Validation

The SearchField component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState('alexander@inperiu');

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail = emailRegExp.test(value);

  return (
    <SearchField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail && 'The email you entered is invalid.'}
    />
  );
}

function Example() {
  const [value, setValue] = useState('alexander@inperiu');

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail = emailRegExp.test(value);

  return (
    <SearchField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail &&
        'The email you entered is invalid.'}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'alexander@inperiu'
  );

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail =
    emailRegExp.test(
      value
    );

  return (
    <SearchField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail &&
        'The email you entered is invalid.'}
    />
  );
}

Description

To give further instructions or more verbose examples to the user about a SearchField you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<SearchField
  label="Search"
  description="An enumeration of the essential qualities of a thing or species"
/>

<SearchField
  label="Search"
  description="An enumeration of the essential qualities of a thing or species"
/>

<SearchField
  label="Search"
  description="An enumeration of the essential qualities of a thing or species"
/>

Placeholder

To give further instructions or examples to the user about a SearchField you can provide a placeholder prop.

<SearchField label="Email" placeholder="test@diallink.com" />

<SearchField
  label="Email"
  placeholder="test@diallink.com"
/>

<SearchField
  label="Email"
  placeholder="test@diallink.com"
/>

Contextual Help

To offer the user contextual help, the SearchField supports passing a contextualHelp prop, that accepts a ReactNode.

<SearchField 
  label='Email' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<SearchField
  label="Email"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<SearchField
  label="Email"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The SearchField component can be disabled via the isDisabled prop.

<SearchField label="Email" defaultValue="alexander@diallink.com" isDisabled />

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
  isDisabled
/>

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
  isDisabled
/>

Read Only

The SearchField component can be marked as read only via the isReadOnly prop.

<SearchField label="Email" defaultValue="alexander@diallink.com" isReadOnly />

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
  isReadOnly
/>

<SearchField
  label="Email"
  defaultValue="alexander@diallink.com"
  isReadOnly
/>

Icons

You can optionally add an icon to the SearchField component.

<SearchField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>

<SearchField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>

<SearchField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.