AutoComplete
Suggest values while allowing free-text input.
Basic usage
Suggestions use case-insensitive substring matching by default, without restricting free text. onChange responds to typing and selection; onSelect only responds to choosing a suggestion. An option with disabled cannot be selected.
import { AutoComplete, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const options = [
{ value: 'Leaf Garden' },
{ value: 'Leaf Studio' },
{ value: 'Pine Forest' },
{ value: 'Archived Garden', disabled: true },
];
export function AutoCompleteBasic() {
const [value, setValue] = useState('');
const [selected, setSelected] = useState('');
return (
<Form layout="vertical">
<FormField label="Project name">
<AutoComplete
aria-label="Project name"
options={options}
placeholder="Type Leaf or enter any text"
value={value}
onChange={setValue}
onSelect={setSelected}
/>
</FormField>
<Flex direction="column" gap={8} role="status">
<Text tone="muted">Input: {value || 'Empty'}</Text>
<Text tone="muted">Last selection: {selected || 'None'}</Text>
</Flex>
</Form>
);
}
Focus or type to open suggestions. Use the arrow keys to highlight available options, Enter to select and Escape to close. Tab continues to the next control. Enter during IME composition does not select a suggestion.
Examples
Dynamic suggestions
onSearch receives typed text, and receives an empty string when cleared. It does not run on selection. When suggestions are generated by your application or returned by a server, set filterOption={false} to display them without local filtering.
import { AutoComplete, type AutoCompleteOption, Form, FormField } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function AutoCompleteSearch() {
const [options, setOptions] = useState<AutoCompleteOption[]>([]);
return (
<Form layout="vertical">
<FormField label="Email address">
<AutoComplete
aria-label="Email address"
placeholder="Enter an email prefix"
options={options}
allowClear
filterOption={false}
onSearch={(query) => {
const prefix = query.split('@')[0] ?? '';
setOptions(
prefix
? ['gmail.com', 'outlook.com', 'icloud.com'].map((domain) => ({
value: `${prefix}@${domain}`,
}))
: [],
);
}}
/>
</FormField>
</Form>
);
}
Grouped suggestions
Use a group label and its options to organize suggestions. Provide searchLabel for rich labels. Selecting a suggestion inserts its value, not its visible label.
import { AutoComplete, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
const options = [
{
label: 'Team',
options: [
{
value: 'alice@example.com',
label: (
<Flex gap={8} align="center">
<Text strong>Alice</Text>
<Text tone="muted">Design</Text>
</Flex>
),
searchLabel: 'Alice Design',
},
{
value: 'bob@example.com',
label: (
<Flex gap={8} align="center">
<Text strong>Bob</Text>
<Text tone="muted">Engineering</Text>
</Flex>
),
searchLabel: 'Bob Engineering',
},
],
},
];
export function Capabilities() {
return (
<Form layout="vertical">
<FormField label="Team email">
<AutoComplete
aria-label="Team email"
options={options}
placeholder="Search a name or role"
/>
</FormField>
</Form>
);
}
Loading and retry
This example simulates a failed load. Retrying performs an asynchronous local load and replaces the error with suggestions. For remote data, handle debouncing and response order in your application. When controlling open, update it in onOpenChange.
import { AutoComplete, type AutoCompleteOption, Button, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useRef, useState } from 'react';
export function AutoCompleteLoading() {
const [state, setState] = useState<'loading' | 'error' | 'ready'>('error');
const [options, setOptions] = useState<AutoCompleteOption[]>([]);
const [open, setOpen] = useState(false);
const input = useRef<HTMLInputElement>(null);
const retry = async () => {
setState('loading');
setOpen(true);
input.current?.focus();
await new Promise((resolve) => setTimeout(resolve, 800));
setOptions([{ value: 'Leaf Garden' }, { value: 'Leaf Studio' }]);
setState('ready');
};
return (
<Form layout="vertical">
<FormField label="Remote project">
<AutoComplete
ref={input}
aria-label="Remote project"
options={options}
filterOption={false}
open={open}
onOpenChange={setOpen}
loading={state === 'loading'}
errorContent={
state === 'error' ? (
<Flex direction="column" align="start" gap={8}>
<Text>Suggestions failed to load</Text>
<Button onClick={retry} size="sm">
Retry
</Button>
</Flex>
) : undefined
}
/>
</FormField>
<Text tone="muted" role="status">
{state === 'loading'
? 'Loading'
: state === 'error'
? 'Load failed'
: 'Loaded 2 suggestions'}
</Text>
<Flex>
<Button
disabled={state === 'loading'}
onClick={() => {
setOptions([]);
setState('error');
setOpen(true);
}}
>
Simulate failure
</Button>
</Flex>
</Form>
);
}
Disabled and read-only
disabled prevents interaction with the entire control. readOnly allows focus and copying but prevents editing, selection and clearing.
import { AutoComplete, Form, FormField } from '@ifhover/leaf-ui';
const options = [{ value: 'Leaf Garden' }, { value: 'Leaf Studio' }];
export function AutoCompleteStates() {
return (
<Form layout="vertical">
<FormField label="Disabled">
<AutoComplete aria-label="Disabled" options={options} defaultValue="Leaf Garden" disabled />
</FormField>
<FormField label="Read only">
<AutoComplete
aria-label="Read only"
options={options}
defaultValue="Leaf Garden"
readOnly
/>
</FormField>
</Form>
);
}
Native input attributes such as name, required and form are supported. Uncontrolled fields follow native form reset; reset controlled values in application state. Application labels and options are not translated automatically.
API
AutoComplete API
placeholder, name, required, form, maxLength and aria-* are forwarded to the input. className and style apply to the outer container.
AutoCompleteOption
AutoCompleteOptionGroup