Tag

Un tag es una representación visual de un atributo, una persona o un recurso. Puede descartarse y, con la prop interactive, se convierte en un tag de interacción que tiene una acción primaria propia. Usa TagGroup para agrupar varios tags.

Uso

<script>
	import { Tag, TagGroup } from 'fluentui-svelte';
	import { CalendarMonthRegular } from 'fluentui-icons-svelte';
</script>

<Tag icon={CalendarMonthRegular}>Primary text</Tag>

<TagGroup aria-label="Fruits">
	<Tag interactive value="apple">Apple</Tag>
	<Tag interactive value="banana">Banana</Tag>
</TagGroup>

Apariencia

Usa la prop appearance para alternar entre filled, outline y brand. El valor por defecto es filled.

Ver Código

<Tag icon={CalendarMonthRegular} dismissible>filled</Tag>
<Tag appearance="outline" icon={CalendarMonthRegular} dismissible>outline</Tag>
<Tag appearance="brand" icon={CalendarMonthRegular} dismissible>brand</Tag>

Deshabilitado

Usa la prop disabled para indicar que no se puede interactuar con un tag. Se bloquea todo, incluido el control para descartarlo.

Ver Código

<Tag disabled secondaryText="appearance=filled" icon={CalendarMonthRegular} dismissible>Disabled</Tag>
<Tag disabled appearance="outline" secondaryText="appearance=outline" icon={CalendarMonthRegular} dismissible>Disabled</Tag>
<Tag disabled appearance="brand" secondaryText="appearance=brand" icon={CalendarMonthRegular} dismissible>Disabled</Tag>

Descartar

Un tag descartable muestra un ícono para descartar y puede recibir el foco: al hacer clic sobre él, o al presionar Enter, Espacio, Delete o Backspace, se descarta. El tag solo informa el descarte mediante onDismiss, así que elimínalo de tus datos. Asegúrate de gestionar correctamente el foco cuando se hayan descartado todos los tags.

Ver Código

<script>
  let dismissed = $state(false);
</script>

{#if !dismissed}
  <Tag dismissible onDismiss={() => (dismissed = true)}>Tag 1</Tag>
{/if}
<Button disabled={!dismissed} onclick={() => (dismissed = false)}>Reset the example</Button>

Nombre accesible

Informa a los lectores de pantalla sobre la acción de descartar. Puedes dejar que el ícono de descarte nombre el botón, con dismissLabel (Dismiss por defecto), o nombrar el propio tag con aria-label o aria-labelledby, y el ícono de descarte se oculta de las tecnologías de asistencia.

Ver Código

<!-- The dismiss icon names the button: "Tag 1 Remove" -->
<Tag dismissible dismissLabel="Remove">Tag 1</Tag>

<!-- Name the tag itself, and the dismiss icon is hidden from assistive technologies -->
<Tag dismissible aria-label="Remove Tag 2">Tag 2</Tag>

Interactivo (acción primaria)

Un tag interactivo tiene una acción primaria, el onclick del tag, y, cuando es descartable, un botón de descarte independiente. Úsalo para un tag que tenga una acción primaria, y un tag simple para uno que no la tenga. El botón de descarte se nombra a partir de ambos botones mediante aria-labelledby. Usa primaryProps y dismissProps para acceder a los botones: un id personalizado en el botón primario es seguido por el botón de descarte, y aria-label junto con aria-labelledby en undefined le da al botón de descarte un nombre que se basta por sí solo.

Ver Código

<script>
  let clicks = $state(0);
</script>

<Tag interactive dismissible onclick={() => clicks++}>Clicked {clicks} times</Tag>
<Tag interactive>Without dismiss</Tag>
<Tag interactive dismissible dismissLabel="Remove" dismissButtonAttributes={{ 'aria-label': 'Remove Tag', 'aria-labelledby': undefined }}>
  Own accessible name
</Tag>
<Button disabled={clicks === 0} onclick={() => (clicks = 0)}>Reset the example</Button>

Ícono

Usa la prop icon para renderizar un ícono personalizado antes del texto.

Ver Código

<Tag icon={CalendarMonthRegular}>Primary text</Tag>

Primary text

Media

Usa media para renderizar un elemento visual antes del texto, como un Avatar. El snippet recibe el shape actual; pásalo al avatar para mantener sus formas sincronizadas. Un componente visual recibe shape como prop.

Media o ícono, no ambos

No uses media junto con icon en el mismo tag.

Ver Código

<script lang="ts">
  import { Avatar, Tag, type TagMediaProps } from 'fluentui-svelte';
</script>

{#snippet avatar({ shape }: TagMediaProps)}
  <Avatar {shape} name="Katri Athokas" size={28} badge={{ status: 'busy' }} />
{/snippet}

<Tag media={avatar}>Primary text</Tag>

Primary text

Texto secundario

Usa la prop secondaryText para añadir una segunda línea de texto que describa o complemente el texto principal. Acepta un string o un snippet.

Ver Código

<Tag secondaryText="Secondary text">Primary text</Tag>

Primary text Secondary text

Seleccionado

Usa la prop selected para pintar un tag como seleccionado. Dentro de un TagGroup, un tag interactivo toma su estado de selección de los selectedValues del grupo.

Ver Código

<Tag selected secondaryText="appearance=filled" icon={CalendarMonthRegular} dismissible>Selected</Tag>
<Tag selected appearance="outline" secondaryText="appearance=outline" icon={CalendarMonthRegular} dismissible>Selected</Tag>
<Tag selected appearance="brand" secondaryText="appearance=brand" icon={CalendarMonthRegular} dismissible>Selected</Tag>

Forma

Usa la prop shape para renderizar tags circulares, redondeados o cuadrados. Por defecto es circular.

Ver Código

<script lang="ts">
  import { Avatar, Tag, type TagMediaProps } from 'fluentui-svelte';
</script>

{#snippet avatar({ shape }: TagMediaProps)}
  <Avatar {shape} name="Katri Athokas" size={28} badge={{ status: 'busy' }} />
{/snippet}

<Tag media={avatar}>Circular</Tag>
<Tag shape="rounded" media={avatar}>Rounded</Tag>
<Tag shape="square" media={avatar}>Square</Tag>

<Tag dismissible icon={CalendarMonthRegular} secondaryText="Secondary text">Circular</Tag>
<Tag shape="rounded" dismissible icon={CalendarMonthRegular} secondaryText="Secondary text">Rounded</Tag>
<Tag shape="square" dismissible icon={CalendarMonthRegular} secondaryText="Secondary text">Square</Tag>

Circular

Rounded

Square

Tamaño

Un tag admite los tamaños medium, small y extra-small. El valor por defecto es medium.

Ver Código

<script lang="ts">
  import { Avatar, Tag, type TagMediaProps } from 'fluentui-svelte';
</script>

{#snippet avatar({ shape }: TagMediaProps)}
  <Avatar {shape} name="Katri Athokas" size={28} badge={{ status: 'busy' }} />
{/snippet}
{#snippet smallAvatar({ shape }: TagMediaProps)}
  <Avatar {shape} name="Katri Athokas" size={20} badge={{ status: 'busy' }} />
{/snippet}
{#snippet extraSmallAvatar({ shape }: TagMediaProps)}
  <Avatar {shape} name="Katri Athokas" size={16} badge={{ status: 'busy' }} />
{/snippet}

<Tag>Medium</Tag>
<Tag dismissible media={avatar}>Medium dismissible</Tag>
<Tag icon={CalendarMonthRegular}>Medium with icon</Tag>

<Tag size="small">Small</Tag>
<Tag size="small" dismissible media={smallAvatar}>Small dismissible</Tag>
<Tag size="small" icon={CalendarMonthRegular}>Small with icon</Tag>

<Tag size="extra-small">Extra small</Tag>
<Tag size="extra-small" dismissible media={extraSmallAvatar}>Extra small dismissible</Tag>
<Tag size="extra-small" icon={CalendarMonthRegular}>Extra small with icon</Tag>

Medium Medium with icon

Small Small with icon

Extra small Extra small with icon

API de TagGroup

Un grupo de tags es un contenedor para varios tags. Entrega su size, appearance, disabled y dismissible a los tags que no definen los suyos, mantiene los valores de los tags interactivos seleccionados en selectedValues y permite mover el foco entre los tags con las flechas del teclado, también hacia arriba y abajo cuando el grupo ocupa varias filas.

Uso

El rol por defecto del grupo es toolbar. Cuando ninguno de los tags es accionable, usa role="list" en el grupo y role="listitem" en cada tag.

Ver Código

<!-- Tags that are not actionable are a list -->
<TagGroup aria-label="Simple tag group with Tag" role="list">
  <Tag role="listitem">Tag 1</Tag>
  <Tag role="listitem">Tag 2</Tag>
  <Tag role="listitem">Tag 3</Tag>
</TagGroup>

<!-- Interactive tags are a toolbar, which is the default role -->
<TagGroup aria-label="Simple tag group with interactive tags">
  <Tag interactive>Tag 1</Tag>
  <Tag interactive>Tag 2</Tag>
  <Tag interactive>Tag 3</Tag>
</TagGroup>

Deshabilitado

Un grupo deshabilitado deshabilita toda la colección de tags.

Ver Código

<TagGroup disabled aria-label="Disabled tag group with Tag" role="list">
  <Tag role="listitem">Tag 1</Tag>
  <Tag role="listitem">Tag 2</Tag>
  <Tag role="listitem">Tag 3</Tag>
</TagGroup>

<TagGroup disabled aria-label="Disabled tag group with interactive tags">
  <Tag interactive>Tag 1</Tag>
  <Tag interactive>Tag 2</Tag>
  <Tag interactive>Tag 3</Tag>
</TagGroup>

Descartar

Un grupo puede hacer que sus tags sean descartables e informa cada descarte mediante onDismiss con el value del tag. El grupo no elimina el tag: hazlo en tus datos. El foco pasa a un tag vecino cuando se descarta uno, así que el teclado permanece en el grupo; asegúrate de gestionar correctamente el foco cuando se hayan descartado todos los tags.

Ver Código

<script>
  const initialTags = [
    { value: '1', text: 'Tag 1' },
    { value: '2', text: 'Tag 2' },
    { value: '3', text: 'Tag 3' }
  ];

  let plainTags = $state(initialTags);
  let interactiveTags = $state(initialTags);
</script>

<TagGroup
  dismissible
  aria-label="TagGroup example with dismissible tags"
  onDismiss={(e, { value }) => (plainTags = plainTags.filter((tag) => tag.value !== value))}
>
  {#each plainTags as tag (tag.value)}
    <Tag value={tag.value}>{tag.text}</Tag>
  {/each}
</TagGroup>
<Button disabled={plainTags.length === initialTags.length} onclick={() => (plainTags = initialTags)}>
  Reset the example
</Button>

<TagGroup
  dismissible
  aria-label="TagGroup example with dismissible interactive tags"
  onDismiss={(e, { value }) => (interactiveTags = interactiveTags.filter((tag) => tag.value !== value))}
>
  {#each interactiveTags as tag (tag.value)}
    <Tag interactive value={tag.value}>{tag.text}</Tag>
  {/each}
</TagGroup>
<Button disabled={interactiveTags.length === initialTags.length} onclick={() => (interactiveTags = initialTags)}>
  Reset the example
</Button>

Seleccionar

Al activar el botón primario de un tag interactivo se alterna su value en selectedValues, y onTagSelect lo informa. Elimina tú mismo de selectedValues un valor descartado.

Ver Código

<script>
  const initialTags = [
    { value: '1', text: 'Tag 1' },
    { value: '2', text: 'Tag 2' },
    { value: '3', text: 'Tag 3' }
  ];

  let selectedValues = $state([]);
  let tags = $state(initialTags);
  let dismissibleSelectedValues = $state([]);

  const reset = () => {
    selectedValues = [];
    dismissibleSelectedValues = [];
    tags = initialTags;
  };
</script>

<p>Selected values: {selectedValues.join(', ')}</p>
<TagGroup bind:selectedValues aria-label="Tag group with multiselect tags">
  <Tag interactive value="1">Tag 1</Tag>
  <Tag interactive value="2">Tag 2</Tag>
  <Tag interactive value="3">Tag 3</Tag>
</TagGroup>

<p>Selected values: {dismissibleSelectedValues.join(', ')}</p>
<TagGroup
  dismissible
  bind:selectedValues={dismissibleSelectedValues}
  aria-label="Tag group with dismissible multiselect tags"
  onDismiss={(e, { value }) => {
    dismissibleSelectedValues = dismissibleSelectedValues.filter((v) => v !== value);
    tags = tags.filter((tag) => tag.value !== value);
  }}
>
  {#each tags as tag (tag.value)}
    <Tag interactive value={tag.value}>{tag.text}</Tag>
  {/each}
</TagGroup>

<Button
  disabled={!selectedValues.length && !dismissibleSelectedValues.length && tags.length === initialTags.length}
  onclick={reset}
>
  Reset the example
</Button>

Selected values:

Tamaños

Un grupo puede definir el tamaño por defecto de todos sus tags. Admite medium, small y extra-small. El valor por defecto es medium.

Ver Código

{#each ['medium', 'small', 'extra-small'] as size}
  <TagGroup {size} aria-label="{size} tag group example">
    <Tag interactive>{size}</Tag>
    <Tag interactive icon={CalendarMonthRegular}>{size}</Tag>
    <Tag interactive dismissible icon={CalendarMonthRegular}>{size}</Tag>
  </TagGroup>
{/each}

Props de Tag

Name	Type	Default	Description
`appearance`	`PillButtonAppearance`	`'filled'`	El tag puede tener apariencia filled, outline o brand. Recurre a la `appearance` del `TagGroup` en el que está.
`size`	`'extra-small'` \| `'small'` \| `'medium'`	`'medium'`	El tag tiene tres tamaños. Recurre a `size` del `TagGroup` en el que está.
`shape`	`'circular'` \| `'rounded'` \| `'square'`	`'circular'`	El tag puede tener forma circular, redondeada o cuadrada. Hereda `shape` de su `TagGroup`.
`disabled`	`boolean`	`false`	Indica que no se puede interactuar con el tag. Un tag dentro de un `TagGroup` deshabilitado también queda deshabilitado.
`selected`	`boolean`	`false`	Pinta el tag como seleccionado. Dentro de un `TagGroup`, un tag interactivo toma su estado seleccionado de `selectedValues` del grupo.
`dismissible`	`boolean`	`false`	Muestra un icono de descarte y permite descartar el tag. Recurre a `dismissible` del `TagGroup` en el que está. Un tag que no es interactivo se convierte en un único botón: activarlo, o pulsar Delete o Backspace sobre él, lo descarta.
`interactive`	`boolean`	`false`	Renderiza el tag como un tag de interacción: un botón principal que lleva la acción, seguido, cuando el tag es descartable, de un botón de descarte separado. Úsalo para un tag con acción principal y un tag simple para uno que no la tiene.
`value`	`string`		Identifica el tag dentro de un `TagGroup`. Es lo que reportan `onDismiss` y `onTagSelect`. Recurre a un id generado.
`icon`	`Snippet` \| `Component`		Un icono que se muestra antes del texto. No lo uses junto con `media`.
`media`	`Snippet` \| `Component`		Un elemento visual antes del texto, normalmente un `Avatar`. Recibe el `shape` actual del tag; pásalo al componente visual. No usar junto con `icon`.
`secondaryText`	`string` \| `Snippet`		Una segunda línea de texto que describe o complementa el texto principal.
`dismissIcon`	`Snippet` \| `Component`	`DismissRegular`	El icono del control para descartar.
`dismissLabel`	`string`	`'Dismiss'`	El nombre accesible del control para descartar. Cuando el tag se nombra con `aria-label` o `aria-labelledby`, el icono de descarte se oculta a las tecnologías de asistencia.
`onDismiss`	`(e: MouseEvent` \| `KeyboardEvent, value: string) => void`		Se llama cuando se descarta el tag. Los datos son del consumidor: el tag no se elimina a sí mismo.
`onclick`	`(e: MouseEvent) => void`		Se llama cuando se activa el tag. En un tag interactivo es el clic del botón principal.
`onkeydown`	`(e: KeyboardEvent) => void`		Se llama cuando se pulsa una tecla sobre el tag.
`primaryButtonAttributes`	`HTMLButtonAttributes`		Atributos del botón principal de un tag interactivo, por ejemplo `aria-haspopup`. Si le das un `id` personalizado, el botón de descarte se nombra a partir de él.
`dismissButtonAttributes`	`HTMLButtonAttributes`		Atributos del botón de descarte de un tag interactivo. Usa `aria-label` junto con `aria-labelledby: undefined` para darle un nombre que se sostenga por sí solo.
`children`	`Snippet`		El texto principal del tag.
`ref` bindable	`HTMLElement` \| `null`		La referencia del DOM del elemento del tag.
HTML Attributes

Props de TagGroup

Name	Type	Default	Description
`shape`	`'circular'` \| `'rounded'` \| `'square'`		Forma de los tags que no definen una propia.
`size`	`'extra-small'` \| `'small'` \| `'medium'`	`'medium'`	El tamaño que reciben los tags del grupo que no definen el suyo.
`appearance`	`PillButtonAppearance`		La apariencia que reciben los tags del grupo que no definen la suya.
`disabled`	`boolean`	`false`	Deshabilita todos los tags del grupo.
`dismissible`	`boolean`		Hace descartables los tags del grupo que no definen la suya.
`selectedValues` bindable	`string[]`	`[]`	Los valores de los tags interactivos seleccionados.
`onTagSelect`	`(e: MouseEvent, data: { value: string; selected: boolean }) => void`		Se llama cuando se activa un tag interactivo del grupo, con el valor que alterna.
`onDismiss`	`(e: MouseEvent` \| `KeyboardEvent, data: { value: string }) => void`		Se llama cuando se descarta un tag del grupo. Los datos son del consumidor: el grupo no elimina el tag.
`role`	`HTMLAttributes<HTMLDivElement>['role']`	`'toolbar'`	El rol del grupo. Usa `list` junto con `role="listitem"` en cada tag cuando ninguno es accionable.
`children`	`Snippet`		Los tags del grupo.
`ref` bindable	`HTMLDivElement` \| `null`		La referencia del DOM del elemento del grupo.
HTML Attributes

Componentes

Tag

Uso

Apariencia

Deshabilitado

Descartar

Nombre accesible

Interactivo (acción primaria)

Ícono

Media

Media o ícono, no ambos

Texto secundario

Seleccionado

Forma

Tamaño

API de TagGroup

Uso

Deshabilitado

Descartar

Seleccionar

Tamaños

Props de Tag

Props de TagGroup