Forms

Autocomplete

Free-form text input with asynchronous suggestion hints rendered in a listbox popover.

import { Autocomplete } from '@lostgradient/cinder/autocomplete';
formautocomplete
01

Overview

Free-form text input with suggestion hints.

Usage

svelte 
<script lang="ts">
  import Autocomplete from '@lostgradient/cinder/autocomplete';

  const fruits = [
    { value: 'apple', label: 'Apple', description: 'Classic pie filling' },
    { value: 'apricot', label: 'Apricot', description: 'Stone fruit' },
    { value: 'banana', label: 'Banana', description: 'Tropical staple' },
    { value: 'blackberry', label: 'Blackberry', description: 'Late-summer berry' },
    { value: 'blueberry', label: 'Blueberry', description: 'Breakfast favorite' },
    { value: 'grapefruit', label: 'Grapefruit', description: 'Tart citrus' },
  ];

  let value = $state('');
</script>

<Autocomplete
  id="field"
  label="Favorite fruit"
  placeholder="Type a fruit"
  suggestionSource={(query: string) =>
    fruits.filter((fruit) => fruit.label?.toLowerCase().includes(query.toLowerCase()))}
  bind:value
/>
Live preview
02

When to use

Use when
  • Accepting arbitrary text while offering completions from a local or remote source.
  • Keeping the user's text as the committed value while suggestions remain optional hints.
Avoid when
  • Requiring the final value to come from a fixed option list — use combobox instead.
03

Examples

Async source

Remote-style source with a loading row and stale-request cancellation.

Basic autocomplete

Free-form text stays editable while the suggestion list offers completions.

Inside FormField

Uses FormField for the label, hint text, and required-state wiring.

04

Props

Props for autocomplete
NameTypeDefaultDescription
id text HTML id for the underlying input, used to associate the <label> and ARIA attributes.
value bindable text '' Bindable current text value of the input.
suggestionSource (query: string, context: AutocompleteSuggestionSourceContext, ) => AutocompleteSuggestion[]Promise<AutocompleteSuggestion[]>
label text Visible label text rendered above the input and linked via for/id.
description text Helper text rendered below the input and associated via aria-describedby.
error text Error message rendered below the input; also sets aria-invalid on the input.
minQueryLength number 1 Minimum number of characters the user must type before suggestions are requested. Default 1.
maxVisibleSuggestions number 50 Maximum number of suggestions rendered in the listbox at once. Default 50.
placeholder text Placeholder text shown inside the input when it is empty.
disabled boolean When true, disables the input and prevents interaction, matching the native disabled attribute.
required boolean Marks the input as required for form validation, matching the native required attribute.
readonly boolean false When true, the input value cannot be changed by the user, matching the native readonly attribute.
emptyMessage text 'No suggestions' Message shown in the listbox when the suggestion source returns no results. Default "No suggestions".
loadingMessage text 'Loading suggestions' Message shown in the listbox while the suggestion source is fetching results. Default "Loading suggestions".
onValueChange (value: string) => void
onComplete (suggestion: AutocompleteSuggestion) => void