PillButton

A PillButton is a checkbox styled as a pill for independent filters and multiple choices.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
</script>

<PillButton>Unread</PillButton>
<PillButton checked>Selected</PillButton>
<PillButton disabled>Disabled</PillButton>

Unread Unread Unread

Usage

<script>
	import { PillButton } from 'fluentui-svelte';
	let unread = $state(false);
</script>

<PillButton name="filter" value="unread" bind:checked={unread}>Unread</PillButton>

Appearance

Choose filled, outline or brand appearance. Each appearance supports selected and unselected states.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
</script>

<PillButton>Filled</PillButton>
<PillButton checked>Filled selected</PillButton>
<PillButton appearance="outline">Outline</PillButton>
<PillButton appearance="outline" checked>Outline selected</PillButton>
<PillButton appearance="brand">Brand</PillButton>
<PillButton appearance="brand" checked>Brand selected</PillButton>

Size

size changes height and typography together: small uses 24px/12px, medium 32px/14px, large 40px/16px and extra-large 48px/18px. Each pair gives the control height and font in pixels.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
</script>

<PillButton size="medium">Medium</PillButton>
<PillButton size="medium" checked>Medium selected</PillButton>
<PillButton size="small">Small</PillButton>
<PillButton size="small" checked>Small selected</PillButton>
<PillButton size="large">Large</PillButton>
<PillButton size="large" checked>Large selected</PillButton>
<PillButton size="extra-large">Extra large</PillButton>
<PillButton size="extra-large" checked>Extra large selected</PillButton>

Shape

Use shape to choose circular, rounded or square corners. The default is circular.

View Code

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

<PillButton shape="circular">Circular</PillButton>
<PillButton shape="circular" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Circular selected
</PillButton>
<PillButton shape="rounded">Rounded</PillButton>
<PillButton shape="rounded" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Rounded selected
</PillButton>
<PillButton shape="square">Square</PillButton>
<PillButton shape="square" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Square selected
</PillButton>

Selection and binding

Use bind:checked to keep selection synchronized with your state. Clicking the pill or pressing Space toggles the native checkbox; external state changes update it too.

View Code

<script lang="ts">
  import { PillButton, Button } from 'fluentui-svelte';
  let checked = $state(false);
</script>

<PillButton bind:checked>Unread</PillButton>
<output>{checked ? 'Selected' : 'Not selected'}</output>
<Button type="button" appearance="standard" onclick={() => (checked = !checked)}>Toggle</Button>

Unread Not selected

Disabled

Use disabled on individual pills or a fieldset around several pills. Disabled choices cannot receive focus, toggle or submit values, including when selected.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
</script>

<PillButton disabled>Disabled</PillButton>
<PillButton checked disabled>Selected and disabled</PillButton>
<PillButton appearance="outline" disabled>Disabled outline</PillButton>
<PillButton appearance="brand" checked disabled>Selected brand</PillButton>
<fieldset disabled>
  <legend>Disabled filters</legend>
  <PillButton name="filter" value="unread" checked>Unread</PillButton>
</fieldset>

Icons

Use icon to show a Fluent icon before the text. Icons are decorative; give an icon-only pill an accessible name with aria-label or aria-labelledby.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
  import CalendarMonthRegular from 'fluentui-icons-svelte/CalendarMonthRegular.svelte';
  import CheckmarkFilled from 'fluentui-icons-svelte/CheckmarkFilled.svelte';
</script>

<PillButton icon={CalendarMonthRegular}>Calendar</PillButton>
<PillButton icon={CheckmarkFilled} checked>Selected</PillButton>
<PillButton size="small" icon={CalendarMonthRegular}>Calendar</PillButton>
<PillButton size="large" icon={CalendarMonthRegular}>Calendar</PillButton>
<PillButton size="extra-large" icon={CalendarMonthRegular}>Calendar</PillButton>
<PillButton icon={CalendarMonthRegular} aria-label="Filter by calendar" />

Avatar

Use media for a decorative Avatar. The snippet receives the current shape; forward it to the avatar so their shapes stay synchronized. A component receives shape as a prop. Media scales with size, retains a uniform 4px inset and takes precedence over icon.

View Code

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

<PillButton>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Alex
</PillButton>
<PillButton checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" image={{ src: 'https://i.pravatar.cc/96?img=47' }} />{/snippet}
  Alex
</PillButton>
<PillButton size="small">
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Alex
</PillButton>
<PillButton size="small" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" image={{ src: 'https://i.pravatar.cc/96?img=47' }} />{/snippet}
  Alex
</PillButton>
<PillButton size="large">
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Alex
</PillButton>
<PillButton size="large" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" image={{ src: 'https://i.pravatar.cc/96?img=47' }} />{/snippet}
  Alex
</PillButton>
<PillButton size="extra-large">
  {#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
  Alex
</PillButton>
<PillButton size="extra-large" checked>
  {#snippet media({ shape })}<Avatar {shape} name="Alex" image={{ src: 'https://i.pravatar.cc/96?img=47' }} />{/snippet}
  Alex
</PillButton>

Multiple filters

Use a fieldset and legend to label independent choices. Bind each pill with bind:checked. Reuse name to submit multiple values in one form field.

View Code

<script lang="ts">
  import { PillButton } from 'fluentui-svelte';
  let filters = $state({ unread: true, flagged: false, attachments: false });
</script>

<fieldset>
  <legend>Message filters</legend>
  <PillButton name="filter" value="unread" bind:checked={filters.unread}>Unread</PillButton>
  <PillButton name="filter" value="flagged" bind:checked={filters.flagged}>Flagged</PillButton>
  <PillButton name="filter" value="attachments" bind:checked={filters.attachments}>Attachments</PillButton>
</fieldset>
<output>{JSON.stringify(filters)}</output>

Message filters

Unread Flagged Attachments

{"unread":true,"flagged":false,"attachments":false}

Forms

Set name and value to submit a selected pill. The native form, required, defaultChecked and disabled attributes are supported. Reset restores defaultChecked and updates bind:checked. An explicit checked state takes precedence initially. required applies to each pill individually.

View Code

<script lang="ts">
  import { PillButton, Button } from 'fluentui-svelte';
  let submitted = $state('');
  function submit(event: SubmitEvent & { currentTarget: HTMLFormElement }) {
    event.preventDefault();
    submitted = JSON.stringify(new FormData(event.currentTarget).getAll('filter'));
  }
</script>

<form onsubmit={submit}>
  <PillButton name="filter" value="unread" defaultChecked>Unread</PillButton>
  <PillButton name="filter" value="flagged">Flagged</PillButton>
  <Button type="submit">Submit filters</Button>
</form>
<output aria-live="polite">{submitted}</output>

External form owner

Use form to associate a pill with the id of a form that does not contain it. Submission, validation and reset still use the native checkbox.

View Code

<script lang="ts">
  import { PillButton, Button } from 'fluentui-svelte';
  let submitted = $state('');
  function submit(event: SubmitEvent & { currentTarget: HTMLFormElement }) {
    event.preventDefault();
    submitted = JSON.stringify(new FormData(event.currentTarget).getAll('filter'));
  }
</script>

<form id="filters-form" onsubmit={submit}>
  <Button type="submit">Submit filters</Button>
  <Button type="reset" appearance="standard">Reset</Button>
</form>
<PillButton form="filters-form" name="filter" value="unread" defaultChecked>Unread</PillButton>
<output aria-live="polite">{submitted}</output>

Unread

Required and validation

required applies to this particular checkbox. Pair aria-invalid with an explanatory message linked through aria-describedby. Invalid text, border and error messages use --fs-system-critical.

View Code

<script lang="ts">
  import { PillButton, Button } from 'fluentui-svelte';
  let accepted = $state(false);
  let attempted = $state(false);
</script>

<form onsubmit={(event) => event.preventDefault()}>
  <PillButton
    name="accepted"
    value="yes"
    required
    bind:checked={accepted}
    aria-invalid={attempted && !accepted ? 'true' : undefined}
    aria-describedby={attempted && !accepted ? 'accept-error' : undefined}
    oninvalid={() => (attempted = true)}
  >Accept notifications</PillButton>
  <Button type="submit">Continue</Button>
</form>
{#if attempted && !accepted}
  <p id="accept-error" role="alert" style="color: var(--fs-system-critical);">Select this option to continue.</p>
{/if}

Using with Label

Wrap PillButton in Label to name the native checkbox. Configure label and labelPosition on the wrapper. It also names icon-only pills. For standalone pills, use visible text, aria-label or aria-labelledby.

View Code

<script lang="ts">
  import { PillButton, Label } from 'fluentui-svelte';
  import CalendarMonthRegular from 'fluentui-icons-svelte/CalendarMonthRegular.svelte';
</script>

<Label label="Message filter" labelPosition="above">
  <PillButton name="filter" value="unread">Unread</PillButton>
</Label>
<Label label="Calendar filter" labelPosition="before">
  <PillButton icon={CalendarMonthRegular} />
</Label>

Message filter Unread

Filter by calendar

PillButton props

Name	Type	Default	Description
`ref` bindable	`HTMLInputElement` \| `null`		The DOM reference of the native checkbox.
`wrapperRef` bindable	`HTMLElement` \| `null`		The DOM reference of the pill surface.
`wrapperAttributes`	`HTMLAttributes<HTMLSpanElement>`		Attributes for the pill surface. Input attributes belong on the component itself.
`checked` bindable	`boolean` \| `null`		Whether the pill is checked. When omitted, `defaultChecked` determines the initial state.
`appearance`	`'filled'` \| `'outline'` \| `'brand'`	`'filled'`	The pill appearance.
`size`	`'small'` \| `'medium'` \| `'large'` \| `'extra-large'`	`'medium'`	The height and text size of the pill: `small` is 24px/12px, `medium` is 32px/14px, `large` is 40px/16px and `extra-large` is 48px/18px.
`shape`	`'circular'` \| `'rounded'` \| `'square'`	`'circular'`	The shape of the pill: `circular`, `rounded` or `square`.
`icon`	`Snippet<[SVGAttributes<SVGElement>]>` \| `Component<SVGAttributes<SVGElement>>`		An optional decorative Fluent icon before the content.
`media`	`Snippet<[PillButtonMediaProps]>` \| `Component<PillButtonMediaProps>`		Decorative media before the text, usually an `Avatar`. Receives the pill's current `shape`; forward it to the media component. Fits the control height with a uniform 4px inset. Takes precedence over `icon`.
`children`	`Snippet`		The visible label. Provide `aria-label` or `aria-labelledby` when there is no visible text.
`HTMLInputAttributes` without `type`, `children`, `checked`, `size`, `on:`

Components

PillButton

Usage

Appearance

Size

Shape

Selection and binding

Disabled

Icons

Avatar

Multiple filters

Forms

External form owner

Required and validation

Using with Label

PillButton props