Autocomplete

yarn add @clayui/autocomplete

React Component
CSS / Markup

Stable3.0.3

An autocomplete text field is an input that offers the user text suggestions while they type.

Loading state
Data from outside
API

Introduction

Take a look at our Storybook for more information about this component.

Check the Lexicon Autocomplete Pattern for a more in-depth look at the motivations and proper usage of this component.

Autocomplete provides the necessary components for you to compose with the other components, by itself it does not do much, you need to use the <ClayDropDown /> along with <Autocomplete.DropDown /> and <Autocomplete.Item /> to create the suggestions.

<ClayAutocomplete.DropDown>
	<ClayDropDown.ItemList>
		<ClayAutocomplete.Item match="cl" value="clay" />
	</ClayDropDown.ItemList>
</ClayAutocomplete.DropDown>

If you already have the raw data, it is becomes simpler to create an autocomplete but it is important that you create a filter for your data according to the value entered in the input element.

<ClayAutocomplete>
	<ClayAutocomplete.Input
		onChange={event => setValue(event.target.value)}
		value={value}
	/>
	<ClayAutocomplete.DropDown active={showDropDown}>
		<ClayDropDown.ItemList>
			{resourceFiltered.map(item => (
				<ClayAutocomplete.Item key={item} match={value} value={item} />
			))}
		</ClayDropDown.ItemList>
	</ClayAutocomplete.DropDown>
</ClayAutocomplete>

Loading state

<ClayAutocomplete.LoadingIndicator /> is used for providing feedback that data is loading in the suggestion box, it communicates with <ClayAutocomplete.Input /> so that the markup can adjust.

WarningAdd this when your suggestion data is coming from a data provider.

import React, {useState} from 'react';
import ClayAutocomplete from '@clayui/autocomplete';

import React, {useState} from 'react';
import ClayAutocomplete from '@clayui/autocomplete';

const Component = () => {
  const [loading] = useState(true);
  const [value, setValue] = useState("");

  return (
    <ClayAutocomplete>
      <ClayAutocomplete.Input
        onChange={event => setValue(event.target.value)}
        value={value}
      />
      {loading && <ClayAutocomplete.LoadingIndicator />}
    </ClayAutocomplete>
  );
};

render(<Component />);

const Component = () => {
  const [loading] = useState(true);
  const [value, setValue] = useState("");
  return (
    <ClayAutocomplete>
      <ClayAutocomplete.Input
        onChange={event => setValue(event.target.value)}
        value={value}
      />
      {loading && <ClayAutocomplete.LoadingIndicator />}
    </ClayAutocomplete>
  );
};
render(<Component />);

Data from outside

For cases where you do not have all the data in the client and need to pass the value for the filter to the backend, use the <ClayDataProvider /> component or useResource hook for this.

import React, {useState} from 'react';
import ClayAutocomplete from '@clayui/autocomplete';
import {useResource} from '@clayui/data-provider';
import ClayDropDown from '@clayui/drop-down';

import React, {useState} from 'react';
import ClayAutocomplete from '@clayui/autocomplete';
import {useResource} from '@clayui/data-provider';
import ClayDropDown from '@clayui/drop-down';

const Component = () => {
  const [value, setValue] = useState("");
  const [networkStatus, setNetworkStatus] = useState(4);
  const { resource } = useResource({
    fetchPolicy: "cache-first",
    link: "https://rickandmortyapi.com/api/character/",
    onNetworkStatusChange: setNetworkStatus,
    variables: { name: value }
  });

  const initialLoading = networkStatus === 1;
  const loading = networkStatus < 4;
  const error = networkStatus === 5;

  return (
    <ClayAutocomplete>
      <ClayAutocomplete.Input
        onChange={event => setValue(event.target.value)}
        placeholder="Type here"
        value={value}
      />
      <ClayAutocomplete.DropDown
        active={(!!resource && !!value) || initialLoading}
      >
        <ClayDropDown.ItemList>
          {(error || (resource && resource.error)) && (
            <ClayDropDown.Item className="disabled">
              {"No Results Found"}
            </ClayDropDown.Item>
          )}
          {!error &&
            resource &&
            resource.results &&
            resource.results.map(item => (
              <ClayAutocomplete.Item
                key={item.id}
                match={value}
                value={item.name}
              />
            ))}
        </ClayDropDown.ItemList>
      </ClayAutocomplete.DropDown>
      {loading && <ClayAutocomplete.LoadingIndicator />}
    </ClayAutocomplete>
  );
};

render(<Component />);

const Component = () => {
  const [value, setValue] = useState("");
  const [networkStatus, setNetworkStatus] = useState(4);
  const { resource } = useResource({
    fetchPolicy: "cache-first",
    link: "https://rickandmortyapi.com/api/character/",
    onNetworkStatusChange: setNetworkStatus,
    variables: { name: value }
  });
  const initialLoading = networkStatus === 1;
  const loading = networkStatus < 4;
  const error = networkStatus === 5;
  return (
    <ClayAutocomplete>
      <ClayAutocomplete.Input
        onChange={event => setValue(event.target.value)}
        placeholder="Type here"
        value={value}
      />
      <ClayAutocomplete.DropDown
        active={(!!resource && !!value) || initialLoading}
      >
        <ClayDropDown.ItemList>
          {(error || (resource && resource.error)) && (
            <ClayDropDown.Item className="disabled">
              {"No Results Found"}
            </ClayDropDown.Item>
          )}
          {!error &&
            resource &&
            resource.results &&
            resource.results.map(item => (
              <ClayAutocomplete.Item
                key={item.id}
                match={value}
                value={item.name}
              />
            ))}
        </ClayDropDown.ItemList>
      </ClayAutocomplete.DropDown>
      {loading && <ClayAutocomplete.LoadingIndicator />}
    </ClayAutocomplete>
  );
};
render(<Component />);

API

Autocomplete

Property	Type	Required	Default	Description
component	React.ForwardRefExoticComponent<any>		React.forwardRef< HTMLDivElement, React.HTMLAttributes<HTMLDivElement> >(({children, ...otherProps}, ref) => ( <ClayInput.Group {...otherProps} ref={ref}> <ClayInput.GroupItem>{children}</ClayInput.GroupItem> </ClayInput.Group> ))	Div component to render. It can be a one component that will replace the markup.

Property	Type	Default	Description
alignElementRef	React.RefObject<HTMLElement>		HTML element that the menu should be aligned to
active	boolean	false	Flag to indicate if menu is showing or not.
onSetActive	(val: boolean) => void	() => {}	Callback function for when active state changes.

Autocomplete.Input

Extends from `ClayForm.Input`

Autocomplete.Item

ClayAutocomplete.Item is a wrapper around ClayDropDown.Item but also underlines the bold characters that are matched. Feel free to create your own match rule using ClayDropDown.Item's API.

Property	Type	Required	Default	Description
innerRef	React.Ref<HTMLAnchorElement>
match	string		''	Match is the string that will be compared with value.
value	string	true		Value is the string that will be compared to the characters of the match property.

Autocomplete.LoadingIndicator

Property	Type	Required	Default	Description
component	React.ComponentType<any>		({children, ...otherProps}) => ( <ClayInput.GroupInsetItem {...otherProps} after> <span className="inline-item inline-item-middle">{children}</span> </ClayInput.GroupInsetItem> )	Div component to render. It can be a one component that will replace the markup.

An autocomplete text field is an input that offers the user text suggestions while they type.

Example
Search Field
Loading

Check the Lexicon Autocomplete and Search Field Pattern for a more in-depth look at the motivations and proper usage of this component.

Example

Add the class .autocomplete-dropdown-menu to dropdown-menu to size the Dropdown Menu according to Lexicon Design specifications.

This requires external javascript to populate and show/hide the .dropdown-menu.

Name

You can use a comma to enter tags. ReallySuperInsanelyJustIncrediblyLongAndTotallyNotPossibleWordButWeAreReallyTryingToCoverAllOurBasesHereJustInCaseSomeoneIsNutsAsPerUsual.

<div class="form-group">
	<label for="autocompleteName1">Name</label>
	<div class="input-group">
		<div class="input-group-item">
			<div class="dropdown">
				<input
					class="form-control"
					id="autocompleteName1"
					type="text"
					value="Rob"
				/>
				<ul class="autocomplete-dropdown-menu dropdown-menu show">
					<li>
						<a class="dropdown-item" href="#1"
							>Rob<strong>ert Downey Jr.</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>Rob<strong>ert Plant</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>Rob<strong>ert Baratheon</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>Rob<strong>ert De Niro</strong></a
						>
					</li>
				</ul>
			</div>
			<div class="form-feedback-group">
				<div class="form-text">
					You can use a comma to enter tags.
					ReallySuperInsanelyJustIncrediblyLongAndTotallyNotPossibleWordButWeAreReallyTryingToCoverAllOurBasesHereJustInCaseSomeoneIsNutsAsPerUsual.
				</div>
			</div>
		</div>
	</div>
</div>

Search Field

Marketplace

<div class="form-group">
	<label for="autocompleteMarketplace1">Marketplace</label>
	<div class="input-group">
		<div class="input-group-item">
			<div class="dropdown">
				<input
					class="form-control input-group-inset input-group-inset-after"
					id="autocompleteMarketplace1"
					placeholder="Search for..."
					type="text"
					value="ele"
				/>
				<span
					class="input-group-inset-item input-group-inset-item-after"
				>
					<button class="btn btn-unstyled" type="submit">
						<svg
							class="lexicon-icon lexicon-icon-search"
							focusable="false"
							role="presentation"
						>
							<use href="/images/icons/icons.svg#search" />
						</svg>
					</button>
					<button class="btn btn-unstyled" type="button">
						<svg
							class="lexicon-icon lexicon-icon-times"
							focusable="false"
							role="presentation"
						>
							<use href="/images/icons/icons.svg#times" />
						</svg>
					</button>
				</span>
				<ul class="autocomplete-dropdown-menu dropdown-menu show">
					<li>
						<a class="dropdown-item" href="#1"
							>ele<strong>ctric toothbrush</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>ele<strong>ctric kettle</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>ele<strong>ctric razor</strong></a
						>
					</li>
					<li>
						<a class="dropdown-item" href="#1"
							>ele<strong>ctrodes for tents</strong></a
						>
					</li>
				</ul>
			</div>
		</div>
	</div>
</div>

Loading

Marketplace

<div class="form-group">
	<label for="autocompleteMarketplace2">Marketplace</label>
	<div class="input-group">
		<div class="input-group-item">
			<div class="dropdown">
				<input
					class="form-control input-group-inset input-group-inset-after"
					id="autocompleteMarketplace2"
					type="text"
					value="H"
				/>
				<span
					class="input-group-inset-item input-group-inset-item-after"
				>
					<span class="inline-item inline-item-middle">
						<span
							class="loading-animation"
							role="presentation"
						></span>
					</span>
				</span>
				<ul class="autocomplete-dropdown-menu dropdown-menu show">
					<li>
						<span class="disabled dropdown-item">Loading...</span>
					</li>
				</ul>
			</div>
		</div>
	</div>
</div>

Table of contents

Introduction

Loading state

Data from outside

API

Autocomplete

Autocomplete.DropDown

Autocomplete.Input

Autocomplete.Item

Autocomplete.LoadingIndicator

Example

Search Field

Loading