TagPicker AI

Un TagPicker combina un campo de texto y un menú desplegable, y permite elegir varias opciones de una lista o escribir una propia. Cada elección se convierte en un Tag descartable que se muestra en el control.

Uso

<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>

Navegación con teclado

Pulsar Backspace en un input vacío elimina el último tag, así que avisa a tus usuarios. ArrowDown y ArrowUp abren la lista y recorren las opciones, Enter elige la opción bajo el cursor, y Escape o Tab cierran la lista. Home y End mueven el cursor de texto del input.

Forma

Usa shape: rounded (predeterminada), square o circular.

Los tags heredan shape. Usa tagGroupProps.shape para sobrescribirlo.

Ver Código

<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>

Por defecto

Enlaza selectedOptions con los valores de las opciones elegidas y pasa los elementos TagPickerOption como hijos. El snippet tag renderiza el tag de una opción elegida, aquí con un Avatar como media. Renderiza un Tag con el value recibido.

Ver Código

<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>

Botón

Pasa readonly mediante inputAttributes para que la entrada sea de solo lectura y el TagPicker funcione como un botón que abre la lista.

Ver Código

<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>

Deshabilitado

Un TagPicker deshabilitado no se puede abrir, escribir en él ni modificar, y sus tags no se pueden descartar.

Ver Código

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

Icono de expansión

Reemplaza la flecha del desplegable con expandIcon, un componente o un snippet, o quítala pasando null.

Ver Código

<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>

Filtrado

Las opciones se filtran mientras el usuario escribe: una opción permanece cuando su texto contiene lo escrito, sin distinguir mayúsculas. La primera coincidencia queda resaltada para que Enter la elija, y notFoundText se muestra cuando no queda ninguna opción.

Ver Código

<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>

Agrupado

Agrupa las opciones con TagPickerOptionGroup. Un grupo sin ninguna opción en pantalla se oculta solo.

Ver Código

<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>

Omite las opciones para obtener un TagPicker sin lista, y dejar que los usuarios escriban sus propios tags. Enlaza value y agrega el tag en querySubmitted, que se llama al pulsar Enter con texto en el input.

Ver Código

<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 = '';
  }}
/>

Acción secundaria

Agrega un botón junto a la flecha del desplegable con el snippet secondaryAction.

Ver Código

{#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>

Selección única

Con single, una nueva elección reemplaza el tag actual y cierra la lista.

Ver Código

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

Tamaño

Un TagPicker es medium por defecto, o large o extra-large. El tamaño del control también define el tamaño de sus tags.

Ver Código

{#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}

Texto truncado

Un tag más ancho que el control, o que su propio max-width, acorta su texto con puntos suspensivos. Dale un title al tag para que el texto completo siga disponible, y trunca tú mismo el texto de las opciones.

Ver Código

{#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>

Atributos de los controles de formulario

Los atributos y eventos se aplican al campo nativo del formulario; ref permite acceder a él. Para el contenedor, usa wrapperAttributes y wrapperRef.

Propiedades del componente (TagPicker)

Name	Type	Default	Description
`shape`	`'circular'` \| `'rounded'` \| `'square'`	`'rounded'`	Forma del campo y forma predeterminada de sus tags seleccionados.
`wrapperRef` bindable	`HTMLDivElement` \| `null`		La referencia DOM del elemento contenedor.
`ref` bindable	`HTMLSelectElement` \| `null`		La referencia DOM del select múltiple nativo que guarda las opciones seleccionadas. El resto de atributos del selector se aplican a él.
`inputRef` bindable	`HTMLInputElement` \| `null`		La referencia DOM del input de texto.
`inputAttributes`	`HTMLInputAttributes`		Los atributos que se aplican al input de texto.
`selectedOptions` bindable	`string[]`	`[]`	Los valores de las opciones elegidas, mostrados como tags en el control. Un valor que ninguna opción tiene se muestra tal cual.
`value` bindable	`string`	`''`	El texto escrito en el input. Filtra las opciones y se borra al elegir una.
`open` bindable	`boolean`	`false`	Controla el estado abierto de la lista de opciones.
`single`	`boolean`		Limita el picker a un solo tag: elegir una opción reemplaza el actual y cierra la lista.
`disabled`	`boolean`		Deshabilita la interacción del usuario: el input, los tags y la lista.
`size`	`'medium'` \| `'large'` \| `'extra-large'`	`'medium'`	El tamaño del control. También define el tamaño de los tags.
`placeholder`	`string`		El texto de marcador de posición del input.
`notFoundText`	`string`	`'No options available'`	El mensaje que se muestra en lugar de la lista cuando no queda ninguna opción por elegir.
`expandIcon`	`Snippet` \| `Component` \| `null`	`ChevronDownRegular`	La flecha del desplegable. Pasa `null` para quitarla.
`secondaryAction`	`Snippet`		Un elemento tipo botón que se muestra al final del control, antes de la flecha del desplegable.
`tag`	`Snippet<[{ value: string; text: string }]>`		Renderiza el tag de una opción elegida, para darle media o texto personalizado. Recurre a un tag simple. Renderiza un `Tag` con el `value` recibido.
`tagGroupProps`	`TagGroupProps`		Propiedades del `TagGroup` seleccionado. Sobrescribe aquí `shape` para dar a los tags una forma distinta de la del campo. Usa `aria-label` o `aria-labelledby` para nombrar el grupo.
`wrapperAttributes`	`HTMLAttributes`		Los atributos que se aplican al elemento wrapper.
`onSelectionChange`	`(e: Event, selectedOptions: string[]) => void`		Se llama cuando se elige una opción o se quita un tag.
`querySubmitted`	`(e: KeyboardEvent, query: string) => void`		Se llama cuando se pulsa Enter con texto en el input y sin ninguna opción bajo el cursor. Aquí se agrega un tag de texto libre.
`children`	`Snippet`		Las opciones. Omítelo para obtener un picker sin lista.
`NativeFieldAttributes<Omit<HTMLSelectAttributes, 'value'` \| `'multiple'` \| `'size'` \| `'disabled'` \| `'children'>>`

Propiedades del componente (TagPickerOption)

Name	Type	Description
`value`	`string`	El valor que se agrega a `selectedOptions` cuando se elige la opción.
`text`	`string`	El texto por el que se filtra la opción y el texto de su tag. Recurre a `value`.
`id`	`string`	El id del elemento de la opción, al que el input hace referencia mediante `aria-activedescendant`. Recurre a un id generado.
`ref` bindable	`HTMLLIElement` \| `null`	La referencia del DOM del elemento de la opción.
`disabled`	`boolean`	Deja la opción fuera de alcance: se muestra, pero el cursor la salta.
`ListViewItemProps<'li'>` without `as`, `value`, `onAction`, `checkmark`

Propiedades del componente (TagPickerOptionGroup)

Name	Type	Description
`label`	`string`	La etiqueta del grupo.
`ref` bindable	`HTMLUListElement` \| `null`	La referencia del DOM del elemento del grupo.
`children`	`Snippet`	Las opciones del grupo.
`wrapperAttributes`	`HTMLAttributes`	Los atributos que se aplican al elemento wrapper.
`wrapperRef` bindable	`HTMLLIElement` \| `null`	La referencia DOM del elemento contenedor.
`HTMLAttributes<HTMLUListElement>` without `children`

Componentes

TagPicker AI

Uso

Navegación con teclado

Forma

Por defecto

Botón

Deshabilitado

Icono de expansión

Filtrado

Agrupado

Sin popover

Acción secundaria

Selección única

Tamaño

Texto truncado

Atributos de los controles de formulario

Propiedades del componente (TagPicker)

Propiedades del componente (TagPickerOption)

Propiedades del componente (TagPickerOptionGroup)