Leaf UI
  • English

      • AutoComplete

      Suggest values while allowing free-text input.

      Examples

      Use options for suggestions and onChange for typed or selected text. onSelect fires only when choosing a suggestion; onSearch fires only for typing. Set filterOption=false for server-generated suggestions. Handle debouncing and request order in your application.

      Live previewInput and suggestions
      Input:Empty · Last selection:None
      basic.tsx
      import { AutoComplete } from '@sudden3/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 (
    <div className="leaf-demo-stack">
      <AutoComplete
        aria-label="Project name"
        placeholder="Type Leaf or enter any text"
        options={options}
        value={value}
        onChange={setValue}
        onSelect={setSelected}
      />
      <span className="leaf-demo-note">
        Input:{value || 'Empty'} · Last selection:{selected || 'None'}
      </span>
      <AutoComplete
        aria-label="Disabled suggestions"
        options={options}
        disabled
        defaultValue="Leaf Garden"
      />
    </div>
  );
}
      Live previewDynamic email suggestions
      Suggestions are generated as you type. You can also enter a complete address.
      search.tsx
      import { AutoComplete, type AutoCompleteOption } from '@sudden3/leaf-ui';
import { useState } from 'react';

export function AutoCompleteSearch() {
  const [options, setOptions] = useState<AutoCompleteOption[]>([]);
  return (
    <div className="leaf-demo-stack">
      <AutoComplete
        aria-label="Email address"
        placeholder="Enter the first part of an email"
        options={options}
        filterOption={false}
        onSearch={(query) => {
          const prefix = query.split('@')[0] ?? '';
          setOptions(
            prefix
              ? ['gmail.com', 'outlook.com', 'icloud.com'].map((domain) => ({
                  value: `${prefix}@${domain}`,
                }))
              : [],
          );
        }}
      />
      <span className="leaf-demo-note">
        Suggestions are generated as you type. You can also enter a complete address.
      </span>
    </div>
  );
}

      AutoComplete API

      PropertyTypeDefaultDescription
      optionsreadonly AutoCompleteOption[]RequiredSuggestion options
      value / defaultValuestring''Controlled text / uncontrolled initial text
      onChange(value: string) => void—Text after typing or selecting
      onSelect(value: string, option: AutoCompleteOption) => void—Runs when selecting a suggestion
      onSearch(query: string) => void—Runs on typing, not on selection
      filterOptionfalse | ((query: string, option: AutoCompleteOption) => boolean)Substring matchfalse disables local filtering; a function customizes matching
      size'sm' | 'md' | 'lg''md'Control size
      status'error' | 'warning'—Validation appearance
      disabled / readOnlybooleanfalseDisabled / read-only fields do not open suggestions
      refRef<HTMLInputElement>—DOM reference

      AutoCompleteOption

      PropertyTypeDefaultDescription
      valuestringRequiredUnique suggestion value; inserted into the input on selection
      labelstringvalueSuggestion label, also used by the default filter
      disabledbooleanfalseDisable the suggestion

      Types

      Import AutoCompleteProps to describe component props. Option types in the API table link to their detailed fields above.

      import type { AutoCompleteProps, AutoCompleteOption } from '@sudden3/leaf-ui';

      Forms and localization

      Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in FormField for labels, help and errors. ConfigProvider supplies regional themes and translated built-in UI. Application labels and options are your responsibility.