TagPicker AI

A TagPicker combines a text field and a dropdown, giving people a way to choose several options from a list or to enter their own choice. Every choice becomes a dismissible Tag shown in the control.

Usage

<script>
	import { TagPicker, TagPickerOption } from 'fluentui-svelte';

	const options = ['John Doe', 'Jane Doe', 'Max Mustermann'];

	let selectedOptions = $state([]);
</script>

<TagPicker
	bind:selectedOptions
	inputAttributes={{ 'aria-label': 'Select Employees' }}
	tagGroupProps={{ 'aria-label': 'Selected Employees' }}
>
	{#each options as option (option)}
		<TagPickerOption value={option}>{option}</TagPickerOption>
	{/each}
</TagPicker>

Keyboard navigation

Pressing Backspace in an empty input removes the last tag, so tell your users about it. ArrowDown and ArrowUp open the list and move through the options, Enter chooses the option under the cursor, and Escape or Tab closes the list. Home and End move the caret of the input.

Shape

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

Tags inherit shape. Use tagGroupProps.shape to override.

View Code

<script>
  import { TagPicker, TagPickerOption } from 'fluentui-svelte';
</script>

<TagPicker shape="rounded" aria-label="rounded" selectedOptions={['svelte']}>
  <TagPickerOption value="svelte">Svelte</TagPickerOption>
</TagPicker>
<TagPicker shape="square" aria-label="square" selectedOptions={['svelte']}>
  <TagPickerOption value="svelte">Svelte</TagPickerOption>
</TagPicker>
<TagPicker shape="circular" aria-label="circular" selectedOptions={['svelte']}>
  <TagPickerOption value="svelte">Svelte</TagPickerOption>
</TagPicker>
<TagPicker
  shape="square"
  tagGroupProps={{ shape: 'circular' }}
  aria-label="square with circular tags"
  selectedOptions={['svelte']}
>
  <TagPickerOption value="svelte">Svelte</TagPickerOption>
</TagPicker>

Default

Bind selectedOptions to the values of the chosen options, and pass the TagPickerOption elements as children. The tag snippet renders the tag of a chosen option, here with an Avatar as its media. Render a Tag with the given value.

View Code

<script>
  let selectedOptions = $state([]);
</script>

{#snippet tag({ value, text })}
  {#snippet media()}
    <Avatar aria-hidden="true" shape="rounded" name={text} size={16} color="colorful" />
  {/snippet}
  <Tag shape="rounded" {value} {media} title={text}>{text}</Tag>
{/snippet}

<TagPicker
  bind:selectedOptions
  {tag}
  inputAttributes={{ 'aria-label': 'Select Employees' }}
  tagGroupProps={{ 'aria-label': 'Selected Employees' }}
>
  {#each options as option (option)}
    <TagPickerOption value={option}>
      <Avatar aria-hidden="true" shape="rounded" name={option} size={20} color="colorful" />
      {option}
    </TagPickerOption>
  {/each}
</TagPicker>

Button

Pass readonly through inputAttributes to make the input read only and use the TagPicker as a button that opens the list.

View Code

<TagPicker
  bind:selectedOptions
  placeholder="Select employees"
  inputAttributes={{ 'aria-label': 'Select Employees', readonly: true }}
>
  {#each options as option (option)}
    <TagPickerOption value={option}>{option}</TagPickerOption>
  {/each}
</TagPicker>

Disabled

A disabled TagPicker cannot be opened, typed in or changed, and its tags cannot be dismissed.

View Code

<TagPicker disabled selectedOptions={[options[0]]} inputAttributes={{ 'aria-label': 'Select Employees' }}>
  {#each options as option (option)}
    <TagPickerOption value={option}>{option}</TagPickerOption>
  {/each}
</TagPicker>

Expand icon

Replace the dropdown arrow with expandIcon, a component or a snippet, or remove it by passing null.

View Code

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

<!-- A custom icon -->
<TagPicker bind:selectedOptions expandIcon={ArrowDownFilled} inputAttributes={{ 'aria-label': 'Select Employees' }}>
  ...
</TagPicker>

<!-- No icon -->
<TagPicker bind:selectedOptions expandIcon={null} inputAttributes={{ 'aria-label': 'Select Employees' }}>
  ...
</TagPicker>

Filtering

The options are filtered as the user types: an option stays when its text contains what was typed, ignoring case. The first match is highlighted so that Enter chooses it, and notFoundText is shown when no option is left.

View Code

<TagPicker
  bind:selectedOptions
  notFoundText="We couldn't find any matches"
  inputAttributes={{ 'aria-label': 'Select Employees' }}
>
  {#each options as option (option)}
    <TagPickerOption value={option}>{option}</TagPickerOption>
  {/each}
</TagPicker>

Grouped

Group options with TagPickerOptionGroup. A group with no option left on screen hides itself.

View Code

<TagPicker bind:selectedOptions inputAttributes={{ 'aria-label': 'Select Employees' }}>
  <TagPickerOptionGroup label="Managers">
    {#each managers as option (option)}
      <TagPickerOption value={option}>{option}</TagPickerOption>
    {/each}
  </TagPickerOptionGroup>
  <TagPickerOptionGroup label="Developers">
    {#each devs as option (option)}
      <TagPickerOption value={option}>{option}</TagPickerOption>
    {/each}
  </TagPickerOptionGroup>
</TagPicker>

Leave out the options to get a TagPicker without a list, to let users enter their own tags. Bind value and add the tag in querySubmitted, called when Enter is pressed with text in the input.

View Code

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

<!-- Without children there is no list: Enter hands the text to querySubmitted -->
<TagPicker
  bind:selectedOptions
  bind:value
  placeholder="Type and press Enter"
  inputAttributes={{ 'aria-label': 'Add Employees' }}
  querySubmitted={(e, query) => {
    if (!selectedOptions.includes(query)) selectedOptions = [...selectedOptions, query];
    value = '';
  }}
/>

Secondary action

Add a button next to the dropdown arrow with the secondaryAction snippet.

View Code

{#snippet allClear()}
  <Button appearance="subtle" onclick={() => (selectedOptions = [])}>All Clear</Button>
{/snippet}

<TagPicker bind:selectedOptions secondaryAction={allClear} inputAttributes={{ 'aria-label': 'Select Employees' }}>
  {#each options as option (option)}
    <TagPickerOption value={option}>{option}</TagPickerOption>
  {/each}
</TagPicker>

Single select

With single a new choice replaces the current tag and closes the list.

View Code

<TagPicker single bind:selectedOptions inputAttributes={{ 'aria-label': 'Select Employee' }}>
  {#each options as option (option)}
    <TagPickerOption value={option}>{option}</TagPickerOption>
  {/each}
</TagPicker>

Size

A TagPicker is medium by default, or large or extra-large. The size of the control also picks the size of its tags.

View Code

{#each ['medium', 'large', 'extra-large'] as size}
  <TagPicker {size} selectedOptions={[options[0]]} inputAttributes={{ 'aria-label': size }}>
    {#each options as option (option)}
      <TagPickerOption value={option}>{option}</TagPickerOption>
    {/each}
  </TagPicker>
{/each}

Truncated text

A tag that is wider than the control, or than its own max-width, shortens its text with an ellipsis. Give the tag a title so the full text stays reachable, and truncate the text of the options yourself.

View Code

{#snippet tag({ value, text })}
  <Tag {value} title={text} style="max-width: 100px;">{text}</Tag>
{/snippet}

<TagPicker bind:selectedOptions {tag} inputAttributes={{ 'aria-label': 'Select Employees' }}>
  {#each [...longOptions, ...options] as option (option)}
    <TagPickerOption value={option}>
      <span style="overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0;">{option}</span>
    </TagPickerOption>
  {/each}
</TagPicker>

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 (TagPicker)

Name	Type	Default	Description
`shape`	`'circular'` \| `'rounded'` \| `'square'`	`'rounded'`	Shape of the field and the default shape of its selected tags.
`wrapperRef` bindable	`HTMLDivElement` \| `null`		The DOM reference of the wrapper element.
`ref` bindable	`HTMLSelectElement` \| `null`		The DOM reference of the native multiple select that holds the selected options. The other attributes of the picker are applied to it.
`inputRef` bindable	`HTMLInputElement` \| `null`		The DOM reference of the text input.
`inputAttributes`	`HTMLInputAttributes`		The attributes to spread on the text input.
`selectedOptions` bindable	`string[]`	`[]`	The values of the chosen options, shown as tags in the control. A value no option has is shown as it is.
`value` bindable	`string`	`''`	The text typed in the input. It filters the options, and is cleared when one is chosen.
`open` bindable	`boolean`	`false`	Controls the open state of the option list.
`single`	`boolean`		Limits the picker to one tag: choosing an option replaces the current one and closes the list.
`disabled`	`boolean`		Disables the user interaction: the input, the tags and the list.
`size`	`'medium'` \| `'large'` \| `'extra-large'`	`'medium'`	The size of the control. It also picks the size of the tags.
`placeholder`	`string`		The placeholder text of the input.
`notFoundText`	`string`	`'No options available'`	The message shown in place of the list when there is no option left to choose.
`expandIcon`	`Snippet` \| `Component` \| `null`	`ChevronDownRegular`	The dropdown arrow. Pass `null` to remove it.
`secondaryAction`	`Snippet`		A button-like element rendered at the end of the control, before the dropdown arrow.
`tag`	`Snippet<[{ value: string; text: string }]>`		Renders the tag of a chosen option, to give it media or custom text. Falls back to a plain tag. Render a `Tag` with the given `value`.
`tagGroupProps`	`TagGroupProps`		The props to spread on the group holding the tags. Override `shape` here to give the tags a different shape from the field. This is where its `aria-label` goes, `'Selected options'` by default.
`wrapperAttributes`	`HTMLAttributes`		The attributes to spread on the wrapper element.
`onSelectionChange`	`(e: Event, selectedOptions: string[]) => void`		Called when an option is chosen, or a tag is removed.
`querySubmitted`	`(e: KeyboardEvent, query: string) => void`		Called when Enter is pressed with text in the input and no option under the cursor. This is where a free-form tag is added.
`children`	`Snippet`		The options. Leave it out to get a picker without a list.
`NativeFieldAttributes<Omit<HTMLSelectAttributes, 'value'` \| `'multiple'` \| `'size'` \| `'disabled'` \| `'children'>>`

Component Props (TagPickerOption)

Name	Type	Description
`value`	`string`	The value added to `selectedOptions` when the option is chosen.
`text`	`string`	The text the option is filtered by, and the text of its tag. Falls back to `value`.
`id`	`string`	The id of the option element, referenced by the input through `aria-activedescendant`. Falls back to a generated id.
`ref` bindable	`HTMLLIElement` \| `null`	The DOM reference of the option element.
`disabled`	`boolean`	Takes the option out of reach: it is shown, but the cursor steps over it.
`ListViewItemProps<'li'>` without `as`, `value`, `onAction`, `checkmark`

Component Props (TagPickerOptionGroup)

Name	Type	Description
`label`	`string`	The label of the group.
`ref` bindable	`HTMLUListElement` \| `null`	The DOM reference of the group element.
`children`	`Snippet`	The options of the group.
`wrapperAttributes`	`HTMLAttributes`	The attributes to spread on the wrapper element.
`wrapperRef` bindable	`HTMLLIElement` \| `null`	The DOM reference of the wrapper element.
`HTMLAttributes<HTMLUListElement>` without `children`

Components

TagPicker AI

Usage

Keyboard navigation

Shape

Default

Button

Disabled

Expand icon

Filtering

Grouped

No popover

Secondary action

Single select

Size

Truncated text

Form Control Attributes

Component Props (TagPicker)

Component Props (TagPickerOption)

Component Props (TagPickerOptionGroup)