Autocomplete

yarn add @clayui/autocomplete

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

Stable3.1.12View in LexiconCHANGELOGstorybook demos

Table of contents

Composing

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.
Code Sample (expand to see it)

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.

    Code Sample (expand to see it)

    API

    Autocomplete

    PropertyTypeRequiredDefaultDescription
    component
    		React.ForwardRefExoticComponent<any>falseReact.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.

    Autocomplete.DropDown

    PropertyTypeRequiredDefaultDescription
    alignElementRef
    		React.RefObject<HTMLElement>falseHTML element that the menu should be aligned to
    active
    		booleanfalsefalseFlag to indicate if menu is showing or not.
    onSetActive
    		(val: boolean) => voidfalse() => {}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.

    PropertyTypeRequiredDefaultDescription
    innerRef
    		React.Ref<HTMLAnchorElement>false
    match
    		stringfalse''Match is the string that will be compared with value.
    value
    		stringtrueValue is the string that will be compared to the characters of the match property.

    Autocomplete.LoadingIndicator

    PropertyTypeRequiredDefaultDescription
    component
    		React.ComponentType<any>false({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.

    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.
    Code Sample (expand to see it) 
    <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

    Code Sample (expand to see it) 
    <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

    • Loading...
    Code Sample (expand to see it) 
    <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>

    How can this be improved? Create an issue!