AutoSuggestBox New

The AutoSuggestBox component provides an input field with dynamic suggestions as users type. It enhances user experience by offering relevant suggestions, improving efficiency in form inputs and searches.

Usage

<script>
	import { AutoSuggestBox } from 'fluentui-svelte';
</script>

<AutoSuggestBox placeholder="Type a fruit...">
	<AutoSuggestBoxOption index={0} value="Apple">Apple</AutoSuggestBoxOption>
	<AutoSuggestBoxOption index={1} value="Banana">Banana</AutoSuggestBoxOption>
	<AutoSuggestBoxOption index={2} value="Cherry">Cherry</AutoSuggestBoxOption>
</AutoSuggestBox>

Suggestions are provided as AutoSuggestBoxOption a children of the AutoSuggestBox. As the user types, matching options will be shown.

Keyboard Navigation

Users can navigate through suggestions using the Up and Down arrow keys. Pressing Enter selects the highlighted suggestion.

Shape

Set shape to rounded (default), square, or circular.

View Code

<script>
  import { AutoSuggestBox } from 'fluentui-svelte';
</script>

<AutoSuggestBox shape="rounded" aria-label="rounded" placeholder="rounded" />
<AutoSuggestBox shape="square" aria-label="square" placeholder="square" />
<AutoSuggestBox shape="circular" aria-label="circular" placeholder="circular" />

Open on focus

Use the openOnFocus prop to show suggestions as soon as the text box receives focus, before anything is typed.

View Code

<AutoSuggestBox openOnFocus placeholder="Choose a fruit...">
  {#each fruits as fruit, index (fruit.id)}
    <AutoSuggestBoxOption {index} id={fruit.id} value={fruit.name}>
      {fruit.name}
    </AutoSuggestBoxOption>
  {/each}
</AutoSuggestBox>

Virtualization

Window large suggestion sets by connecting AutoSuggestBox to a virtual list through the virtualizer prop.

View Code

<script lang="ts">
  import SvelteVirtualList from '@humanspeak/svelte-virtual-list';

  let listRef = $state<ReturnType<typeof SvelteVirtualList> | null>(null);
</script>

<AutoSuggestBox
  placeholder="Type a name..."
  virtualizer={{
    size: people.length,
    scrollToTop: () => listRef?.scroll({ index: 0, align: 'top', smoothScroll: false }),
    scrollToBottom: () => listRef?.scroll({ index: people.length - 1, align: 'bottom', smoothScroll: false }),
    scrollToIndex: (index) => listRef?.scroll({ index, align: 'auto', smoothScroll: false })
  }}
>
  <SvelteVirtualList items={people} bind:this={listRef} defaultEstimatedItemHeight={30}>
    {#snippet renderItem(person, index)}
      <AutoSuggestBoxOption {index} id={person.id} value={person.name}>
        {person.name}
      </AutoSuggestBoxOption>
    {/snippet}
  </SvelteVirtualList>
</AutoSuggestBox>

Multiselect

Allow people to choose several suggestions and optionally show the selected values in the text box.

View Code

<script lang="ts">
  let selectedOptions = $state<{ id: string; value: string }[]>([]);
</script>

<AutoSuggestBox multiselect showTextualMultiselect bind:selectedOptions placeholder="Choose fruits...">
  {#each fruits as fruit, index (fruit.id)}
    <AutoSuggestBoxOption {index} id={fruit.id} value={fruit.name}>
      {fruit.name}
    </AutoSuggestBoxOption>
  {/each}
</AutoSuggestBox>

Virtualization with filtering

A virtualized list must filter its source data itself and report the filtered length through virtualizer.size.

View Code

<script lang="ts">
  import SvelteVirtualList from '@humanspeak/svelte-virtual-list';

  let items = $state.raw(people);
  let listRef = $state<ReturnType<typeof SvelteVirtualList> | null>(null);
</script>

<AutoSuggestBox
  placeholder="Type a name..."
  virtualizer={{
    size: items.length,
    scrollToTop: () => listRef?.scroll({ index: 0, align: 'top', smoothScroll: false }),
    scrollToBottom: () => {
      if (items.length) listRef?.scroll({ index: items.length - 1, align: 'bottom', smoothScroll: false });
    },
    scrollToIndex: (index) => listRef?.scroll({ index, align: 'auto', smoothScroll: false })
  }}
  textChanged={(_, value) => {
    const query = value.trim().toLowerCase();
    items = people.filter(({ name }) => name.toLowerCase().includes(query));
  }}
>
  <SvelteVirtualList {items} bind:this={listRef} defaultEstimatedItemHeight={30}>
    {#snippet renderItem(person, index)}
      <AutoSuggestBoxOption {index} id={person.id} value={person.name}>
        {person.name}
      </AutoSuggestBoxOption>
    {/snippet}
  </SvelteVirtualList>
</AutoSuggestBox>

Form Control Attributes

Attributes and events apply to the native form field; ref gives you access to it. For the container, use wrapperAttributes and wrapperRef.

Component Props

Name	Type	Default	Description
`wrapperRef` bindable	`HTMLDivElement` \| `null`		The DOM reference of the wrapper element.
`ref` bindable	`HTMLInputElement` \| `null`		The DOM reference of the text box element.
`value` bindable	`string`	`''`	The current text of the box.
`open` bindable	`boolean`	`false`	Controls the open state of the suggestion list.
`multiselect`	`boolean`		Lets more than one suggestion be chosen, and keeps the list open after each one.
`selectOnFocus`	`boolean`		Mirrors the suggestion under the cursor into the text box as it is walked over. Not supported together with `multiselect`.
`openOnFocus`	`boolean`	`false`	Opens the suggestion list as soon as the text box takes focus, instead of waiting for the first keystroke. Useful on touch devices, which have no arrow key to open the list with.
`showTextualMultiselect`	`boolean`		Lists every chosen suggestion in the text box, comma separated. Multiselect only.
`notFoundText`	`string`	`'No results found'`	The message shown in place of the list when nothing matches.
`selectedOptions` bindable	`{ id: string; value: string }[]`	`[]`	The suggestions currently chosen.
`suggestionChosen`	`(e: Event, selection: string) => void`		Called when a suggestion is chosen: by clicking it, by pressing Enter on it, or by walking onto it while `selectOnFocus` is set.
`querySubmitted`	`(e: MouseEvent` \| `KeyboardEvent, query: string) => void`		Called when Enter is pressed with no suggestion under the cursor, or when the search button is clicked. This is where a fresh set of suggestions is fetched. Enter then also submits the form with the typed text, unless the event is prevented.
`virtualizer`	`AutoSuggestVirtualizer`		Bridge to a windowed list, for suggestion sets too long to render whole.
`maxItemsInView`	`number`	`6`	How many suggestions are visible before the list scrolls.
`wrapperAttributes`	`HTMLAttributes`		The attributes to spread on the wrapper element.
`flyoutRef` bindable	`HTMLElement` \| `null`		The DOM reference of the flyout holding the suggestion list.
`flyoutProps`	`FlyoutProps`		The props to spread on the flyout.
`listViewRef` bindable	`HTMLUListElement` \| `null`		The DOM reference of the suggestion list.
`listViewProps`	`ListViewItemProps`		The props to spread on the suggestion list.
`shape`, `type`, `placeholder`, `hideActionButtons`, `textChanged`, `onClear` from `TextBoxProps`
`HTMLInputAttributes` without `value`, `type`, `role`, `size`, `placeholder`

AutoSuggestBoxOption Props

Name	Type	Description
`value`	`string`	The value reported to the box when the suggestion is chosen. Falls back to the id.
`text`	`string`	The text shown in the box once the suggestion is chosen. Falls back to `value`.
`id`	`string`	The id of the option element, referenced by the box through `aria-activedescendant`. Falls back to a generated id.
`ref` bindable	`HTMLLIElement` \| `null`	The DOM reference of the option element.
`disabled`	`boolean`	Takes the suggestion out of reach: it is shown, but the cursor steps over it.
`index`	`number`	Where the suggestion sits in the whole set. A windowed list needs the real index, not the position within the rendered slice.
`ListViewItemProps<'li'>` without `as`, `value`

Components

AutoSuggestBox New

Usage

Keyboard Navigation

Shape

Open on focus

Virtualization

Multiselect

Virtualization with filtering

Form Control Attributes

Component Props

AutoSuggestBoxOption Props