AutoComplete

Autocomplete provides suggestions as users type in a text field. It helps users complete their input faster and reduces errors by offering valid options.

Examples

Basic autocomplete

Use autocomplete to help users find and select from a list of options.

Preview

Code

<script>
  import { AutoComplete } from 'svelte-polaris';
  import SearchIcon from "@shopify/polaris-icons/dist/svg/SearchIcon.svg?component";

  let selectedOptions = [];
  let inputValue = '';

  const options = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
    { value: 'date', label: 'Date' },
    { value: 'elderberry', label: 'Elderberry' },
    { value: 'fig', label: 'Fig' },
    { value: 'grape', label: 'Grape' }
  ];

  function updateText(value) {
    inputValue = value;
  }

  function updateSelection(selected) {
    selectedOptions = selected;
  }
</script>

{#snippet textField()}
    <AutoComplete.TextField
        onChange={updateText}
        label="Tags"
        value={inputValue}
        prefix={SearchIcon}
        placeholder="Search"
        autoComplete="off"
    />
{/snippet}

<AutoComplete
    {options}
    selected={selectedOptions}
    onSelect={updateSelection}
    {textField}
/>

Autocomplete with multiple selection

Allow users to select multiple options from the autocomplete list.

Preview

Code

<script lang="ts">
  import { AutoComplete, Tag, InlineStack } from "svelte-polaris";
  import SearchIcon from "@shopify/polaris-icons/dist/svg/SearchIcon.svg?component";

  let selectedOptions: string[] = [];
  let inputValue = "";

  type Section = {
    title: string;
    options: {
      value: string;
      label: string;
    }[];
  };

  const options: Section[] = [
    {
      title: "Frequently used",
      options: [
        { value: "ups", label: "UPS" },
        { value: "usps", label: "USPS" },
      ],
    },
    {
      title: "All carriers",
      options: [
        { value: "dhl", label: "DHL Express" },
        { value: "canada_post", label: "Canada Post" },
      ],
    },
  ];

  function updateText(value: string) {
    inputValue = value;
  }

  function updateSelection(selected: string[]) {
    selectedOptions = selected;
  }

  function removeTag(option: string) {
    selectedOptions = selectedOptions.filter(
      (selectedOption) => selectedOption !== option,
    );
  }
</script>

{#snippet textField()}
  <AutoComplete.TextField
    onChange={updateText}
    label="Programming languages"
    value={inputValue}
    prefix={SearchIcon}
    placeholder="Search languages..."
    autoComplete="off"
  />
{/snippet}

<AutoComplete
  allowMultiple
  {options}
  selected={selectedOptions}
  onSelect={updateSelection}
  {textField}
/>

{#if selectedOptions.length > 0}
  <div style="margin-top: 1rem;">
    <InlineStack gap="200">
      {#each selectedOptions as option}
        <Tag onRemove={() => removeTag(option)}>
          {option}
        </Tag>
      {/each}
    </InlineStack>
  </div>
{/if}

Autocomplete with loading state

Show a loading state while fetching autocomplete options.

Preview

Code

<script lang="ts">
    import SearchIcon from "@shopify/polaris-icons/dist/svg/SearchIcon.svg?component";
    import { AutoComplete } from "svelte-polaris";

    let selectedOptions: string[] = [];
    let inputValue = "";

    const options = [
        { value: "apple", label: "Apple" },
        { value: "banana", label: "Banana" },
        { value: "cherry", label: "Cherry" },
        { value: "date", label: "Date" },
        { value: "elderberry", label: "Elderberry" },
        { value: "fig", label: "Fig" },
        { value: "grape", label: "Grape" },
    ];

    function updateText(value: string) {
        inputValue = value;
    }

    function updateSelection(selected: string[]) {
        selectedOptions = selected;
    }
</script>

{#snippet textField()}
    <AutoComplete.TextField
        onChange={updateText}
        label="Tags"
        value={inputValue}
        prefix={SearchIcon}
        placeholder="Search"
        autoComplete="off"
    />
{/snippet}

<AutoComplete
    {options}
    loading={true}
    selected={selectedOptions}
    onSelect={updateSelection}
    {textField}
/>

Autocomplete with empty state

Provide helpful messaging when no options are available.

Preview

Code

<script lang="ts">
    import { BlockStack, Icon, Text, AutoComplete } from 'svelte-polaris';
    import SearchIcon from "@shopify/polaris-icons/dist/svg/SearchIcon.svg?component";

    let selectedOptions: string[] = [];
    let inputValue = "";

    const options:[] = [
    ];

    function updateText(value: string) {
        inputValue = value;
    }

    function updateSelection(selected: string[]) {
        selectedOptions = selected;
    }
</script>

{#snippet emptyState()}
    <BlockStack gap="200">
        <Icon source={SearchIcon} />
        <Text variant="headingMd" as="h2">No colors found</Text>
        <Text variant="bodyMd" as="p">Try searching for red, blue, or green</Text>
    </BlockStack>
{/snippet}

{#snippet textField()}
    <AutoComplete.TextField
        onChange={updateText}
        label="Tags"
        value={inputValue}
        prefix={SearchIcon}
        placeholder="Search"
        autoComplete="off"
    />
{/snippet}

<AutoComplete
    {options}
    selected={selectedOptions}
    onSelect={updateSelection}
    {textField}
    {emptyState}
/>

Autocomplete with action

Add an action to create new options when none exist.

Preview

Code

<script lang="ts">
    import PlusCircleIcon from "@shopify/polaris-icons/dist/svg/PlusCircleIcon.svg?component";
    import SearchIcon from "@shopify/polaris-icons/dist/svg/SearchIcon.svg?component";
    import { AutoComplete } from "svelte-polaris";

    let selectedOptions: string[] = [];
    let inputValue = "";

    const options = [
        { value: "apple", label: "Apple" },
        { value: "banana", label: "Banana" },
        { value: "cherry", label: "Cherry" },
        { value: "date", label: "Date" },
        { value: "elderberry", label: "Elderberry" },
        { value: "fig", label: "Fig" },
        { value: "grape", label: "Grape" },
    ];

    function updateText(value: string) {
        inputValue = value;
    }

    function updateSelection(selected: string[]) {
        selectedOptions = selected;
    }
</script>

{#snippet textField()}
    <AutoComplete.TextField
        onChange={updateText}
        label="Tags"
        value={inputValue}
        prefix={SearchIcon}
        placeholder="Search"
        autoComplete="off"
    />
{/snippet}

<AutoComplete
    {options}
    selected={selectedOptions}
    onSelect={updateSelection}
    {textField}
    actionBefore={{
        accessibilityLabel: "Action label",
        badge: {
            tone: "new",
            content: "New!",
        },
        content: "Action with long name",
        ellipsis: true,
        helpText: "Help text",
        icon: PlusCircleIcon,
        onAction: () => {
            console.log("actionBefore clicked!");
        },
    }}
/>

Props

AutoComplete props

Prop	Type	Default	Description
options	AutocompleteOption[]	[]	Collection of options to display
selected	AutocompleteOption[]	[]	Currently selected options
onSelect	(selected: AutocompleteOption[]) => void		Callback when selection changes
textField	TextFieldProps		Props for the text input field
allowMultiple	boolean	false	Allow multiple selections
loading	boolean	false	Show loading state
willLoadMoreResults	boolean	false	Whether more results will load
emptyState	EmptyStateProps		Empty state configuration
actionBefore	ActionDescriptor		Action to show before options
preferredPosition	'above' | 'below' | 'mostSpace'	'below'	Preferred popover position
listboxId	string		ID for the listbox

AutocompleteOption props

Prop	Type	Default	Description
value	string		Unique value for the option
label	string		Display text for the option
disabled	boolean	false	Whether the option is disabled

TextFieldProps (for textField prop)

Prop	Type	Default	Description
value	string		Current input value
onChange	(value: string) => void		Callback when input changes
label	string		Label for the input field
placeholder	string		Placeholder text
autoComplete	string		HTML autocomplete attribute
disabled	boolean	false	Whether the input is disabled
error	string | boolean		Error message or state
helpText	string		Help text below the input

Best practices

• Use autocomplete to help users find options quickly in large datasets
• Provide clear, descriptive labels for options
• Show loading states when fetching options asynchronously
• Implement proper filtering to show relevant results
• Use empty states to guide users when no results are found
• Allow creation of new options when appropriate
• Consider performance with large option lists
• Provide keyboard navigation support
• Use multiple selection sparingly and show selected items clearly

Accessibility

• Autocomplete automatically manages ARIA attributes for screen readers
• Keyboard navigation is built-in (arrow keys, Enter, Escape)
• Selected options are announced to assistive technologies
• Loading states are properly communicated
• Focus management is handled automatically
• Use descriptive labels and help text for better context

Related components

• Use Combobox for single-selection dropdowns
• Use Select for simple option selection
• Use TextField for basic text input
• Use Tag to display selected options