# fluentui-svelte

Fluent UI 2 components for Svelte 5, published on npm as `fluentui-svelte`. The components use runes, snippets
and plain event attributes (`onclick`), so write consumer code the same way: no `export let`, no slots, no `on:click`.

The styles rely on CSS that only Chromium ships today (`field-sizing`, unprefixed `mask`, `backdrop-filter`). In
Firefox and Safari some visuals degrade; behaviour and accessibility do not.

Written for fluentui-svelte `0.7.2`. When the installed version (`node_modules/fluentui-svelte/package.json`)
differs, the guides inside `node_modules` win.

## Before writing code

1. Find the component in the [index](#components) at the end of this file.
2. Read its guide before using it. The installed package ships one per component, matching its version:
   `node_modules/fluentui-svelte/dist/components/<folder>/docs/llms.md`.
   Without the package installed, fetch `https://fluentui-svelte.dev/docs/components/<folder>.md`.
3. Use only the props the guide lists. Do not carry props over from Fluent UI React, WinUI or other Svelte
   libraries: the names and behaviour differ.

## Setup

```sh
npm i -D fluentui-svelte
```

Import the stylesheets once, in the root layout (`src/routes/+layout.svelte` in SvelteKit), and wrap the app in
`FluentUISvelte`. The provider starts the keyboard navigation engine: without it the components render, but arrow
keys do not move focus inside lists, menus, trees and tables.

```svelte
<script>
	import 'fluentui-svelte/theme.css'; // required: the design tokens every component reads
	import 'fluentui-svelte/reset.css'; // optional; skip it if the app already has a reset (Tailwind preflight)
	import 'fluentui-svelte/typography.css'; // optional: the Fluent type ramp
	import 'fluentui-svelte/class-darkmode.css'; // dark theme via a `dark` class on <html>
	import { ModeWatcher } from 'mode-watcher';
	import { FluentUISvelte } from 'fluentui-svelte';

	let { children } = $props();
</script>

<ModeWatcher />
<FluentUISvelte>
	{@render children()}
</FluentUISvelte>
```

- Dark mode: pick **one** of `class-darkmode.css` (a `dark` class on `<html>`, which `<ModeWatcher />` from
  `mode-watcher` sets; switch it with `setMode('dark' | 'light' | 'system')` or `toggleMode()`) and
  `media-darkmode.css` (follows `prefers-color-scheme`, no JavaScript). `mode-watcher` is already a dependency of
  the library. The provider does not render `<ModeWatcher />` for you.
- `FluentUISvelte` takes only `children` (and an optional `tabspotInstance`). It has no theme or reduced-motion
  props; reduced motion follows the operating system.
- Everything is exported from the package root: `import { Button, Dialog } from 'fluentui-svelte'`.

## Rules every component follows

**Icons** come from `fluentui-icons-svelte` (6,000+ Fluent icons as Svelte components). The library depends on it,
but an app that imports icons itself must install it too: `npm i -D fluentui-icons-svelte`. Browse the names at
https://fluentui-icons-svelte.pages.dev/icons. Import each icon from its own file, never from the package root. The
root re-exports thousands of components, and Vite prebundles all of them in dev (minutes of cold start):

```svelte
<script>
	import AddRegular from 'fluentui-icons-svelte/AddRegular.svelte'; // yes
	// import { AddRegular } from 'fluentui-icons-svelte';             // no
</script>
```

Icon props (`icon`, `indicatorIcon`, `iconBefore`, `media`, `expandIcon`, …) take either the component itself
(`icon={AddRegular}`) or a snippet when the icon needs its own props:
`{#snippet add()}<AddRegular width="1.25rem" />{/snippet}`.

**Bound state starts at `null`, not `undefined`.** Every `$bindable` prop defaults to `null` (or another simple
value), and Svelte throws when you `bind:` a prop with a default to `undefined`:

```svelte
<script>
	let date = $state(null); // not $state() / undefined
	let input = $state(null); // for bind:ref too
</script>

<CalendarDatePicker bind:value={date} />
```

**Where attributes go.** Attributes passed straight to a component (`id`, `name`, `required`, `class`, `aria-*`,
`oninput`, …) land on the element that holds the value or does the job: the native `<input>`/`<select>` of a form
control, the `<button>` of a Button. Inner parts are reached through named props instead:

- `*Attributes` for a plain element: `wrapperAttributes` (outer container), `buttonAttributes`, `inputAttributes`,
  `listAttributes`, `dismissButtonAttributes`.
- `*Props` for an inner component: `flyoutProps`, `listboxProps`, `tagGroupProps`, `tooltipProps`,
  `menuTriggerProps`, `primaryButtonProps`.
- `*Ref` to bind those elements: `wrapperRef`, `buttonRef`, `inputRef`, `menuTriggerRef`. `ref` (bindable) is the
  main element.

To label or describe an inner part, pass the attribute through its `*Props`/`*Attributes` prop. Do not look for a
dedicated prop such as `menuLabel`: there is none.

**`as` picks the rendered tag** from a fixed list (Button: `button | a | div`; Card: `div | article | section | a`;
ListViewItem: `li | a | button | div`; DialogTitle: `div | h1`–`h6`). Any other value throws.

**Callbacks** are named `onXxx` and receive `(event, data)`: `onOpenChange`, `onCheckedValueChange`,
`onSelectionChange`, `onTabSelect`, `onDismiss`, `onAction`. Exceptions: Card `onSelectionChange(id, selected)` has
no event, and the text inputs keep WinUI names (`textChanged`, `querySubmitted`, `suggestionChosen`). Native events
stay lowercase (`onclick`, `oninput`).

**You own the data.** Callbacks that report a removal never remove anything: `Tag`/`TagGroup` `onDismiss` and
`TabView` `onTabClose` tell you which item to drop from your own array.

**Parts need their parent.** `DialogTrigger`, `MenuItem`, `CardHeader`, `DropdownOption`, `TagPickerOption`,
`ListViewItem`, `TreeViewItem`, `TopNavItem`, `TabViewTab` and the other sub-components throw when rendered outside
their root component.

## Forms

Form controls are real form fields: `name`, `value`, `required`, `form`, `min`/`max`/`step` and the validation
events go to a native element, so the values reach `FormData`, the browser validates them and `form.reset()`
restores them. Plain `<form method="POST">` and SvelteKit form actions work without glue code.

```svelte
<script>
	import { Label, TextBox, Dropdown, DropdownOption, Checkbox, Button } from 'fluentui-svelte';

	let email = $state('');
	let role = $state('');
</script>

<form method="POST">
	<Label label="Email"><TextBox name="email" type="email" required bind:value={email} /></Label>
	<Label label="Role">
		<Dropdown name="role" required bind:value={role}>
			<DropdownOption value="dev" text="Developer">Developer</DropdownOption>
			<DropdownOption value="design" text="Designer">Designer</DropdownOption>
		</Dropdown>
	</Label>
	<Checkbox name="terms" required>I accept the terms</Checkbox>
	<Button type="submit">Send</Button>
</form>
```

- **Label** names the first control inside it, or the next one after it: the control takes the label's id when it
  has none. If the control has an `id` of its own and the label text comes first, pass that id as `for`. Inside a
  Label, the own text of a Checkbox, RadioButton or ToggleSwitch is not rendered: the Label names it.
- **Pickers** (Dropdown, TagPicker, DatePicker, TimePicker, CalendarDatePicker) draw a button or input and keep a
  hidden native field for the value. Attributes you pass go to that field; the visible control takes
  `buttonAttributes` / `inputAttributes`. A plain `<label for>` names a picker only after hydration, so prefer
  `Label` or `aria-labelledby`.
- **Invalid state** has no prop: the styles follow native validation (`:user-invalid`) and `aria-invalid="true"`.
  Pass `aria-invalid` and `aria-errormessage` (or `aria-describedby`) straight to the control for server errors.
- `Label` has a `required` of its own that only draws the indicator; the field still needs `required`.

## Overlays

None of them uses a portal: popups are positioned in place (`position: fixed` for Menu and Tooltip), so an
ancestor with `transform`, `filter` or `contain` moves or clips them.

**Dialog** wraps the native `<dialog>`. `type` is `'modal'` (default), `'non-modal'` or `'alert'` (no dismissal by
Escape or outside click).

```svelte
<script>
	import {
		Dialog,
		DialogTrigger,
		DialogSurface,
		DialogTitle,
		DialogContent,
		DialogActions,
		Button
	} from 'fluentui-svelte';

	let dialog = $state(null);
</script>

<Dialog bind:this={dialog} onOpenChange={(open) => console.log(open)}>
	<DialogTrigger>Edit profile</DialogTrigger>
	<DialogSurface>
		<DialogTitle>Edit profile</DialogTitle>
		<DialogContent>…</DialogContent>
		<DialogActions>
			<Button>Save</Button>
			<Button appearance="standard" onclick={() => dialog.closeDialog()}>Close</Button>
		</DialogActions>
	</DialogSurface>
</Dialog>
```

Open a modal or alert dialog with `DialogTrigger` or `dialog.openDialog()`. Setting `open` only adds the `open`
attribute, which shows the `<dialog>` without the modal layer (no backdrop, no focus trap).

**Menu** renders no trigger of its own: `MenuTrigger` hands its snippet the props and the state to bind, and the
popover appears only once `state.ref` is bound.

```svelte
<Menu hasCheckmarks {checkedValues} onCheckedValueChange={(e, values) => (checkedValues = values)}>
	<MenuTrigger>
		{#snippet children({ state, menuTriggerProps })}
			<Button bind:ref={state.ref} {...menuTriggerProps}>Sort</Button>
		{/snippet}
	</MenuTrigger>
	<MenuPopover>
		<MenuList>
			<MenuItemRadio name="sort" value="name">Name</MenuItemRadio>
			<MenuItemRadio name="sort" value="date">Date</MenuItemRadio>
			<MenuDivider />
			<MenuItem onclick={refresh}>Refresh</MenuItem>
		</MenuList>
	</MenuPopover>
</Menu>
```

- `checkedValues` (`Record<name, value[]>`) and `open` are one-way: write them back from `onCheckedValueChange` /
  `onOpenChange`. A radio item closes the menu; checkbox and switch items keep it open.
- A submenu is a nested `<Menu>`, with its own trigger and popover, inside a `MenuList`.
- `ContextMenuTrigger ref={element}` opens the menu on right click; get `element` from `bind:this`, never from
  `document.querySelector` in markup (it breaks SSR).
- With a `SplitButton`, the snippet also passes `primaryButtonProps`; bind `menuTriggerRef={state.ref}` and give
  `menuTriggerProps` an `aria-label`, because that part shows only an arrow.

**Tooltip** wraps its target and spreads attributes onto it:

```svelte
<Tooltip content="Delete the file" relationship="description" withArrow>
	{#snippet children(attrs)}
		<Button {...attrs}>Delete</Button>
	{/snippet}
</Tooltip>
```

`relationship` defaults to `'label'`, which makes the tooltip the accessible name of the target. Use
`'description'` when the target already has a name (visible text or `aria-label`). A `target` prop
(an `HTMLElement`) anchors a tooltip to an element elsewhere.

**Flyout** is only the floating surface: it has no trigger, open state or outside-click handling. Anchor it with
`floating reference={element}` (plus `placement`, `offset`), show and hide it with `hidden` or `{#if}`, and close
it yourself.

**MenuCommandBar** adds a row of square, icon-only commands at the top or bottom of a `MenuList` (set its
`position` to match). Each `MenuCommandBarItem` needs an `icon` and a `label`, which names it and shows as its
tooltip; the `overflow` snippet adds a "more" button with the secondary commands.

## App shell

`AppWindow` draws the frame of a desktop-style app (Mica, border, shell shadow). Its direct children are an
optional `TitleBar` across the top, an optional `SideNav` and the `AppSurface` that holds the page:

```svelte
<script>
	import { page } from '$app/state';
	import {
		AppWindow,
		AppSurface,
		TitleBar,
		TitleBarLeftControls,
		TitleBarRightControls,
		SideNav,
		SideNavItem
	} from 'fluentui-svelte';
	import AppsRegular from 'fluentui-icons-svelte/AppsRegular.svelte';
	import HomeRegular from 'fluentui-icons-svelte/HomeRegular.svelte';
	import FolderRegular from 'fluentui-icons-svelte/FolderRegular.svelte';

	let { children } = $props();
</script>

<div style="height: 100dvh">
	<AppWindow active>
		<TitleBar>
			{#snippet leftControls()}
				<TitleBarLeftControls globalNav appIcon={AppsRegular} appName="Contoso" />
			{/snippet}
		</TitleBar>
		<SideNav header="Workspace">
			<SideNavItem href="/" label="Home" icon={HomeRegular} active={page.url.pathname === '/'} />
			<SideNavItem href="/files" label="Files" icon={FolderRegular} active={page.url.pathname.startsWith('/files')} />
		</SideNav>
		<AppSurface>{@render children()}</AppSurface>
	</AppWindow>
</div>
```

- `AppWindow` is `100%` wide and tall unless you pass `width` and `height`, so its container needs a height. It
  clips overflow: the page scrolls inside `AppSurface`.
- `active` defaults to `false`, which draws the inactive window shadow; set it on the window that has focus.
- `SideNav` owns no router: set each item's `href` and `active` from the current route. `bind:collapsed` controls
  the icon rail; `floating` overlays the page instead of taking space (a floating SideNav outside an `AppWindow`
  needs a positioned parent). `SideNavItem` is a link; use `as="button"` for actions.
- `TitleBarLeftControls globalNav` expands and collapses the SideNav of its window. The window buttons of
  `TitleBarRightControls` (`onMinimize`, `onWindowToggle`, `onClose`, `maximized`) only report the press: the host
  (Tauri, Electron) minimizes, maximizes and closes the window.

## Choosing a component

| Need                                                   | Use                                                                          |
| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Pick one or several values from a fixed list           | `Dropdown` + `DropdownOption` (`bind:value`, `multiple` makes it `string[]`) |
| Free text with suggestions, search box                 | `AutoSuggestBox` + `AutoSuggestBoxOption` (pass `index` to every option)     |
| Several values shown as removable tags, or new entries | `TagPicker` + `TagPickerOption` (`bind:selectedOptions`)                     |
| A few exclusive options always visible                 | `RadioButton` with `bind:group`                                              |
| Date / time                                            | `CalendarDatePicker`, `DatePicker`, `TimePicker`, inline `CalendarView`      |
| Selectable list of items                               | `ListView` + `ListViewItem value` (`bind:selectedItems`, `selectionMode`)    |
| Hierarchy                                              | `TreeView` + `TreeViewItem` (`bind:openItems`, `bind:checkedItems`)          |
| Tabular data                                           | `Table` primitives: sorting and selection are yours to wire                  |
| Document tabs                                          | `TabView` (`bind:activeTab`; you render the panels)                          |
| Section navigation                                     | `TopNav` (`bind:selectedValue`), `Breadcrumb`                                |
| Status message                                         | `InfoBar`                                                                    |
| App frame with title bar and side navigation           | `AppWindow` + `TitleBar` + `SideNav` + `AppSurface`                          |
| Icon-only commands in a menu (cut, copy, paste)        | `MenuCommandBar` + `MenuCommandBarItem` inside a `MenuList`                  |

`DropdownSelect` styles the native `<select>` with `appearance: base-select`. That needs Chrome or Edge 135+ or
Safari 27+, and Chrome or Edge 145+ with `multiple`; other browsers, Firefox included, show the native select
without rich option content. Use `Dropdown` when the select must look the same in every browser.

## SSR (SvelteKit)

Components render on the server. A few need data the server cannot read from the markup:

- `DropdownOption`: pass `text`, or the button shows the raw value until hydration.
- `TagPicker`: tags show the raw values on the server unless a custom `tag` snippet renders the text.
- `CalendarView`: pass `today` (built from year, month and day) so server and browser agree on the date;
  `CalendarDatePicker` needs the visitor's `timeZone` in `format`.
- Menu popovers are not in the server HTML; arrow-key navigation starts after hydration.
- Never read `document` or `window` in markup or at the top of `<script>`.

## Pitfalls that throw

- `AutoSuggestBox`: `selectOnFocus` with `multiselect`.
- `TagPicker`: `single` with more than one entry in `selectedOptions`.
- `Slider`: `min` not lower than `max`, or `step` larger than `max - min`.
- `Rating`: `max` not a whole number greater than 1.
- `Card`: `selected` or `showFloatingAction` without `selectable`; `as="a"` with `selectable`; an `action` inside a
  selectable card.
- An `as` value outside the component's list; a sub-component outside its parent; `bind:` to `undefined`.

Other mistakes that do not throw:

- `AutoSuggestBox` submits its form on Enter unless `querySubmitted` calls `preventDefault()`.
- An interactive `Tag` inside a `TagPicker`; `media` and `icon` together on a `Tag`.
- A `Table` without `TableHeader`, or with its parts' roles overridden.
- `Tooltip` with the default `relationship="label"` on a control that already has a name.

## Components

Folder, exports, status (only when the API may still change) and summary. Read
`node_modules/fluentui-svelte/dist/components/<folder>/docs/llms.md` before using one.

<!-- components:start -->

- `app-surface`: `AppSurface`. The area of an app that holds its content: a layer over the window or its Mica, with rounded corners next to a SideNav, in the colors of an active or an inactive window.
- `app-window`: `AppWindow`. The surface of an app: a Mica window built on the Flyout, with its own border and the shell shadow of an active or an inactive window, sized by a width and a height.
- `auto-suggest-box`: `AutoSuggestBox`, `AutoSuggestBoxOption`. An input field that shows dynamic suggestions as the user types, improving form and search efficiency.
- `avatar`: `Avatar`. A graphical representation of a user, team, or entity, showing an image, icon, or initials with optional presence status.
- `badge`: `Badge`, `BadgeIcon`. A visual decoration for UI elements that displays notifications, status indicators, or counts with configurable colors, shapes, and styles.
- `breadcrumb`: `Breadcrumb`, `BreadcrumbItem`, `BreadcrumbButton`, `BreadcrumbDivider`. A navigation landmark that shows where a page sits in the hierarchy above it, in three sizes and with room for an overflow menu.
- `button`: `Button`, `SplitButton`. A button triggers an action or event when activated, with accent, standard, and subtle appearances.
- `calendar-date-picker`: `CalendarDatePicker`. A button trigger paired with a CalendarView popup for selecting a single date.
- `calendar-view`: `CalendarView`, `CalendarViewHeader`, `CalendarViewControls`, `CalendarViewDays`, `CalendarViewMonths`, `CalendarViewYears`, `CalendarViewItem`. An inline calendar for browsing days, months, and years and selecting dates or a range.
- `card`: `Card`, `CardHeader`, `CardFooter`, `CardPreview`. A card is a container that displays content and actions on a single topic.
- `checkbox`: `Checkbox`. A control a user can check or clear, and that can also report an indeterminate (mixed) state.
- `color-picker`: `ColorPicker`. A Fluent color picker with square and circular spectra, RGB and HSV fields, and optional opacity.
- `date-picker`: `DatePicker`. An input for selecting a date from carousel-style day, month, and year columns.
- `dialog`: `Dialog`, `DialogTitle`, `DialogContent`, `DialogActions`, `DialogSurface`, `DialogTrigger`. A window overlaid on the page that requires user attention, composed of trigger, surface, title, content, and actions.
- `divider`: `Divider`. A horizontal or vertical rule that visually separates content within a layout, with an optional label.
- `dropdown`: `Dropdown`, `DropdownOption`. A custom dropdown that lets users select one or more options from a list, with rich option content.
- `dropdown-select`: `DropdownSelect`, `DropdownSelectOption`. A native-select-based dropdown for choosing one or more options, with support for rich option content.
- `expander`: `Expander`. A control that displays a header and a collapsible content area that can expand up or down.
- `file-uploader`: `FileUploader`. A drop zone and file list that picks, drops, captures and imports files, and uploads them to any S3-compatible storage, powered by upup.
- `flyout`: `Flyout`. A floating panel that displays additional information or options in a non-intrusive, accessible way.
- `hyperlink`: `Hyperlink`. A clickable link that navigates to a specified URL, following Fluent UI design principles with built-in accessibility.
- `info-bar`: `InfoBar`. An inline, non-intrusive status message with built-in severity levels and an optional close button.
- `label`: `Label`. An accessible caption for a form control, with configurable size, weight, position, and required state.
- `list-view`: `ListView`, `ListViewItem`, `ListViewItemBranch`. A vertically stacked set of items that can be focused, selected, and navigated with the keyboard.
- `media-player`: `MediaPlayer`, `MediaPlayerButton`. A video player with Fluent transport controls: seek bar, volume, subtitles, playback speed, full screen and picture-in-picture, powered by Video.js.
- `menu`: `Menu`, `MenuItem`, `MenuDivider`, `MenuGroup`, `MenuTrigger`, `MenuPopover`, `MenuList`, `MenuItemCheckbox`, `MenuItemRadio`, `MenuItemSwitch`, `MenuCommandBar`, `MenuCommandBarItem`, `ContextMenuTrigger`. A dropdown list of actions or options, with support for groups, submenus, checkable items, and context menus.
- `number-box`: `NumberBox`. A numeric input with min, max, and step constraints and optional spinner buttons.
- `persona`: `Persona`. A visual representation of a person combining an avatar, presence, and up to three lines of text.
- `pill-button`: `PillButton`. A checkbox styled as a Fluent pill, with native form submission, validation and reset.
- `progress-bar`: `ProgressBar`. A horizontal progress indicator that shows determinate or indeterminate progress, with paused and error states.
- `progress-ring`: `ProgressRing`. A circular progress indicator that shows determinate or indeterminate progress, with paused and error states.
- `radio-button`: `RadioButton`. A control for choosing a single option from a set of mutually exclusive choices.
- `rating`: `Rating`. A control that lets users give a value to an item by selecting one of a row of stars.
- `side-nav`: `SideNav`, `SideNavItem`, `SideNavBranch`. Collapsible app navigation with an icon rail, floating overlay, nested links, custom content and a pinned footer.
- `skeleton`: `Skeleton`. A placeholder that indicates where content will appear while it is loading.
- `slider`: `Slider`. A control that lets users select a value from a continuous or discrete range by dragging a thumb along a track.
- `tab-view`: `TabView`, `TabViewTab`. A strip of document tabs, with icons, close buttons and a new tab button, that owns the selection and leaves the content to you.
- `table`: `Table`, `TableHeader`, `TableHeaderCell`, `TableBody`, `TableRow`, `TableCell`, `TableSelectionCell`, `TableCellLayout`, `TableCellActions`. A low level set of primitives to display two dimensional data, with support for sorting, selection and custom cell layouts.
- `tag`: `Tag`, `TagGroup`. A visual representation of an attribute, person or asset that can be dismissed, selected and grouped, with an interactive variant that carries a primary action.
- `tag-picker`: `TagPicker`, `TagPickerOption`, `TagPickerOptionGroup`. A text field and a dropdown that let people choose several options from a list, or enter their own, each choice shown as a dismissible tag.
- `text-box`: `TextBox`, `TextBoxButton`. A single-line (or configurable) text input for capturing plain text, with search, password, and number types.
- `textarea`: `TextArea`. A multiline text input that lets the user enter and edit longer, free-form text.
- `time-picker`: `TimePicker`. An input for selecting a time from carousel-style hour, minute, and second columns, in 12- or 24-hour format.
- `title-bar`: `TitleBar`, `TitleBarLeftControls`, `TitleBarRightControls`. The top bar of an app shell, laid out like a Windows 11 title bar: navigation and app identity at the start, a flexible search at the center, and the person picture and window controls at the end.
- `toggle-switch`: `ToggleSwitch`. A switch that lets someone choose between two mutually exclusive options with an immediate result.
- `tooltip`: `Tooltip`. A small popup that displays additional information about an element when the user hovers over it.
- `top-nav`: `TopNav`, `TopNavItem`. A row of navigation items with a bar that travels to whichever one is selected, in four appearances and three sizes.
- `tree-view`: `TreeView`, `TreeViewItem`, `TreeViewItemContent`. A hierarchical, nested list where each item can be expanded, checked, or selected.

<!-- components:end -->

---

# AppSurface

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An app surface is the area of an app that holds its content, next to the navigation. It is square on its own; next to a SideNav it rounds the corner that faces it and the one across from it. It is either a `layer` over the window or the `mica` of the window itself, in the colors of an active or an inactive window.

## Usage

Inside AppWindow, the surface inherits the window's active state unless active is explicitly set. Without a SideNav in the window, or on its own, it has no corner radius. With one it rounds the corner that faces the SideNav and the one across from it, following its `position`; a floating and collapsed SideNav removes the radii until either state changes.

Put the content of the app inside the surface, usually in the space an `AppWindow` has left once the navigation takes its place. The surface grows to fill the room its container leaves it, scrolls its content when it does not fit, and is a `layer` unless you set another `mode`.

```svelte
<script>
	import { AppSurface, AppWindow } from 'fluentui-svelte';
</script>

<AppWindow width={400} height={160}>
	<AppSurface style="padding: 1rem">This is the content of the app.</AppSurface>
</AppWindow>
```

## Examples

### Mode

`layer`, the default, is a layer over the window, with the stroke of a card. `mica` paints the base of the window itself, with the stroke of a control surface.

```svelte
<AppWindow width={400} height={120}>
	<div style="display: flex; flex: 1; min-height: 0">
		<div style="flex: none; width: 3rem"></div>
		<AppSurface mode="layer" style="padding: 1rem">Layer</AppSurface>
	</div>
</AppWindow>

<AppWindow width={400} height={120}>
	<div style="display: flex; flex: 1; min-height: 0">
		<div style="flex: none; width: 3rem"></div>
		<AppSurface mode="mica" style="padding: 1rem">Mica</AppSurface>
	</div>
</AppWindow>
```

### Active and Inactive

`active` tells whether the window the surface lives in is the active one. A `layer` is solid while active and translucent while inactive, which is the default; `mica` paints the same base in both states. Set it from the same focus state as the window.

```svelte
<script>
	let active = $state(false);
</script>

<AppWindow {active} width={400} height={120}>
	<div style="display: flex; flex: 1; min-height: 0">
		<div style="flex: none; width: 3rem"></div>
		<AppSurface {active} style="padding: 1rem">Layer</AppSurface>
	</div>
</AppWindow>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:AppSurfaceProps -->

| Name                                                | Type                      | Default   | Description                                                                                                                                                 |
| --------------------------------------------------- | ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLElement`             |           | The DOM reference of the surface element.                                                                                                                   |
| `mode`                                              | `'layer'` &#124; `'mica'` | `'layer'` | The material of the surface: a `layer` over the window, or the `mica` of the window itself.                                                                 |
| `active`                                            | `boolean`                 | `false`   | Whether the window the surface lives in is active, which picks the surface color. Inherits AppWindow's active state when omitted, or false when standalone. |
| `children`                                          | `Snippet`                 |           | The content of the surface.                                                                                                                                 |
| `HTMLAttributes<HTMLDivElement>` without `children` |                           |           |                                                                                                                                                             |

<!-- /props:AppSurfaceProps -->

---

# AppWindow

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An app window is the surface of an app: a Mica window with its own border and a shell shadow that tells the active window from the inactive ones. It is built on the Flyout, so it takes its content the same way, and it fills the space around it unless you give it a size.

## Usage

Start with a `TitleBar` if the window has one, then place page content in an `AppSurface` or another scrollable container. The window itself clips overflow. It is `100%` wide and tall unless you give it a `width` and a `height`.

```svelte
<script>
	import {
		AppSurface,
		AppWindow,
		AutoSuggestBox,
		TitleBar,
		TitleBarLeftControls,
		TitleBarRightControls
	} from 'fluentui-svelte';
	import AppsRegular from 'fluentui-icons-svelte/AppsRegular.svelte';
</script>

<AppWindow width={400} height={200}>
	<TitleBar>
		{#snippet leftControls()}
			<TitleBarLeftControls appIcon={AppsRegular} appName="FluentUI App" />
		{/snippet}
		{#snippet rightControls()}
			<TitleBarRightControls />
		{/snippet}
	</TitleBar>
	<AppSurface style="padding: 1rem">This is the content of the window.</AppSurface>
</AppWindow>
```

## Examples

### Size

`width` and `height` take a number in pixels or any CSS length. By default they take `100%` of their container.

```svelte
<AppWindow width={200} height={100} />
<AppWindow width="14rem" height="6rem" />

<div style="width: 260px; height: 120px">
	<AppWindow />
</div>
```

### Active and Inactive

`active` picks the shell shadow the window casts: the lighter one of an inactive window, which is the default, or the deeper one of the active window. Set it from the focus state of the window your app lives in.

```svelte
<script>
	let active = $state(false);
</script>

<AppWindow {active} width={400} height={160} />
```

### With a Title Bar

The window paints the Mica background, so a `TitleBar` inside it stays transparent and sits right on it.

```svelte
<AppWindow width={400} height={220}>
	<TitleBar searchMinWidth={120}>
		{#snippet leftControls()}
			<TitleBarLeftControls appIcon={AppsRegular} appName="FluentUI App" />
		{/snippet}
		{#snippet search()}
			<AutoSuggestBox placeholder="Search" aria-label="Search" />
		{/snippet}
		{#snippet rightControls()}
			<TitleBarRightControls />
		{/snippet}
	</TitleBar>
	<AppSurface style="padding: 1rem">This is the content of the window.</AppSurface>
</AppWindow>
```

## Shared window context

AppWindow creates a context per instance. Descendant components can call the exported `getAppWindowContext()` during initialization; it returns null outside AppWindow. Call it inside a child component, rather than in the parent that renders AppWindow.

`config.width` and `config.height` expose window dimensions. `state` contains the window `ref`, `active`, `maximized`, `minimized`, and registered `sideNav`, `titleBar`, `globalNav` and `appSurface` parts. Parts are null until mounted and are cleared on unmount. SideNav exposes live `collapsed`, `floating`, `position` and `ref` getters, and `setCollapsed(event, collapsed)`. `globalNav` is the global navigation button of the TitleBar (`TitleBarLeftControls`): its `ref` and `enabled`, which tells SideNav to hide its own hamburger. Nested AppWindow instances have independent contexts.

The host reports maximized/minimized through AppWindow props; these flags do not invoke native APIs or hide the window. TitleBarRightControls inherits maximized unless explicitly overridden. AppSurface inherits active unless overridden and removes its corner radii while its window's SideNav is floating and collapsed.

```svelte
<!-- WindowStatus.svelte -->
<script>
	import { getAppWindowContext } from 'fluentui-svelte';
	const appWindow = getAppWindowContext();
</script>

<p>Maximized: {appWindow?.state.maximized ?? false}</p>
<p>Minimized: {appWindow?.state.minimized ?? false}</p>
<p>Navigation collapsed: {appWindow?.state.sideNav?.collapsed ?? false}</p>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:AppWindowProps -->

| Name                                                | Type                        | Default  | Description                                                                                                                                           |
| --------------------------------------------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLElement` &#124; `null` |          | The DOM reference of the window element.                                                                                                              |
| `width`                                             | `number` &#124; `string`    | `'100%'` | The width of the window. A number is in pixels, a string is any CSS length.                                                                           |
| `height`                                            | `number` &#124; `string`    | `'100%'` | The height of the window. A number is in pixels, a string is any CSS length.                                                                          |
| `active`                                            | `boolean`                   | `false`  | Whether the window is the active one, which picks the shell shadow it casts: a deeper one while active, a lighter one while inactive.                 |
| `maximized` _bindable_                              | `boolean`                   | `false`  | The maximized state reported by the host. Shared through AppWindow context and inherited by TitleBarRightControls when its maximized prop is omitted. |
| `minimized` _bindable_                              | `boolean`                   | `false`  | The minimized state reported by the host. Shared with window descendants; it does not call a native window API or hide the component.                 |
| `children`                                          | `Snippet`                   |          | The content of the window, such as a `TitleBar` and the page below it.                                                                                |
| `HTMLAttributes<HTMLDivElement>` without `children` |                             |          |                                                                                                                                                       |

<!-- /props:AppWindowProps -->

---

# AutoSuggestBox

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

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

```svelte
<script>
	import { AutoSuggestBox, AutoSuggestBoxOption } 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>
```

## Examples

### Open on focus

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

```svelte
<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. Its `size` is the total number of suggestions, while each option keeps its real `index`.

```svelte
<script>
	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';

	let listRef;
</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.

```svelte
<script>
	let selectedOptions = $state([]);
</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`.

```svelte
<script>
	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';

	let items = $state(people);
	let listRef;
</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>
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:AutoSuggestBoxProps -->

| Name                                                                                              | Type                                                            | Default              | Description                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrapperRef` _bindable_                                                                           | `HTMLDivElement` &#124; `null`                                  |                      | The DOM reference of the wrapper element.                                                                                                                                                                                                         |
| `ref` _bindable_                                                                                  | `HTMLInputElement` &#124; `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` &#124; `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` &#124; `null`                                     |                      | The DOM reference of the flyout holding the suggestion list.                                                                                                                                                                                      |
| `flyoutProps`                                                                                     | `FlyoutProps`                                                   |                      | The props to spread on the flyout.                                                                                                                                                                                                                |
| `listViewRef` _bindable_                                                                          | `HTMLUListElement` &#124; `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`                      |                                                                 |                      |                                                                                                                                                                                                                                                   |

<!-- /props:AutoSuggestBoxProps -->

## AutoSuggestBoxOption Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:AutoSuggestOptionProps -->

| Name                                            | Type                          | Default | 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` &#124; `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` |                               |         |                                                                                                                               |

<!-- /props:AutoSuggestOptionProps -->

---

# Avatar

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An Avatar is a graphical representation of a user, team, or entity.

Avatar can display an image, icon, or initials, and supports different sizes, shapes, and status indicators.

## Usage

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

<Avatar size={40} name="FluentUI Svelte" />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Image

An avatar can display an image. It is recommended to also include a name in addition to the image: the initials from the name are displayed while the image is loading, and the name makes the Avatar accessible to screen readers.

```svelte
<Avatar
	active="active"
	size={56}
	name="FluentUI Svelte"
	image={{ src: 'https://placehold.co/120x120/jpeg' }}
	badge={{ status: 'do-not-disturb' }}
/>
```

### Icon

An avatar can display an icon. The icon will only be shown when there is no image or initials available.

```svelte
<script>
	import ClockRegular from 'fluentui-icons-svelte/ClockRegular.svelte';
</script>

<Avatar active="active" size={56} name="FluentUI Svelte" icon={ClockRegular} color="information" />
```

### Badge

An avatar can have a badge to indicate presence status. See the PresenceBadge component for more info.

```svelte
<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} />
```

### Shape

An avatar can have a square, circular, or rounded shape.

```svelte
<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} />
<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} shape="rounded" />
<Avatar active="active" size={56} name="FluentUI Svelte" badge={{ status: 'available' }} shape="square" />
```

### Color: colorful

An avatar can have its color automatically picked based on the name prop, or idForColor can be used if a name is not available.

```svelte
<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
<Avatar active="active" size={56} name="FluentUI Svelte" color="colorful" />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:AvatarProps -->

| Name               | Type                                                                           | Default       | Description                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------- |
| `name`             | `string`                                                                       | `'Avatar'`    | The name of the person or entity represented by this Avatar. This should always be provided if it is available. |
| `image`            | `{ src: string; }`                                                             |               | The Avatar's image                                                                                              |
| `ref` _bindable_   | `HTMLDivElement` &#124; `null`                                                 |               | The DOM reference of the avatar element.                                                                        |
| `size`             | `number`                                                                       | `48`          | Size of the avatar in pixels.                                                                                   |
| `shape`            | `'circular'` &#124; `'rounded'` &#124; `'square'`                              | `'circular'`  | The avatar can have a circular, rounded or square shape.                                                        |
| `color`            | [`Colors`](https://fluentui-svelte.dev/docs/types/#colors) &#124; `'colorful'` | `'attention'` | The color when displaying either an icon or initials. For now it only supports system colors (plus colorful).   |
| `active`           | `'active'` &#124; `'inactive'`                                                 |               | Optional activity indicator                                                                                     |
| `activeAppearance` | `'ring'` &#124; `'shadow'` &#124; `'ring-shadow'`                              | `'ring'`      | The appearance when `active="active"`                                                                           |
| `initials`         | `string`                                                                       | `name`        | Custom initials by default they will be derived from the `name` prop.                                           |
| `idForColor`       | `string`                                                                       |               | Specify a string to be used instead of the name, to determine which color to use when color="colorful".         |
| `icon`             | `Snippet` &#124; `Component`                                                   |               | Icon to be displayed when the avatar doesn't have an image or initials.                                         |
| `badge`            | `BadgePresence`                                                                |               | The badge to display as a status indicator. (you can use with a custom icon)                                    |
| HTML Attributes    |                                                                                |               |                                                                                                                 |

<!-- /props:AvatarProps -->

---

# Badge

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A badge is a visual decoration for UI elements used to display notifications, status indicators, or counts. It supports different colors and styles to match various UI needs.

## Usage

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

<Badge>36</Badge>
```

## Badge API

A brief explanation of the props that really need explaining. You can see the rest of the props here.

## Examples

### Appearance

Use the appearance prop to switch between filled, outline, tint, and ghost styles.

```svelte
<Badge size={46} color="attention">5</Badge>
<Badge size={46} color="attention" appearance="outline">5</Badge>
<Badge size={46} color="attention" appearance="tint">5</Badge>
<Badge size={46} color="attention" appearance="ghost">5</Badge>
```

### Sizes

Use the size prop to control the badge dimensions.

```svelte
<Badge size={42} color="attention">46</Badge>
<Badge size={56} color="attention">56</Badge>
<Badge size={64} color="attention">64</Badge>
<Badge size={96} color="attention">96</Badge>
```

### Shapes

Use the shape prop to render circular, rounded, or square badges.

```svelte
<Badge size={36} color="attention">36</Badge>
<Badge size={36} color="attention" shape="rounded">36</Badge>
<Badge size={36} color="attention" shape="square">36</Badge>
```

### Color

Use the color prop to communicate different statuses and priorities.

```svelte
<Badge size={36} color="information">I</Badge>
<Badge size={36} color="attention">A</Badge>
<Badge size={36} color="warning">W</Badge>
<Badge size={36} color="critical">C</Badge>
<Badge size={36} color="success">S</Badge>
```

### Icon

Use the icon prop to render an icon inside the badge. You can pass the icon as a snippet or as a component.

> **Only icon?** If you use this component and notice padding between the wrapper and the icon, use the BadgeIcon component instead to avoid it.

```svelte
<script>
	import { Badge } from 'fluentui-svelte';
	import AccessibilityRegular from 'fluentui-icons-svelte/AccessibilityRegular.svelte';
</script>

<Badge color="attention" size={96} icon={AccessibilityRegular} />
```

## Badge Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BadgeProps -->

| Name             | Type                                                           | Default         | Description                                                                               |
| ---------------- | -------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| `size`           | `number`                                                       | `20`            | The size of the badge in pixels.                                                          |
| `shape`          | `'circular'` &#124; `'rounded'` &#124; `'square'`              | `'circular'`    | The badge can have a circular, rounded or square shape.                                   |
| `appearance`     | `'filled'` &#124; `'outline'` &#124; `'ghost'` &#124; `'tint'` | `'filled'`      | The badge can have its background and border styled for greater emphasis or to be subtle. |
| `iconPosition`   | `'before'` &#124; `'after'`                                    | `'before'`      | The position of the icon relative to the badge content.                                   |
| `color`          | [`Colors`](https://fluentui-svelte.dev/docs/types/#colors)     | `'information'` | The color of the badge. For now it only supports system colors.                           |
| `icon`           | `Snippet` &#124; `Component`                                   |                 | Icon to render inside the badge.                                                          |
| `ref` _bindable_ | `HTMLSpanElement` &#124; `null`                                |                 | The DOM reference of the badge element.                                                   |
| HTML Attributes  |                                                                |                 |                                                                                           |

<!-- /props:BadgeProps -->

## BadgeIcon API

This component is useful when you want to show an icon in the form of a Badge somewhere in your app.

### Usage

```svelte
<script>
	import { BadgeIcon } from 'fluentui-svelte';
	import AccessibilityRegular from 'fluentui-icons-svelte/AccessibilityRegular.svelte';
</script>

<BadgeIcon size={96} icon={AccessibilityRegular} />
```

One example is using this component inside Avatar:

By default, Avatar uses an instance of BadgeIcon. As you can see, the first example on the left uses the Badge component, which adds unwanted padding inside it. In Avatar, you can use one of the predefined BadgeIcon options, or set a custom icon by passing it as a property. When you use the component option, the styles are applied automatically, but with #snippet you need to make sure you pass the arguments to the icon like this:

```svelte
<script>
	import { Avatar, Badge } from 'fluentui-svelte';
	import AccessibilityRegular from 'fluentui-icons-svelte/AccessibilityRegular.svelte';
</script>

<!-- args: [size: number, shape: string] -->
{#snippet customBadge(args)}
	<Badge color="attention" size={args.width} aria-hidden={args['aria-hidden']} icon={AccessibilityRegular} />
{/snippet}

<Avatar active="active" size={96} name="FluentUI Svelte" badge={{ icon: customBadge }} />
```

### BadgeIcon Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BadgeIconProps -->

| Name             | Type                                                           | Default       | Description                                                                        |
| ---------------- | -------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------- |
| `status`         | [`Statuses`](https://fluentui-svelte.dev/docs/types/#statuses) | `'available'` | The presence status to display. It picks both the icon and the color of the badge. |
| `outOfOffice`    | `boolean`                                                      | `false`       | Decorates the presence icon to signal that the person is out of office.            |
| `size`           | `number`                                                       | `20`          | The size of the badge in pixels.                                                   |
| `color`          | [`Colors`](https://fluentui-svelte.dev/docs/types/#colors)     |               | Overrides the color the status would pick on its own.                              |
| `icon`           | `Snippet` &#124; `Component`                                   |               | Custom icon, rendered instead of the one the status would pick on its own.         |
| `ref` _bindable_ | `HTMLSpanElement` &#124; `null`                                |               | The DOM reference of the badge element.                                            |
| HTML Attributes  |                                                                |               |                                                                                    |

<!-- /props:BadgeIconProps -->

---

# Breadcrumb

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A breadcrumb shows where a page sits in the hierarchy above it, and gives the reader a way back up. It renders a `nav` landmark around an ordered list, so a screen reader can jump straight to it.

The landmark names itself `Breadcrumb`, the trail is an `ol` so its order is part of the markup rather than of the styling, the last step carries `aria-current="page"`, and the dividers are held out of the accessibility tree — a trail of three steps reads as three, not as five. Every one of those can be overridden: pass your own `aria-label`, or an `aria-labelledby`, and the default steps aside.

To create a breadcrumb, you will need to use the following components:

- `Breadcrumb`: The landmark and the list. It creates the context the rest read.
- `BreadcrumbItem`: One step of the trail — the list item the step lives in. It takes anything, not only a step.
- `BreadcrumbButton`: A step that can be activated: an anchor when it goes somewhere, a button when it does something.
- `BreadcrumbDivider`: The mark between two steps. It is decoration, and is hidden from assistive technology.

## Usage

A breadcrumb is a list of steps with a divider between them. The last step is the page the reader is already on, so it is marked `current` rather than linked away.

```svelte
<script>
	import { Breadcrumb, BreadcrumbItem, BreadcrumbButton, BreadcrumbDivider } from 'fluentui-svelte';
</script>

<Breadcrumb>
	<BreadcrumbItem>
		<BreadcrumbButton as="a" href="/">Home</BreadcrumbButton>
	</BreadcrumbItem>
	<BreadcrumbDivider />
	<BreadcrumbItem>
		<BreadcrumbButton as="a" href="/files">Files</BreadcrumbButton>
	</BreadcrumbItem>
	<BreadcrumbDivider />
	<BreadcrumbItem>
		<BreadcrumbButton current>Quarterly report</BreadcrumbButton>
	</BreadcrumbItem>
</Breadcrumb>
```

## Examples

### Size

`size` sets the type, the height and the divider of every step at once.

```svelte
<Breadcrumb size="small">...</Breadcrumb>
<Breadcrumb size="medium">...</Breadcrumb>
<Breadcrumb size="large">...</Breadcrumb>
```

### Icon

`icon` takes a snippet or a component and renders it beside the label, on the side `iconPosition` asks for.

```svelte
<BreadcrumbItem>
	<BreadcrumbButton as="a" href="/files" icon={FolderRegular}>Files</BreadcrumbButton>
</BreadcrumbItem>
```

### Current Step

`current` marks the step as the page the trail ends at. It announces `aria-current="page"` and reads as text rather than as a way out, so the last step does not offer to take the reader where they already are.

```svelte
<BreadcrumbItem>
	<BreadcrumbButton current>Quarterly report</BreadcrumbButton>
</BreadcrumbItem>
```

### Overflow Menu

A step takes whatever you put in it, so a long trail folds its middle into a menu by making that menu a step of its own. Which steps fold is your call — slice the list wherever the layout needs it.

```svelte
<script>
	// Keep the root and the last two steps; everything between them goes into the menu.
	const head = trail.slice(0, 1);
	const folded = trail.slice(1, -2);
	const tail = trail.slice(-2);
</script>

<Breadcrumb>
	{#each head as item (item.name)}
		<BreadcrumbItem>
			<BreadcrumbButton as="a" href={item.href}>{item.name}</BreadcrumbButton>
		</BreadcrumbItem>
		<BreadcrumbDivider />
	{/each}

	<BreadcrumbItem>
		<Menu>
			<MenuTrigger>
				{#snippet children({ state, menuTriggerProps })}
					<Button bind:ref={state.ref} {...menuTriggerProps} appearance="subtle" aria-label="More steps">
						<MoreHorizontalRegular />
					</Button>
				{/snippet}
			</MenuTrigger>
			<MenuPopover>
				<MenuList>
					<!-- A step that goes somewhere is a link, in the menu as much as in the trail. -->
					{#each folded as item (item.name)}
						<MenuItem href={item.href}>{item.name}</MenuItem>
					{/each}
				</MenuList>
			</MenuPopover>
		</Menu>
	</BreadcrumbItem>
	<BreadcrumbDivider />

	{#each tail as item (item.name)}
		<BreadcrumbItem>
			<BreadcrumbButton current>{item.name}</BreadcrumbButton>
		</BreadcrumbItem>
	{/each}
</Breadcrumb>
```

The label on the menu button is yours to write, and it is worth writing: a trigger with only an icon says nothing to a screen reader. Note also that what lives inside a `MenuPopover` is not rendered until the menu opens, so the folded steps are not in the HTML a crawler reads.

### Focus Mode

`focusMode` decides how the focus walks the trail. `tab`, the default, leaves every step its own tab stop, which is what a reader expects of a row of links. `arrow` gives the whole trail a single tab stop and moves between steps with the arrow keys, with `Home` and `End` for the ends.

```svelte
<Breadcrumb focusMode="arrow">...</Breadcrumb>
```

## Component Props (Breadcrumb)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BreadcrumbProps -->

| Name                 | Type                                         | Default    | Description                                                                                                                                                |
| -------------------- | -------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_     | `HTMLElement` &#124; `null`                  |            | The DOM reference of the `nav`.                                                                                                                            |
| `listRef` _bindable_ | `HTMLOListElement` &#124; `null`             |            | The DOM reference of the list.                                                                                                                             |
| `listAttributes`     | `HTMLOlAttributes`                           |            | The attributes to spread on the list element.                                                                                                              |
| `size`               | `'small'` &#124; `'medium'` &#124; `'large'` | `'medium'` | The size of every step and divider of the trail.                                                                                                           |
| `focusMode`          | `'tab'` &#124; `'arrow'`                     | `'tab'`    | How the focus walks the trail: `tab` leaves every step its own tab stop, `arrow` gives the trail a single one and moves between steps with the arrow keys. |
| Element Attributes   |                                              |            |                                                                                                                                                            |

<!-- /props:BreadcrumbProps -->

## Component Props (BreadcrumbItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BreadcrumbItemProps -->

| Name                      | Type                          | Default | Description                    |
| ------------------------- | ----------------------------- | ------- | ------------------------------ |
| `ref` _bindable_          | `HTMLLIElement` &#124; `null` |         | The DOM reference of the item. |
| Element Attributes (`li`) |                               |         |                                |

<!-- /props:BreadcrumbItemProps -->

## Component Props (BreadcrumbButton)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BreadcrumbButtonProps -->

| Name                | Type                              | Default    | Description                                                                                            |
| ------------------- | --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `ref` _bindable_    | `BreadcrumbItemElementDOMType[T]` |            | The DOM reference of the step.                                                                         |
| `as`                | `'button'` &#124; `'a'`           | `'button'` | The DOM element to render. A step that goes somewhere is an anchor and takes `href`.                   |
| `icon`              | `Snippet` &#124; `Component`      |            | The icon to display beside the label.                                                                  |
| `iconPosition`      | `'before'` &#124; `'after'`       | `'before'` | Which side of the label the icon sits on.                                                              |
| `current`           | `boolean`                         | `false`    | Marks the step as the page the trail ends at, which is what `aria-current` announces.                  |
| `disabled`          | `boolean`                         |            | Disables the user interaction.                                                                         |
| `disabledFocusable` | `boolean`                         | `false`    | Keeps a disabled step focusable, so the tab order stays the same for a keyboard or screen reader user. |
| HTML Attributes     |                                   |            |                                                                                                        |

<!-- /props:BreadcrumbButtonProps -->

## Component Props (BreadcrumbDivider)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:BreadcrumbDividerProps -->

| Name                      | Type                          | Default | Description                       |
| ------------------------- | ----------------------------- | ------- | --------------------------------- |
| `ref` _bindable_          | `HTMLLIElement` &#124; `null` |         | The DOM reference of the divider. |
| Element Attributes (`li`) |                               |         |                                   |

<!-- /props:BreadcrumbDividerProps -->

## Accessibility

The landmark is named `Breadcrumb` by default, which is what a screen reader announces when jumping to it. Give it your own `aria-label` when a page carries more than one trail, so each is distinguishable, or an `aria-labelledby` pointing at a heading you already render — the default steps aside for both.

The dividers are decoration and are hidden, so the list reads as the number of steps it has. The last step carries `aria-current="page"`. A step with an icon and no label needs an `aria-label` of its own.

Structured data is left to you. A breadcrumb is one of the few components a search engine reads directly, through `BreadcrumbList` from schema.org, but the text of a step lives in your markup and the URLs live in your routing — so the trail you publish is yours to build, in whichever shape your site already uses.

---

# Button

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A button triggers an action or event when activated and supports three visual appearances: accent, standard, and subtle.

## Usage

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

<Button>I am a Button</Button>
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### As

You can control which tag the button component should use: button, a, or div.

```svelte
<Button>I am a Button</Button>
<Button as="a" href="/">I am a Anchor</Button>
<Button as="div">I am a Div</Button>
```

### Shape

A button can be rounded, circular, or square. Default: rounded.

```svelte
<Button shape="circular" />
<Button />
<Button shape="square" />
```

### Appearance

A button can have its content and borders styled for greater emphasis or to be subtle.

```svelte
<Button appearance="accent" />
<Button appearance="standard" />
<Button appearance="subtle" />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ButtonProps -->

| Name                | Type                                              | Default     | Description                                                                            |
| ------------------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `ref` _bindable_    | `ButtonElementDOMType[T]`                         |             | The DOM reference of the button element.                                               |
| `as`                | `'button'` &#124; `'a'` &#124; `'div'`            | `'button'`  | The DOM element to render.                                                             |
| `disabled`          | `boolean`                                         |             | Disables the user interaction.                                                         |
| `shape`             | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'` | A button can be rounded, circular, or square.                                          |
| `appearance`        | `'accent'` &#124; `'standard'` &#124; `'subtle'`  | `'accent'`  | A button can have its content and borders styled for greater emphasis or to be subtle. |
| `disabledFocusable` | `boolean`                                         | `false`     | When set, allows the button to be focusable even when it has been disabled.            |
| `isMenuButton`      | `boolean`                                         |             | Add an icon that indicates the button triggers a menu.                                 |
| `indicatorPosition` | `'before'` &#124; `'after'`                       | `'after'`   | Position of the menu indicator relative to the button content.                         |
| `indicatorIcon`     | `Snippet` &#124; `Component`                      |             | The icon used to indicate the button triggers a menu.                                  |
| HTML Attributes     |                                                   |             |                                                                                        |

<!-- /props:ButtonProps -->

## Split Button

A split button is a special type of button that combines a standard button with a menu button to provide users with a primary action and additional options.

### Usage

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

<SplitButton menuTriggerProps={{ 'aria-label': 'More options' }} />
<SplitButton appearance="standard" menuTriggerProps={{ 'aria-label': 'More options' }} />
<SplitButton appearance="subtle" menuTriggerProps={{ 'aria-label': 'More options' }} />
<SplitButton shape="circular" menuTriggerProps={{ 'aria-label': 'More options' }} />
<SplitButton shape="circular" appearance="standard" menuTriggerProps={{ 'aria-label': 'More options' }} />
<SplitButton shape="circular" appearance="subtle" menuTriggerProps={{ 'aria-label': 'More options' }} />
```

### Adding a Menu

To add a menu to the split button, please refer to the Menu documentation for details on how to create menus and pass them as a prop to the SplitButton component.

### Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SplitButtonProps -->

| Name                          | Type                                              | Default     | Description                                                                                                |
| ----------------------------- | ------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `appearance`                  | `'accent'` &#124; `'standard'` &#124; `'subtle'`  | `'accent'`  | Both buttons can have their content and borders styled for greater emphasis or to be subtle.               |
| `shape`                       | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'` | Both buttons can be rounded, circular, or square.                                                          |
| `disabled`                    | `boolean`                                         | `false`     | Disables the user interaction on both buttons.                                                             |
| `primaryButtonProps`          | `ButtonProps`                                     |             | The props to spread on the primary button.                                                                 |
| `menuTriggerProps`            | `ButtonProps`                                     |             | The props to spread on the button that opens the menu. It shows only an arrow, so give it an `aria-label`. |
| `wrapperRef` _bindable_       | `HTMLDivElement` &#124; `null`                    |             | The DOM reference of the element wrapping both buttons.                                                    |
| `primaryButtonRef` _bindable_ | `HTMLButtonElement` &#124; `null`                 |             | The DOM reference of the primary button.                                                                   |
| `menuTriggerRef` _bindable_   | `HTMLButtonElement` &#124; `null`                 |             | The DOM reference of the button that opens the menu.                                                       |
| HTML Attributes               |                                                   |             |                                                                                                            |

<!-- /props:SplitButtonProps -->

---

# Calendar Date Picker

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A button trigger paired with a CalendarView popup for selecting a single date.

## Usage

```svelte
<script>
	import { CalendarDatePicker } from 'fluentui-svelte';

	let value = $state(null);
</script>

<CalendarDatePicker bind:value />
```

## Component API

The `CalendarDatePicker` combines a button trigger with a `CalendarView` popup. Clicking the trigger opens the calendar, and selecting a day updates the bound `value` and closes the popup. Because it builds on `CalendarView`, calendar props such as `blackoutDates`, `minDate`, `maxDate`, `weekStart` and `headers` are forwarded straight to the popup calendar.

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CalendarDatePickerProps -->

| Name                                                                                                      | Type                                                | Default                                                 | Description                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrapperRef` _bindable_                                                                                   | `HTMLDivElement` &#124; `null`                      |                                                         | The DOM reference of the wrapper element.                                                                                                                                                                                                    |
| `value` _bindable_                                                                                        | `Date` &#124; `null`                                | `null`                                                  | The selected date.                                                                                                                                                                                                                           |
| `format`                                                                                                  | `Intl.DateTimeFormatOptions`                        | `{ year: 'numeric', month: 'numeric', day: 'numeric' }` | The options used to format the date rendered on the trigger. When rendering on the server, give it the `timeZone` of the visitor: the calendar picks dates at the visitor's midnight, and the server would format them in its own time zone. |
| `calendarPosition`                                                                                        | `Partial<ComputePositionConfig>`                    |                                                         | The floating UI configuration object of the calendar popup. Keys left out keep their default.                                                                                                                                                |
| `onChange`                                                                                                | `(event: Event, value: Date` &#124; `null) => void` |                                                         | Called whenever the selected date changes.                                                                                                                                                                                                   |
| `popupLabel`                                                                                              | `string`                                            | `'Choose a date'`                                       | The accessible name of the calendar popup, which is announced as a dialog.                                                                                                                                                                   |
| `ref` _bindable_                                                                                          | `HTMLInputElement` &#124; `null`                    |                                                         | The DOM reference of the native date input that holds the value, as `YYYY-MM-DD`. The other attributes of the picker are applied to it.                                                                                                      |
| `buttonRef` _bindable_                                                                                    | `HTMLButtonElement` &#124; `null`                   |                                                         | The DOM reference of the button that opens the calendar.                                                                                                                                                                                     |
| `buttonProps`                                                                                             | `ButtonProps`                                       |                                                         | The props to spread on the `Button` that opens the calendar.                                                                                                                                                                                 |
| `wrapperAttributes`                                                                                       | `HTMLAttributes`                                    |                                                         | The attributes to spread on the wrapper element.                                                                                                                                                                                             |
| `popupRef` _bindable_                                                                                     | `HTMLDivElement` &#124; `null`                      |                                                         | The DOM reference of the calendar popup.                                                                                                                                                                                                     |
| `locale`, `blackoutDates`, `headers`, `minDate`, `maxDate`, `today`, `weekStart` from `CalendarViewProps` |                                                     |                                                         |                                                                                                                                                                                                                                              |
| `NativeFieldAttributes<HTMLInputAttributes>`                                                              |                                                     |                                                         |                                                                                                                                                                                                                                              |

<!-- /props:CalendarDatePickerProps -->

`locale`, `blackoutDates`, `headers`, `minDate`, `maxDate` and `weekStart` are forwarded
straight to the underlying `CalendarView`. Button HTML attributes, including `id`, `class` and ARIA attributes, are forwarded to the
trigger. Use `wrapperAttributes` and `wrapperRef` for the root element.

---

# Calendar View

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An inline calendar for browsing days, months, and years and selecting one date, several
dates, or a range.

## Usage

```svelte
<script>
	import { CalendarView } from 'fluentui-svelte';

	let value = $state(null);
</script>

<CalendarView bind:value onChange={(e, selection) => console.log(selection)} />
```

## Examples

### Multiple Selection

Set `selectionMode` to `multiple` to allow selecting more than one date. `value` then
holds an array.

```svelte
<CalendarView selectionMode="multiple" />
```

### Range Selection

Set `selectionMode` to `range` to pick a start and an end. The range has its own binding
rather than sharing `value`, and `end` stays `null` between the two clicks so you can
tell a half-built range from a range of a single day.

```svelte
<script>
	let range = $state({ start: null, end: null });
</script>

<CalendarView selectionMode="range" bind:range />
```

A range spans blacked-out dates by default, since a blackout usually marks a day that
cannot be _picked_ rather than one that breaks the period. Set `blackoutBreaksRange`
for the range to stop at the first blackout.

```svelte
<CalendarView selectionMode="range" bind:range {blackoutDates} blackoutBreaksRange />
```

### Week Start

Use the `weekStart` prop to change the first day of the week (0 = Sunday, 1 = Monday).

```svelte
<CalendarView weekStart={0} />
```

## Keyboard

The grid is driven by [Tabspot](https://github.com/JLAcostaEC/tabspot): the calendar
registers its table as a grid mover and only adds the paging on top of it.

| Key                        | Action                                                      |
| -------------------------- | ----------------------------------------------------------- |
| `ArrowLeft` / `ArrowRight` | Previous / next cell, continuing into the neighbouring row. |
| `ArrowUp` / `ArrowDown`    | Same column, one row up / down.                             |
| `Home` / `End`             | First / last cell of the current row.                       |
| `Ctrl` + `ArrowUp`         | Zoom out: days to months, months to years.                  |
| `Ctrl` + `ArrowDown`       | Zoom in: years to months.                                   |
| `Delete` / `Backspace`     | Clear the range. Range selection only.                      |

Moving past the edge of the visible month, year or decade turns the page and keeps
focus on the date you moved to. Dates outside `minDate`/`maxDate` cannot be focused,
and `blackoutDates` are stepped over.

Focus follows the grid. Opening the calendar as a popup (`floating`) puts focus on the
selected date, on today, or on the first date of the page, in that order; an inline
calendar never takes focus on its own. Changing the view from a cell — `Ctrl` + arrow,
or picking a month or year — carries focus to the matching cell of the new view, while
changing it from the header button leaves focus on the button.

## CalendarView Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CalendarViewProps -->

| Name                       | Type                                                                | Default                      | Description                                                                                                                                                                                                                                                                                           |
| -------------------------- | ------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null`                                      |                              | The DOM reference of the calendar element.                                                                                                                                                                                                                                                            |
| `value` _bindable_         | `Date` &#124; `Date[]` &#124; `null`                                | `null`                       | The selected date, or an array of dates when `selectionMode` is `'multiple'`. Unused by `'range'`.                                                                                                                                                                                                    |
| `selectionMode`            | `'single'` &#124; `'multiple'` &#124; `'range'`                     | `'single'`                   | How many dates the grid hands out, and in what shape.                                                                                                                                                                                                                                                 |
| `range` _bindable_         | `{ start: Date` &#124; `null; end: Date` &#124; `null; }`           | `{ start: null, end: null }` | The picked range. Only read and written when `selectionMode` is `'range'`, and `end` stays `null` until the range is closed.                                                                                                                                                                          |
| `blackoutBreaksRange`      | `boolean`                                                           | `false`                      | Stop a range from spanning a blacked-out date.                                                                                                                                                                                                                                                        |
| `blackoutDates`            | `Date[]`                                                            |                              | Dates that are rendered but cannot be selected.                                                                                                                                                                                                                                                       |
| `headers`                  | `boolean`                                                           |                              | Labels the first cell of a month or a year with its name.                                                                                                                                                                                                                                             |
| `minDate`                  | `Date`                                                              |                              | The earliest selectable date.                                                                                                                                                                                                                                                                         |
| `maxDate`                  | `Date`                                                              |                              | The latest selectable date.                                                                                                                                                                                                                                                                           |
| `today`                    | `Date`                                                              | `new Date()`                 | The date the view treats as today: it is highlighted, and the view opens on its month when there is no `value`. Pass it when rendering on the server, built from a year, month and day on both sides, as in `new Date(2024, 2, 5)`: the same instant falls on different days in different time zones. |
| `view`                     | `'days'` &#124; `'months'` &#124; `'years'`                         | `'days'`                     | The calendar page the view opens on.                                                                                                                                                                                                                                                                  |
| `locale`                   | `string`                                                            | `'en-US'`                    | The locale used to format weekday and month names.                                                                                                                                                                                                                                                    |
| `weekStart`                | `number`                                                            | `1`                          | The first day of the week, where 0 is Sunday.                                                                                                                                                                                                                                                         |
| `floating`                 | `CalendarViewFloating`                                              |                              | Renders the calendar as a popup anchored to a reference element instead of inline.                                                                                                                                                                                                                    |
| `onChange`                 | `(event: Event, value: Date` &#124; `Date[]` &#124; `null) => void` |                              | Called whenever the selection changes. Not called in `'range'` mode.                                                                                                                                                                                                                                  |
| `onRangeChange`            | `(event: Event, range: CalendarDateRange) => void`                  |                              | Fired on every step of a range, including the one that leaves `end` null.                                                                                                                                                                                                                             |
| `onViewChange`             | `(event: Event, view: View) => void`                                |                              | Called whenever the active calendar page changes.                                                                                                                                                                                                                                                     |
| Element Attributes (`div`) |                                                                     |                              |                                                                                                                                                                                                                                                                                                       |

<!-- /props:CalendarViewProps -->

All `div` HTML attributes are forwarded to the root element.

## CalendarViewItem Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CalendarViewItemProps -->

| Name                       | Type                                        | Default | Description                                                                                |
| -------------------------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `selected`                 | `boolean`                                   |         | Renders the cell as the selected one.                                                      |
| `disabled`                 | `boolean`                                   |         | Disables the user interaction.                                                             |
| `current`                  | `boolean`                                   |         | Marks the cell as the current date.                                                        |
| `outOfRange`               | `boolean`                                   |         | Renders the cell as belonging to a neighbouring page.                                      |
| `blackout`                 | `boolean`                                   |         | Renders the cell as blacked out, so it reads as unavailable rather than disabled.          |
| `rangePosition`            | `'start'` &#124; `'between'` &#124; `'end'` |         | Set on the days a range covers, which paints the band behind them.                         |
| `header`                   | `string`                                    |         | A small label rendered above the cell content.                                             |
| `variant`                  | `'day'` &#124; `'monthYear'`                | `'day'` | Which shape the cell takes: a circle for a day, a rounded rectangle for a month or a year. |
| `children`                 | `Snippet`                                   |         | The content of the cell.                                                                   |
| `buttonAttributes`         | `HTMLButtonAttributes`                      |         | The attributes to spread on the inner button element.                                      |
| Element Attributes (`div`) |                                             |         |                                                                                            |

<!-- /props:CalendarViewItemProps -->

All `div` HTML attributes are forwarded to the cell element.

---

# Card

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A card is a container that groups content and actions about a single topic, and can optionally be selected.

## Usage

```svelte
<script>
	import { Card, CardPreview, CardHeader, CardFooter, Button } from 'fluentui-svelte';
</script>

{#snippet footerActions()}
	<Button>Like</Button>
	<Button appearance="standard">Share</Button>
{/snippet}

<Card orientation="vertical">
	<CardPreview logoSrc="/logo.png">
		<img src="/preview.png" alt="Preview" />
	</CardPreview>
	<CardHeader title="FluentUI Svelte" description="5h ago · About us - Overview" />
	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
	<CardFooter action={footerActions} />
</Card>
```

## Component API

A card is built out of the following components:

- `Card`: the root component. It creates all the state, provides context to its parts and handles the selection.
- `CardPreview`: the media shown at one edge of the card, with an optional logo overlaid on it.
- `CardHeader`: the title of the card, with an optional image, description and action.
- `CardFooter`: the actions shown at the bottom of the card.

`CardPreview`, `CardHeader` and `CardFooter` read the card context, so they throw when rendered outside a `Card`.
They are all optional, and the card renders any other content passed to it as is.

The following combinations are rejected at runtime, because they cannot be resolved visually:

- `showFloatingAction` without `selectable`.
- `selected` without `selectable`.
- `as="a"` together with `selectable`.
- `action` on `CardHeader` or `CardFooter` inside a selectable card.

## Examples

### Appearance

A card can have its background and borders styled for greater emphasis or to be subtle.

```svelte
<Card appearance="filled">Filled</Card>
<Card appearance="outlined">Outlined</Card>
<Card appearance="subtle">Subtle</Card>
```

### Orientation

A card lays its parts out horizontally by default. Set `orientation` to `vertical` to stack them instead.

```svelte
<Card orientation="horizontal">
	<CardPreview logoSrc="/logo.png">
		<img src="/preview.png" alt="Preview" />
	</CardPreview>
	<CardHeader title="Horizontal" description="The default orientation" />
</Card>

<Card orientation="vertical">
	<CardPreview logoSrc="/logo.png">
		<img src="/preview.png" alt="Preview" />
	</CardPreview>
	<CardHeader title="Vertical" description="Stacks every part" />
</Card>
```

### Selection

A selectable card toggles its selection when clicked anywhere, and reports it through `onSelectionChange`. Set
`showFloatingAction` to float a checkbox over the top right corner.

```svelte
<script>
	let selected = $state(false);
</script>

<Card selectable showFloatingAction bind:selected onSelectionChange={(id, selected) => console.log(id, selected)}>
	<CardHeader title="Selectable card" description={selected ? 'Selected' : 'Not selected'} />
</Card>
```

### Header

The header takes a `title`, and optionally an `image`, a `description` and an `action`. A string title renders inside
a heading; a snippet or a component receives the id the floating checkbox is labelled by.

```svelte
<script>
	import { Card, CardHeader, Button } from 'fluentui-svelte';
	import MoreHorizontalRegular from 'fluentui-icons-svelte/MoreHorizontalRegular.svelte';
</script>

{#snippet title(attrs)}
	<h4 class="body" {...attrs}><b>FluentUI Svelte</b> mentioned you</h4>
{/snippet}

{#snippet action()}
	<Button appearance="subtle" aria-label="More actions"><MoreHorizontalRegular width="1em" height="1em" /></Button>
{/snippet}

<Card>
	<CardHeader image="/logo.png" {title} description="5h ago · About us - Overview" {action} />
</Card>
```

### Preview

The preview holds the media of the card and rounds the corners it sits against. The `logoSrc` prop overlays a logo on
the bottom left corner.

```svelte
<Card orientation="vertical">
	<CardPreview logoSrc="/logo.png">
		<img src="/preview.png" alt="Preview" />
	</CardPreview>
</Card>
```

### Footer

The footer renders the actions of the card at the bottom, spread across the available width.

```svelte
<script>
	import { Card, CardHeader, CardFooter, Button } from 'fluentui-svelte';
</script>

{#snippet action()}
	<Button>Like</Button>
	<Button appearance="standard">Share</Button>
{/snippet}

<Card orientation="vertical">
	<CardHeader title="FluentUI Svelte" description="5h ago · About us - Overview" />
	<CardFooter {action} />
</Card>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CardProps -->

| Name                  | Type                                                       | Default        | Description                                                                             |
| --------------------- | ---------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `ref` _bindable_      | `CardElementDOMType[Tag]`                                  |                | The DOM reference of the card element.                                                  |
| `as`                  | `'div'` &#124; `'article'` &#124; `'section'` &#124; `'a'` | `'div'`        | The DOM element to render.                                                              |
| `orientation`         | `'horizontal'` &#124; `'vertical'`                         | `'horizontal'` | The axis the card lays its parts out on.                                                |
| `selectable`          | `boolean`                                                  | `false`        | Lets the user select the card by clicking anywhere on it.                               |
| `showFloatingAction`  | `boolean`                                                  | `false`        | Floats the selection checkbox over the top right corner of the card.                    |
| `id`                  | `string`                                                   |                | The id of the card element. Falls back to a generated one.                              |
| `selected` _bindable_ | `boolean`                                                  | `false`        | Whether the card is selected. Only available on selectable cards.                       |
| `disabled`            | `boolean`                                                  | `false`        | Disables the user interaction.                                                          |
| `appearance`          | `'filled'` &#124; `'outlined'` &#124; `'subtle'`           | `'filled'`     | A card can have its background and borders styled for greater emphasis or to be subtle. |
| `onSelectionChange`   | `(id: string, selected: boolean) => void`                  |                | Called with the id of the card whenever its selection changes.                          |
| HTML Attributes       |                                                            |                |                                                                                         |

<!-- /props:CardProps -->

## CardPreview

The media shown at one edge of the card, with an optional logo overlaid on it.

### Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CardPreviewProps -->

| Name                                                | Type                           | Default | Description                                                                             |
| --------------------------------------------------- | ------------------------------ | ------- | --------------------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLDivElement` &#124; `null` |         | The DOM reference of the preview element.                                               |
| `logoSrc`                                           | `string`                       |         | The URL of the logo overlaid on the bottom left corner of the preview.                  |
| `logoAlt`                                           | `string`                       | `''`    | The alternative text of the logo. Empty by default, which marks the logo as decorative. |
| `children`                                          | `Snippet`                      |         | The media to preview, usually an image.                                                 |
| `HTMLAttributes<HTMLDivElement>` without `children` |                                |         |                                                                                         |

<!-- /props:CardPreviewProps -->

## CardHeader

The title of the card, with an optional image, description and action.

### Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CardHeaderProps -->

| Name                                                         | Type                                                       | Default | Description                                                                                           |
| ------------------------------------------------------------ | ---------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                             | `HTMLDivElement` &#124; `null`                             |         | The DOM reference of the header element.                                                              |
| `title`                                                      | `Snippet` &#124; `Component` &#124; `string`               |         | The title of the card. A snippet or a component receives the id the floating checkbox is labelled by. |
| `headingLevel`                                               | `1` &#124; `2` &#124; `3` &#124; `4` &#124; `5` &#124; `6` | `4`     | The level of the heading that holds a string title, to fit the headings of the page around it.        |
| `image`                                                      | `Snippet` &#124; `Component` &#124; `string`               |         | The image rendered before the title. A string is used as the `src` of an `<img>`.                     |
| `imageAlt`                                                   | `string`                                                   | `''`    | The alternative text of a string image. Empty by default, which marks the image as decorative.        |
| `description`                                                | `Snippet` &#124; `Component` &#124; `string`               |         | A second line of text below the title.                                                                |
| `action`                                                     | `Snippet` &#124; `Component`                               |         | The action rendered at the end of the header. Not available on selectable cards.                      |
| `HTMLAttributes<HTMLDivElement>` without `children`, `title` |                                                            |         |                                                                                                       |

<!-- /props:CardHeaderProps -->

## CardFooter

The actions shown at the bottom of the card.

### Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CardFooterProps -->

| Name                                                | Type                           | Default | Description                                                                |
| --------------------------------------------------- | ------------------------------ | ------- | -------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLDivElement` &#124; `null` |         | The DOM reference of the footer element.                                   |
| `action`                                            | `Snippet` &#124; `Component`   |         | The actions rendered inside the footer. Not available on selectable cards. |
| `HTMLAttributes<HTMLDivElement>` without `children` |                                |         |                                                                            |

<!-- /props:CardFooterProps -->

---

# Checkbox

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

Represents a control that a user can select (check) or clear (uncheck). A CheckBox can also report its value as indeterminate.

## Usage

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

<Checkbox>Default</Checkbox>
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Checkbox Props table below.

## Examples

### Label

Pass the label text as children. The root is a `<div>` and the text renders in a separate `<label>` associated with the checkbox through `for` and `id`. Inside a `Label`, it is not rendered: the Label names the checkbox.

```svelte
<Checkbox />
<Checkbox>FluentUI Checkbox</Checkbox>
<Checkbox>Another Checkbox</Checkbox>
```

### Checked

The `checked` prop determines whether the checkbox is checked or not. It accepts a boolean value.

```svelte
<Checkbox>Unchecked</Checkbox>
<Checkbox checked>Checked</Checkbox>
```

### Indeterminate

The `indeterminate` prop sets the checkbox to an indeterminate state, which is useful for representing a mixed selection.

```svelte
<Checkbox indeterminate>Indeterminate</Checkbox>
```

### Disabled

The `disabled` prop disables the checkbox, preventing user interaction. It accepts a boolean value.

```svelte
<Checkbox disabled>Disabled</Checkbox>
<Checkbox checked disabled>Checked & Disabled</Checkbox>
```

### Value

The `value` prop sets the value of the checkbox input. It is useful when the checkbox is part of a form submission.

```svelte
<Checkbox value="checkbox-value">Checkbox with Value</Checkbox>
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Checkbox Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:CheckboxProps -->

| Name                                            | Type                             | Default | Description                                                                                 |
| ----------------------------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                | `HTMLInputElement` &#124; `null` |         | The DOM reference of the checkbox element.                                                  |
| `wrapperRef` _bindable_                         | `HTMLDivElement` &#124; `null`   |         | The DOM reference of the checkbox wrapper element.                                          |
| `wrapperAttributes`                             | `HTMLAttributes`                 |         | The attributes to spread on the wrapper element.                                            |
| `indeterminate` _bindable_                      | `boolean` &#124; `null`          |         | Renders the checkbox in its mixed state, neither checked nor unchecked.                     |
| `name`                                          | `string` &#124; `null`           | `id`    | The name submitted with the form. Falls back to the id of the checkbox.                     |
| `group`                                         | `string` &#124; `null`           |         | The value of the group of checkboxes this input belongs to.                                 |
| `checked` _bindable_                            | `boolean` &#124; `null`          |         | Whether the checkbox is checked.                                                            |
| `disabled`                                      | `boolean`                        |         | Disables the user interaction.                                                              |
| `children`                                      | `Snippet`                        |         | The content of the label associated with the checkbox. Inside a `Label`, it is not rendered |
| `HTMLInputAttributes` without `on:`, `children` |                                  |         |                                                                                             |

<!-- /props:CheckboxProps -->

---

# ColorPicker

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

Choose a color with a hue/saturation spectrum, brightness and optional opacity sliders, and RGB or HSV fields.

```svelte
<script>
	import { ColorPicker, Label } from 'fluentui-svelte';
	let color = $state('#0078d4');
</script>

<Label label="Accent color">
	<ColorPicker name="accent" bind:value={color} defaultValue="#0078d4" shape="circular" alpha />
</Label>
```

- `shape`: the shared `Shapes` type: `rounded` (default), `square` or `circular`.
- `orientation`: `vertical` (default) or `horizontal`.
- `format`: bindable `rgb` (default) or `hsv`. Changing format preserves the color.
- `collapsed`: bindable; hides channel fields until More is pressed.
- `alpha`: enables opacity editing and hexadecimal alpha output.
- `value`: bindable CSS color. User edits emit hexadecimal strings; external updates synchronize the controls.
- RGB fields clamp to integers from 0 to 255, hue from 0 to 360, and percentages from 0 to 100. Empty fields restore the selected channel on blur. The Hex editor accepts 3/6 hexadecimal digits (also 4/8 with `alpha`), with an optional `#`; invalid edits restore the selected color.
- Native `name`, `form`, `required`, `disabled`, `readonly`, `pattern`, `oninput` and `onchange` apply to the single submitted text field. `defaultValue` is restored on form reset. Internal controls have no form names.
- Use `Label`, `aria-label`, or `aria-labelledby` to name the picker. Hue and saturation use native keyboard ranges; Left/Right move the spectrum marker horizontally and Up/Down move it vertically. Both coordinates are announced. Other channels use native number fields and sliders.
- Localize `label`, `formatLabel`, `channelLabels`, `moreLabel`, `lessLabel` and `validationMessage` as needed.

## Props

<!-- props:ColorPickerProps -->

| Name                                                                                                            | Type                                                                                                                                                             | Default          | Description                                                                  |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
| `channelLabels`                                                                                                 | `Partial< Record<'hue'` &#124; `'saturation'` &#124; `'brightness'` &#124; `'opacity'` &#124; `'red'` &#124; `'green'` &#124; `'blue'` &#124; `'hex', string> >` |                  | Accessible channel labels, overriding the English defaults.                  |
| `value` _bindable_                                                                                              | `string`                                                                                                                                                         |                  | The CSS color submitted by the field. User edits produce hexadecimal colors. |
| `defaultValue`                                                                                                  | `string`                                                                                                                                                         | `'#ffffff'`      | Initial color and the value restored by a native form reset.                 |
| `shape`                                                                                                         | `'circular'` &#124; `'rounded'` &#124; `'square'`                                                                                                                | `'rounded'`      | Shape of the hue/saturation spectrum.                                        |
| `orientation`                                                                                                   | `'vertical'` &#124; `'horizontal'`                                                                                                                               | `'vertical'`     | Arrangement of the spectrum, sliders and fields.                             |
| `collapsed` _bindable_                                                                                          | `boolean`                                                                                                                                                        |                  | Hides the channel fields until the user expands them.                        |
| `format` _bindable_                                                                                             | `'rgb'` &#124; `'hsv'`                                                                                                                                           | `'rgb'`          | Channel fields displayed in the editor.                                      |
| `alpha`                                                                                                         | `boolean`                                                                                                                                                        |                  | Enables the opacity slider and alpha channel.                                |
| `label`                                                                                                         | `string`                                                                                                                                                         | `'Color picker'` | Accessible name of the picker.                                               |
| `formatLabel`                                                                                                   | `string`                                                                                                                                                         | `'Color format'` | Accessible name of the channel format selector.                              |
| `moreLabel`                                                                                                     | `string`                                                                                                                                                         | `'More'`         | Label of the expansion control.                                              |
| `lessLabel`                                                                                                     | `string`                                                                                                                                                         | `'Less'`         | Label of the collapse control.                                               |
| `validationMessage`                                                                                             | `string`                                                                                                                                                         |                  | Message used for an invalid CSS color.                                       |
| `onColorChange`                                                                                                 | `(value: string) => void`                                                                                                                                        |                  | Reports a user color edit.                                                   |
| `ref` _bindable_                                                                                                | `HTMLInputElement` &#124; `null`                                                                                                                                 |                  | Native form field reference.                                                 |
| `wrapperRef` _bindable_                                                                                         | `HTMLDivElement` &#124; `null`                                                                                                                                   |                  | Visible picker reference.                                                    |
| `wrapperAttributes`                                                                                             | `HTMLAttributes<HTMLDivElement>`                                                                                                                                 |                  | Attributes for the visible picker.                                           |
| `NativeFieldAttributes<HTMLInputAttributes>` without `value`, `defaultValue`, `type`, `size`, `children`, `on:` |                                                                                                                                                                  |                  |                                                                              |

<!-- /props:ColorPickerProps -->

---

# Date Picker

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An input for selecting a date from carousel-style day, month, and year columns. The value uses the `YYYY-MM-DD` format.

## Usage

```svelte
<script>
	import { DatePicker } from 'fluentui-svelte';

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

<DatePicker bind:value />
```

## Examples

### Date Format

Use the `format` prop to switch between `dd/MM/yyyy` and `MM/dd/yyyy`.

```svelte
<DatePicker format="dd/MM/yyyy" />
<DatePicker format="MM/dd/yyyy" />
```

### Hiding Columns

Use `hideDays`, `hideMonths`, or `hideYears` to hide individual selector columns (for example, a month/year-only picker).

```svelte
<DatePicker hideDays />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DatePickerProps -->

| Name                                         | Type                                              | Default                                        | Description                                                                                                                     |
| -------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `value` _bindable_                           | `string`                                          | `''`                                           | Selected date as `YYYY-MM-DD` (matches the underlying `<input type="date">`).                                                   |
| `format`                                     | `'MM/dd/yyyy'` &#124; `'dd/MM/yyyy'`              | `'dd/MM/yyyy'`                                 | The order the three columns are laid out in.                                                                                    |
| `open` _bindable_                            | `boolean`                                         | `false`                                        | Controls the open state of the picker.                                                                                          |
| `hideYears`                                  | `boolean`                                         | `false`                                        | Removes the year column.                                                                                                        |
| `hideMonths`                                 | `boolean`                                         | `false`                                        | Removes the month column.                                                                                                       |
| `hideDays`                                   | `boolean`                                         | `false`                                        | Removes the day column.                                                                                                         |
| `minYear`                                    | `number`                                          | `Current - 100`                                | The first year offered by the year column. Unless `min` is given, the native input accepts no earlier date.                     |
| `maxYear`                                    | `number`                                          | `Current + 100`                                | The last year offered by the year column. Unless `max` is given, the native input accepts no later date.                        |
| `disabledDates`                              | `Date[]`                                          | `[]`                                           | Specific days (year-month-day) that cannot be selected.                                                                         |
| `disabledMonths`                             | `Date[]`                                          | `[]`                                           | Specific months (by month + year) that cannot be selected.                                                                      |
| `disabledYears`                              | `Date[]`                                          | `[]`                                           | Specific years (by year) that cannot be selected.                                                                               |
| `ref` _bindable_                             | `HTMLInputElement` &#124; `null`                  |                                                | The DOM reference of the native date input that holds the value. The other attributes of the picker are applied to it.          |
| `buttonRef` _bindable_                       | `HTMLButtonElement` &#124; `null`                 |                                                | The DOM reference of the button that opens the picker.                                                                          |
| `buttonAttributes`                           | `HTMLButtonAttributes`                            |                                                | The attributes to spread on the button that opens the picker.                                                                   |
| `wrapperRef` _bindable_                      | `HTMLDivElement` &#124; `null`                    |                                                | The DOM reference of the element wrapping the button and the native input.                                                      |
| `wrapperAttributes`                          | `HTMLAttributes`                                  |                                                | The attributes to spread on the wrapper element.                                                                                |
| `popupLabel`                                 | `string`                                          | `'Choose a date'`                              | The accessible name of the popup, which is announced as a dialog.                                                               |
| `columnLabels`                               | `{ month?: string; day?: string; year?: string }` | `{ month: 'Month', day: 'Day', year: 'Year' }` | The names of the month, day and year columns: shown on the trigger while there is no date, and given to the lists of the popup. |
| `NativeFieldAttributes<HTMLInputAttributes>` |                                                   |                                                |                                                                                                                                 |

<!-- /props:DatePickerProps -->

---

# Dialog

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A dialog is a window overlaid on either the primary window or another dialog window. Windows under a modal dialog are inert. That is, users cannot interact with content outside an active dialog window. Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, and in some implementations, attempts to interact with the inert content cause the dialog to close.

The Dialog is composed of several components that work together through a shared context:

- `Dialog`: The root component that creates the state and provides context to its children.
- `DialogTrigger`: A button that opens the dialog when clicked.
- `DialogSurface`: The `<dialog>` element that hosts the dialog content.
- `DialogTitle`: The heading of the dialog. Renders as an `h3` by default.
- `DialogContent`: The scrollable body of the dialog.
- `DialogActions`: The footer that holds action buttons.

## Usage

```svelte
<script>
	import {
		Dialog,
		DialogTrigger,
		DialogSurface,
		DialogTitle,
		DialogContent,
		DialogActions,
		Button
	} from 'fluentui-svelte';

	let dialog = $state();
</script>

<Dialog bind:this={dialog}>
	<DialogTrigger>Open Dialog</DialogTrigger>
	<DialogSurface>
		<DialogTitle>Dialog Title</DialogTitle>
		<DialogContent>
			<p>Lorem ipsum dolor sit amet consectetur adipisicing elit.</p>
		</DialogContent>
		<DialogActions fluid>
			<Button>Save</Button>
			<Button appearance="standard" onclick={() => dialog.closeDialog()}>Close</Button>
		</DialogActions>
	</DialogSurface>
</Dialog>
```

## Examples

### Position

Set `position` on `Dialog` to combine `top`, `middle`, or `bottom` with `start`, `center`, or `end`, for example `top-end` or `bottom-start`. The default is `middle-center`.

Start and end follow the text direction, so `top-start` sits on the right in RTL. All positions keep a 1rem gap from viewport edges and work with modal, non-modal, and alert dialogs. Changing `position` moves an open dialog without closing it.

```svelte
<Dialog position="top-end">
	<DialogTrigger>Open Dialog</DialogTrigger>
	<DialogSurface>
		<DialogTitle>Dialog Title</DialogTitle>
		<DialogContent>Dialog body content.</DialogContent>
	</DialogSurface>
</Dialog>
```

### Entrance and Exit Motion

`animation` selects `fade`, `zoom`, `slide`, or `bounce` for both directions. The default is `zoom`. Zoom enters from 88% scale and exits to 90%; slide travels 16px, from above for top positions and below otherwise. Bounce uses a small scale overshoot with Fluent's strong-invoke curve.

`duration` defaults to `normal`. Theme names are `fast`, `normal`, `slow`, `slower`, `very-slow`, and `extra-slow`, matching `--fs-<name>-duration`. A CSS custom property name such as `--fs-fast-duration` is also accepted. Numbers are milliseconds; `0` disables motion.

```svelte
<Dialog animation="slide" duration={200} position="bottom-end">
	<DialogTrigger>Open Dialog</DialogTrigger>
	<DialogSurface>
		<DialogTitle>Dialog Title</DialogTitle>
		<DialogContent>Dialog body content.</DialogContent>
	</DialogSurface>
</Dialog>
```

Motion is implemented with CSS `@starting-style` and discrete `display`/`overlay` transitions. Calling `closeDialog()` updates `open` and releases native modal focus immediately; CSS keeps the surface and backdrop painted until the exit ends. Browsers without these CSS features open and close immediately. The OS reduced-motion preference and FluentUISvelte's app preference disable motion, including numeric durations; an explicit app preference takes priority over the OS.

### With Actions

Add a `DialogActions` region to render action buttons in the dialog footer. Use `bind:this` on the `Dialog` to call `closeDialog()` programmatically.

```svelte
<script>
	import {
		Dialog,
		DialogTrigger,
		DialogSurface,
		DialogTitle,
		DialogContent,
		DialogActions,
		Button
	} from 'fluentui-svelte';
	let dialog = $state();
</script>

<Dialog bind:this={dialog}>
	<DialogTrigger>Actions Dialog</DialogTrigger>
	<DialogSurface>
		<DialogTitle>Dialog Title</DialogTitle>
		<DialogContent>
			<p>Dialog body content.</p>
		</DialogContent>
		<DialogActions fluid>
			<Button style="flex: 1 1 auto;">Save</Button>
			<Button style="flex: 1 1 auto;" appearance="standard" onclick={() => dialog.closeDialog()}>Close</Button>
		</DialogActions>
	</DialogSurface>
</Dialog>
```

## Dialog Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogProps -->

| Name              | Type                                                                       | Default           | Description                                                                                          |
| ----------------- | -------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `type`            | `'modal'` &#124; `'non-modal'` &#124; `'alert'`                            | `'modal'`         | How the dialog behaves once open.                                                                    |
| `position`        | [`DialogPosition`](https://fluentui-svelte.dev/docs/types/#dialogposition) | `'middle-center'` | Where the dialog sits in the viewport. Start and end follow the text direction.                      |
| `animation`       | `'fade'` &#124; `'zoom'` &#124; `'slide'` &#124; `'bounce'`                | `'zoom'`          | The entrance and exit animation. Bounce uses a subtle overshoot.                                     |
| `duration`        | [`DialogDuration`](https://fluentui-svelte.dev/docs/types/#dialogduration) | `'normal'`        | Duration in milliseconds, a theme duration name, or a CSS custom property name. Use 0 for no motion. |
| `open` _bindable_ | `boolean` &#124; `null`                                                    |                   | Controls the open state of the dialog.                                                               |
| `onOpenChange`    | `(open: boolean) => void`                                                  |                   | Called whenever the dialog opens or closes.                                                          |
| `children`        | `Snippet`                                                                  |                   | The parts of the dialog: a trigger and a surface.                                                    |

<!-- /props:DialogProps -->

## DialogTrigger Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogTriggerProps -->

| Name                    | Type                              | Default | Description                               |
| ----------------------- | --------------------------------- | ------- | ----------------------------------------- |
| `ref` _bindable_        | `HTMLButtonElement` &#124; `null` |         | The DOM reference of the trigger element. |
| `ButtonProps<'button'>` |                                   |         |                                           |

<!-- /props:DialogTriggerProps -->

## DialogSurface Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogSurfaceProps -->

| Name                          | Type                              | Default | Description                              |
| ----------------------------- | --------------------------------- | ------- | ---------------------------------------- |
| `ref` _bindable_              | `HTMLDialogElement` &#124; `null` |         | The DOM reference of the dialog element. |
| Element Attributes (`dialog`) |                                   |         |                                          |

<!-- /props:DialogSurfaceProps -->

## DialogTitle Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogTitleProps -->

| Name             | Type                                         | Default | Description                              |
| ---------------- | -------------------------------------------- | ------- | ---------------------------------------- |
| `ref` _bindable_ | `HTMLDivElement` &#124; `HTMLHeadingElement` |         | The DOM reference of the title element.  |
| `as`             | `DialogTitleTag`                             | `'h3'`  | The HTML element to render the title as. |
| HTML Attributes  |                                              |         |                                          |

<!-- /props:DialogTitleProps -->

## DialogContent Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogContentProps -->

| Name                       | Type                           | Default | Description                               |
| -------------------------- | ------------------------------ | ------- | ----------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null` |         | The DOM reference of the content element. |
| Element Attributes (`div`) |                                |         |                                           |

<!-- /props:DialogContentProps -->

## DialogActions Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DialogActionsProps -->

| Name                       | Type                                       | Default | Description                                                 |
| -------------------------- | ------------------------------------------ | ------- | ----------------------------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null`             |         | The DOM reference of the actions element.                   |
| `fluid`                    | `boolean`                                  |         | Stretches every action to share the available width evenly. |
| `position`                 | `'start'` &#124; `'center'` &#124; `'end'` | `'end'` | Where the actions sit along the main axis.                  |
| Element Attributes (`div`) |                                            |         |                                                             |

<!-- /props:DialogActionsProps -->

---

# Divider

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Divider component is used to visually separate content within a layout. It can be oriented horizontally or vertically.

## Usage

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

<Divider>Divider</Divider>
```

## Divider API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Divider Props table below.

## Examples

### Appearance

Controls the color of the divider. Possible values: `'standard'`, `'accent'`, `'subtle'`.

```svelte
<Divider appearance="standard">Standard Divider</Divider>
<Divider appearance="accent">Accent Divider</Divider>
<Divider appearance="subtle">Subtle Divider</Divider>
```

### Vertical

When `vertical` is set, the divider renders on the vertical axis instead of the horizontal one. Make sure the parent container has a defined height so the divider is visible.

```svelte
<Divider vertical>Vertical</Divider>
```

### Align Content

The `alignContent` prop controls where the label content (children) is positioned along the divider. Possible values: `'start'`, `'center'`, `'end'`.

```svelte
<Divider alignContent="start">Start Aligned Divider</Divider>
<Divider alignContent="center">Center Aligned Divider</Divider>
<Divider alignContent="end">End Aligned Divider</Divider>
```

It also works combined with the `vertical` prop:

```svelte
<Divider alignContent="start" vertical>Start</Divider>
<Divider alignContent="center" vertical>Center</Divider>
<Divider alignContent="end" vertical>End</Divider>
```

### Inset

When `inset` is set, the divider gets some inline padding applied, useful when it's placed inside a container that has content touching its edges.

```svelte
<Divider inset>Inset Divider</Divider>
```

### Custom element

The `as` prop lets you change the underlying HTML element rendered by the divider. Possible values: `'div'`, `'hr'`, `'span'`.

```svelte
<Divider as="hr" />
```

## Divider Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DividerProps -->

| Name             | Type                                                                | Default     | Description                                                          |
| ---------------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------- |
| `as`             | `'div'` &#124; `'hr'` &#124; `'span'`                               | `'div'`     | The HTML element to render the divider as.                           |
| `ref` _bindable_ | `HTMLDivElement` &#124; `HTMLHRElement` &#124; `HTMLSpanElement`    |             | The DOM reference of the divider element.                            |
| `vertical`       | `boolean`                                                           |             | Renders the divider vertically instead of horizontally.              |
| `alignContent`   | `'start'` &#124; `'center'` &#124; `'end'`                          | `'center'`  | Where the content of the divider sits along the line.                |
| `inset`          | `boolean`                                                           |             | Removes the padding around the divider line.                         |
| `appearance`     | `'accent'` &#124; `'standard'` &#124; `'subtle'` &#124; `'default'` | `'default'` | The divider line can be styled for greater emphasis or to be subtle. |
| HTML Attributes  |                                                                     |             |                                                                      |

<!-- /props:DividerProps -->

---

# Dropdown

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Dropdown lets users select one or more options from a list of `DropdownOption` children. Options can render rich content, such as a `Persona`, and the current selection is exposed through a bindable `value`.

## Usage

```svelte
<script>
	import { Dropdown, DropdownOption } from 'fluentui-svelte';
</script>

<Dropdown aria-label="Choose an option">
	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
</Dropdown>
```

## Examples

### Custom Option Content

Options can render any content, such as a `Persona`. Pass a `text` prop so the closed dropdown can still display the selection.

```svelte
<Dropdown aria-label="Choose an option">
	<DropdownOption value="John Doe" text="John Doe">
		<Persona
			name="John Doe"
			primaryText="Software Engineer"
			presence={{ status: 'available' }}
			avatarProps={{ color: 'colorful', idForColor: '' }}
		/>
	</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
	<DropdownOption value="C" text="Option C">Option C</DropdownOption>
</Dropdown>
```

### Multiple Selection

Set the `multiple` prop to allow selecting more than one option.

```svelte
<Dropdown multiple aria-label="Choose options">
	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
	<DropdownOption value="C" text="Option C">Option C</DropdownOption>
</Dropdown>
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownProps -->

| Name                                                 | Type                                              | Default              | Description                                                                                                          |
| ---------------------------------------------------- | ------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `shape`                                              | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'`          | Shape of the input surface, including its border and focus indicator.                                                |
| `value` _bindable_                                   | `string` &#124; `string[]`                        | `multiple ? [] : ''` | The selected value. An array of values when `multiple` is set.                                                       |
| `multiple`                                           | `boolean`                                         |                      | Allows more than one option to be selected at a time.                                                                |
| `placeholder`                                        | `string`                                          | `'Select an option'` | The text shown by the trigger while no option is selected.                                                           |
| `disabled`                                           | `boolean`                                         |                      | Disables the user interaction.                                                                                       |
| `name`                                               | `string` &#124; `null`                            |                      | The name the value is submitted under. Without one, the form leaves the value out, as with any field.                |
| `wrapperRef` _bindable_                              | `HTMLDivElement` &#124; `null`                    |                      | The DOM reference of the wrapper element.                                                                            |
| `wrapperAttributes`                                  | `HTMLAttributes`                                  |                      | The attributes to spread on the wrapper element.                                                                     |
| `ref` _bindable_                                     | `HTMLSelectElement` &#124; `null`                 |                      | The DOM reference of the native select that holds the value. The other attributes of the dropdown are applied to it. |
| `buttonRef` _bindable_                               | `HTMLButtonElement` &#124; `null`                 |                      | The DOM reference of the button that opens the dropdown.                                                             |
| `buttonAttributes`                                   | `HTMLButtonAttributes`                            |                      | The attributes to spread on the button that opens the dropdown.                                                      |
| `flyoutRef` _bindable_                               | `HTMLDivElement` &#124; `null`                    |                      | The DOM reference of the flyout element.                                                                             |
| `flyoutProps`                                        | `FlyoutProps`                                     |                      | The props to spread on the flyout.                                                                                   |
| `flyoutMaxHeight`                                    | `string`                                          |                      | The maximum height of the flyout, as a CSS length.                                                                   |
| `listboxRef` _bindable_                              | `HTMLUListElement` &#124; `null`                  |                      | The DOM reference of the listbox element.                                                                            |
| `listboxProps`                                       | `ListViewProps`                                   |                      | The props to spread on the listbox rendered inside the flyout.                                                       |
| `children`                                           | `Snippet`                                         |                      | The `DropdownOption` elements of the list.                                                                           |
| `DropdownMultipleValue` &#124; `DropdownSingleValue` |                                                   |                      |                                                                                                                      |
| `NativeFieldAttributes<HTMLSelectAttributes>`        |                                                   |                      |                                                                                                                      |

<!-- /props:DropdownProps -->

## DropdownOption Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownOptionProps -->

| Name                      | Type     | Default | Description                                                                                                                                                          |
| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`                    | `string` |         | The text shown by the dropdown once the option is selected. Falls back to the rendered children, which the server cannot read: pass it when rendering on the server. |
| `ListViewItemProps<'li'>` |          |         |                                                                                                                                                                      |

<!-- /props:DropdownOptionProps -->

---

# Dropdown Select

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Dropdown Select is a dropdown built on the native `<select>` element. It lets users choose one option, or several with the `multiple` prop, from a list of `DropdownSelectOption` children.

> **Browser compatibility:** Custom styling uses `appearance: base-select`, `::picker(select)` and `<selectedcontent>`. Single-select styling requires Chrome or Edge 135+, or Safari / iOS Safari 27+. Firefox (including 158) does not yet support the complete feature by default. Earlier Chrome / Edge and Safari versions use the native select appearance; rich option content and custom picker styling are unavailable.
>
> Custom styling for `multiple` requires Chrome or Edge 145+. Safari / iOS Safari 27 and Firefox 158 do not support customizable listboxes and use the native listbox. Browser compatibility verified on October 16, 2026.

## Usage

```svelte
<script>
	import { DropdownSelect, DropdownSelectOption } from 'fluentui-svelte';
</script>

<DropdownSelect aria-label="Choose an option">
	<DropdownSelectOption value="A">Option A</DropdownSelectOption>
	<DropdownSelectOption value="B">Option B</DropdownSelectOption>
	<DropdownSelectOption value="C">Option C</DropdownSelectOption>
</DropdownSelect>
```

## Examples

### Custom Option Content

Options can render rich content such as a `Persona`. Provide a `text` prop for the plain-text selection label.

```svelte
<DropdownSelect aria-label="Choose an option">
	<DropdownSelectOption value="John Doe" text="John Doe">
		<Persona
			name="John Doe"
			primaryText="Software Engineer"
			presence={{ status: 'available' }}
			avatarProps={{ color: 'colorful', idForColor: '' }}
		/>
	</DropdownSelectOption>
	<DropdownSelectOption value="B">Option B</DropdownSelectOption>
	<DropdownSelectOption value="C">Option C</DropdownSelectOption>
</DropdownSelect>
```

### Multiple Selection

Set the `multiple` prop to allow selecting more than one option.

```svelte
<DropdownSelect multiple aria-label="Choose options">
	<DropdownSelectOption value="A">Option A</DropdownSelectOption>
	<DropdownSelectOption value="B">Option B</DropdownSelectOption>
	<DropdownSelectOption value="C">Option C</DropdownSelectOption>
</DropdownSelect>
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownSelectProps -->

| Name                          | Type                                              | Default                    | Description                                                            |
| ----------------------------- | ------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------- |
| `shape`                       | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'`                | Shape of the input surface, including its border and focus indicator.  |
| `value` _bindable_            | `string` &#124; `string[]`                        | `multiple ? [] : ''`       | The selected value. An array of values when `multiple` is set.         |
| `multiple`                    | `boolean`                                         |                            | Allows more than one option to be selected at a time.                  |
| `placeholder`                 | `string`                                          | `'Native Select Dropdown'` | The text shown while no option is selected.                            |
| `hidePlaceholder`             | `boolean`                                         |                            | Keeps the placeholder out of the option list once a value is selected. |
| `ref` _bindable_              | `HTMLSelectElement` &#124; `null`                 |                            | The DOM reference of the select element.                               |
| `wrapperRef` _bindable_       | `HTMLDivElement` &#124; `null`                    |                            | The DOM reference of the wrapper element.                              |
| `wrapperAttributes`           | `HTMLAttributes`                                  |                            | The attributes to spread on the wrapper element.                       |
| Element Attributes (`select`) |                                                   |                            |                                                                        |

<!-- /props:DropdownSelectProps -->

## DropdownSelectOption Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownSelectOptionProps -->

| Name                          | Type                        | Default | Description                                                   |
| ----------------------------- | --------------------------- | ------- | ------------------------------------------------------------- |
| `value`                       | `string`                    |         | The value reported to the select when the option is picked.   |
| `text`                        | `string`                    |         | The label of the option. Falls back to the rendered children. |
| `disabled`                    | `boolean`                   |         | Disables the user interaction.                                |
| `ref` _bindable_              | `HTMLElement` &#124; `null` |         | The DOM reference of the option element.                      |
| `children`                    | `Snippet`                   |         | The content of the option, used when no `text` is given.      |
| Element Attributes (`option`) |                             |         |                                                               |

<!-- /props:DropdownSelectOptionProps -->

---

# Expander

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

Control that displays a header and a collapsible content area.

## Usage

A basic expander expects a header and its content. You can configure the header by passing the `header` property. Content can be provided as child elements of the component. By default, the content container has no padding, this allows you to use 100% of the content width if needed.

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

<Expander header="Expander Title">
	<p>This is the content of the expander</p>
</Expander>
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Controlling Expansion

Expanders can be either expanded or collapsed. This can be controlled by setting the `expanded` property.

```svelte
<Expander header="Expander Title" expanded>
	<p>This is the content of the expander</p>
</Expander>
```

### Opening Direction

An expander doesn't have to expand downwards. You can control an expander's expansion direction using the `direction` property. To create an upwards-expanding expander, set `direction` to `up`.

```svelte
<Expander header="Expander Title" direction="up">
	<p>This is the content of the expander</p>
</Expander>
```

### Adding an Icon

You can easily add an icon to an expander's header using the `Icon` prop. You can pass either a Snippet or a Component. When using Snippet, you have two options:

- Apply the styles to the icon yourself
- Spread the Snippet props into the SVG element

```svelte
<script>
	import { Expander } from 'fluentui-svelte';
	/** As component */
	import InfoRegular from 'fluentui-icons-svelte/InfoRegular.svelte';
</script>

<!-- As Snippet -->
{#snippet IconSnippet(props)}
	<!-- Spread props from Expander Component -->
	<svg {...props} viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
		<path d="M6.747..." />
	</svg>
{/snippet}

<Expander header="Expander Title" direction="up" Icon={InfoRegular}>
	<p>This is the content of the expander</p>
</Expander>
<Expander header="Expander Title" direction="up" Icon={IconSnippet}>
	<p>This is the content of the expander</p>
</Expander>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ExpanderProps -->

| Name                           | Type                                    | Default  | Description                                                               |
| ------------------------------ | --------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `header`                       | `string`                                |          | Label of the expander.                                                    |
| `description`                  | `string`                                |          | Description to render below the header.                                   |
| `direction`                    | `'down'` &#124; `'up'`                  | `'down'` | Set the opening direction of the expander.                                |
| `justify`                      | `boolean`                               | `false`  | The expander is justified to the full width of the container.             |
| `disabled`                     | `boolean`                               | `false`  | Disables the user interaction.                                            |
| `animation`                    | `{ duration: number; easing: string; }` |          | The animation configuration. Reduced motion is always honoured over this. |
| `expanded` _bindable_          | `boolean`                               | `false`  | Control the opening state of the expander.                                |
| `ref` _bindable_               | `HTMLDetailsElement` &#124; `null`      |          | The DOM reference of the expander element.                                |
| `Icon`                         | `Snippet` &#124; `Component`            |          | The icon to display before the label.                                     |
| `summaryRef` _bindable_        | `HTMLElement` &#124; `null`             |          | The DOM reference of the summary element.                                 |
| `summaryAttributes`            | `HTMLAttributes<HTMLElement>`           |          | The HTML attributes to spread on the summary element.                     |
| Element Attributes (`details`) |                                         |          |                                                                           |

<!-- /props:ExpanderProps -->

---

# File Uploader

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A drop zone and file list for choosing files: pick them, drag and drop them, or import them from the camera, the microphone, the screen, a link and cloud drives (Google Drive, OneDrive, Dropbox, Box). It is built on the headless upup engine (`@useupup/core`), which also uploads each file to any S3-compatible storage.

Two ways to use it in a form:

- **Without `upload`**, it is a native file input: the form submits the files under `name`, and `required`, reset and `Label` work as usual.
- **With `upload`** (an `uploadEndpoint`, a `serverUrl` or a tus endpoint), the files are uploaded with a button under the list, or as soon as they are added with `autoUpload`. The form submits what `uploadedValue` returns for each uploaded file (its storage `key` by default) instead of the file, and a submission is stopped while files are not uploaded yet, uploading or failed.

A submission that finds the uploader invalid (`required` with no file, or files not uploaded) turns the drop zone critical.

## Usage

```svelte
<script>
	import { FileUploader, Label } from 'fluentui-svelte';

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

<Label label="Upload" labelPosition="above">
	<FileUploader
		bind:files
		name="attachments"
		accept=".jpg,.jpeg,.png,.pdf,.mp4"
		maxFileSize={50 * 1024 * 1024}
		description="JPEG, PNG, PDF, and MP4 formats, up to 50 MB."
	/>
</Label>
```

## Examples

### Multiple Files

Set `multiple`, or a `maxFiles` above 1, to accept several files, and `maxFileSize`, `minFileSize` or `maxTotalFileSize` to limit them. Files outside the limits are left out, with a message saying why, and `onReject` receives them. `showLimits` shows the limits at the foot of the drop zone (for example "5 files max · 10 MB each").

```svelte
<FileUploader
	maxFiles={5}
	maxFileSize={10 * 1024 * 1024}
	maxTotalFileSize={30 * 1024 * 1024}
	accept="image/*"
	showLimits
/>
```

### Sources

Each source in `sources` adds a button to the drop zone, and opens in its place. `camera`, `microphone` and `screen` record with the media APIs of the browser and show the result before it is added; `url` fetches a file from a link: the site of the file must allow CORS, or `fetchLink` can send the request through a route of your server (allow only trusted hosts there). A cloud drive is passed as an object made by `googleDriveSource`, `oneDriveSource`, `dropboxSource` or `boxSource` with the ids of the provider; only the drives passed are bundled. Each source loads its code when it is opened.

```svelte
<script>
	import { FileUploader, googleDriveSource, oneDriveSource, dropboxSource, boxSource } from 'fluentui-svelte';
</script>

<FileUploader
	multiple
	sources={[
		'local',
		'url',
		'camera',
		'microphone',
		'screen',
		googleDriveSource({ clientId: '...', apiKey: '...', appId: '...' }),
		oneDriveSource({ clientId: '...' }),
		dropboxSource({ clientId: '...' }),
		boxSource({ clientId: '...' })
	]}
/>
```

### Uploading

Pass `upload` with an `uploadEndpoint`: a route of your app that receives `{ name, size, type, metadata }` and returns `{ key, uploadUrl }`, where `uploadUrl` is a presigned PUT URL of your storage. `serverUrl` points at a handler of `@useupup/server` instead. Without `autoUpload`, a button under the list uploads the waiting files; `uploader.upload()` does it from code.

```svelte
<form method="POST">
	<FileUploader
		name="attachments"
		multiple
		required
		upload={{ provider: 'aws', uploadEndpoint: '/api/upload-token' }}
		autoUpload
		onUploadComplete={(files) => console.log(files.map((file) => file.key))}
	/>
	<button>Send</button>
</form>
```

The texts default to English; pass `labels` with the ones to translate. `uploader` gives the upup engine, to pause, resume, cancel or listen to its events.

HTML attributes, including class, id and ARIA attributes, apply to the native file input. Bind ref to access it. Use buttonAttributes and buttonRef for the button that opens the picker, and wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:FileUploaderProps -->

| Name                                         | Type                                                      | Default                                   | Description                                                                                                                                                                                                                                     |
| -------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `files` _bindable_                           | `FileUploaderFile[]`                                      | `[]`                                      | The files of the list. Read it, or bind it, to know what the user chose and what was uploaded. The files it starts with join the list.                                                                                                          |
| `sources`                                    | `(FileUploaderSource` &#124; `FileUploaderDrive)[]`       | `['local']`                               | Where the files can come from. Each source other than `local` adds a button to the drop zone. Cloud drives use `googleDriveSource`, `oneDriveSource`, `dropboxSource` or `boxSource`; only the ones passed are bundled. Read once, on creation. |
| `upload`                                     | `FileUploaderUploadOptions`                               |                                           | Where and how the files are uploaded. With an `uploadEndpoint` or a `serverUrl`, the files are uploaded, and the form submits what `uploadedValue` returns for each one instead of the file. Without them, the form submits the files.          |
| `autoUpload`                                 | `boolean`                                                 | `false`                                   | Uploads each file as soon as it is added. Without it, a button uploads the waiting files, and the form cannot be submitted until they are uploaded.                                                                                             |
| `fetchLink`                                  | `(url: string, signal: AbortSignal) => Promise<Response>` | `(url, signal) => fetch(url, { signal })` | Fetches the file of the link source. A browser reads a file of another site only when that site allows it (CORS); point this at a route of your server that fetches the link instead.                                                           |
| `uploadedValue`                              | `(file: FileUploaderFile) => string`                      | `(file) => file.key`                      | What the form submits for an uploaded file.                                                                                                                                                                                                     |
| `accept`                                     | `string`                                                  |                                           | The file types accepted, like the `accept` attribute: extensions, MIME types or wildcards such as `image/*`.                                                                                                                                    |
| `maxFiles`                                   | `number`                                                  |                                           | The maximum number of files. Above 1, it accepts several files, as `multiple` does.                                                                                                                                                             |
| `maxFileSize`                                | `number`                                                  |                                           | The maximum size of a file, in bytes.                                                                                                                                                                                                           |
| `minFileSize`                                | `number`                                                  |                                           | The minimum size of a file, in bytes.                                                                                                                                                                                                           |
| `maxTotalFileSize`                           | `number`                                                  |                                           | The maximum size of all the files together, in bytes.                                                                                                                                                                                           |
| `description`                                | `string` &#124; `Snippet`                                 |                                           | The line under the title of the drop zone, usually the accepted types and sizes.                                                                                                                                                                |
| `showLimits`                                 | `boolean`                                                 |                                           | Shows the limits of the uploader at the foot of the drop zone: the number of files, the size of each one and the size of all of them, the ones that are set.                                                                                    |
| `labels`                                     | `Partial<FileUploaderLabels>`                             |                                           | The texts of the uploader. The ones left out fall back to English.                                                                                                                                                                              |
| `uploader` _bindable_                        | `UpupCore` &#124; `null`                                  |                                           | The upup engine of the uploader, to pause, resume or cancel the uploads, or to listen to its events. The engine runs in the browser only: it is `null` on the server, and set once the uploader is mounted.                                     |
| `onFilesAdded`                               | `(files: FileUploaderFile[]) => void`                     |                                           | Called with the files added to the list.                                                                                                                                                                                                        |
| `onFileRemoved`                              | `(file: FileUploaderFile) => void`                        |                                           | Called with a file removed from the list.                                                                                                                                                                                                       |
| `onReject`                                   | `(rejections: FileUploaderRejection[]) => void`           |                                           | Called with the files left out of the list, and why.                                                                                                                                                                                            |
| `onUploadComplete`                           | `(files: FileUploaderFile[]) => void`                     |                                           | Called with the files of the list once every upload has ended.                                                                                                                                                                                  |
| `onUploadError`                              | `(error: Error, file?: FileUploaderFile) => void`         |                                           | Called when an upload fails.                                                                                                                                                                                                                    |
| `ref` _bindable_                             | `HTMLInputElement` &#124; `null`                          |                                           | The DOM reference of the native file input that holds the files. The other attributes of the uploader are applied to it.                                                                                                                        |
| `buttonRef` _bindable_                       | `HTMLButtonElement` &#124; `null`                         |                                           | The DOM reference of the button that opens the file picker.                                                                                                                                                                                     |
| `buttonAttributes`                           | `HTMLButtonAttributes`                                    |                                           | The attributes to spread on the button that opens the file picker.                                                                                                                                                                              |
| `wrapperRef` _bindable_                      | `HTMLDivElement` &#124; `null`                            |                                           | The DOM reference of the wrapper element.                                                                                                                                                                                                       |
| `wrapperAttributes`                          | `HTMLAttributes`                                          |                                           | The attributes to spread on the wrapper element.                                                                                                                                                                                                |
| `NativeFieldAttributes<FileInputAttributes>` |                                                           |                                           |                                                                                                                                                                                                                                                 |

<!-- /props:FileUploaderProps -->

---

# Flyout

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Flyout component is a floating panel that can be used to display additional information or options in a non-intrusive way. It is fully accessible and follows Fluent UI design principles for a seamless user experience.

## Usage

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

<Flyout>
	<p>This is the content of the flyout.</p>
</Flyout>
```

The Flyout.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:FlyoutProps -->

| Name                       | Type                                                                      | Default    | Description                                                                     |
| -------------------------- | ------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------- |
| `ref` _bindable_           | `HTMLElement` &#124; `null`                                               |            | The DOM reference of the flyout element.                                        |
| `children`                 | `Snippet`                                                                 |            | The content of the flyout.                                                      |
| `floating`                 | `boolean`                                                                 | `false`    | Positions the flyout with floating-ui instead of leaving it in the normal flow. |
| `reference`                | `HTMLElement`                                                             |            | The element the flyout is positioned against when `floating` is set.            |
| `placement`                | `Placement`                                                               | `'bottom'` | Where the flyout is placed relative to its reference.                           |
| `onPlacementChange`        | `(placement: Placement) => void`                                          |            | Called whenever floating-ui settles on a different placement.                   |
| `roundCorners`             | `'all'` &#124; `'top'` &#124; `'bottom'` &#124; `'left'` &#124; `'right'` | `'all'`    | Which corners of the flyout are rounded.                                        |
| `offset`                   | `number`                                                                  | `8`        | The distance in pixels between the flyout and its reference.                    |
| `placementConfig`          | `AutoPlacementOptions`                                                    |            | The auto placement configuration handed over to floating-ui.                    |
| Element Attributes (`div`) |                                                                           |            |                                                                                 |

<!-- /props:FlyoutProps -->

---

# Hyperlink

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Hyperlink component is used to create clickable links that navigate to a specified URL. It follows Fluent UI design principles and ensures accessibility and smooth user interactions.

## Usage

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

<Hyperlink href="/">Go to Home</Hyperlink>
```

## Examples

### Disabled

Disables the hyperlink and prevents navigation.

```svelte
<Hyperlink href="/" disabled>Disabled Link</Hyperlink>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:HyperlinkProps -->

| Name                     | Type                              | Default | Description                              |
| ------------------------ | --------------------------------- | ------- | ---------------------------------------- |
| `href`                   | `string`                          | `'#'`   | The URL the hyperlink points to.         |
| `disabled`               | `boolean`                         |         | Disables the user interaction.           |
| `ref` _bindable_         | `HTMLAnchorElement` &#124; `null` |         | The DOM reference of the anchor element. |
| Element Attributes (`a`) |                                   |         |                                          |

<!-- /props:HyperlinkProps -->

---

# InfoBar

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The InfoBar control is for displaying app-wide status messages to users that are highly visible yet non-intrusive. There are built-in severity levels to easily indicate the type of message shown, as well as the option to include your own call to action or hyperlink button. Since the InfoBar is inline with other UI content, it can remain visible or be dismissed by the user.

## Usage

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

<InfoBar status="information" title="Information">
	<p>This is an informational message.</p>
</InfoBar>
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Status

The status prop determines the visual style and meaning of the InfoBar.

```svelte
<InfoBar status="information" title="Information">
	<p>This is an informational message.</p>
</InfoBar>
<InfoBar status="attention" title="Attention">
	<p>This is an attention message.</p>
</InfoBar>
<InfoBar status="warning" title="Warning">
	<p>This is a warning message.</p>
</InfoBar>
<InfoBar status="critical" title="Critical">
	<p>This is a critical message.</p>
</InfoBar>
<InfoBar status="success" title="Success">
	<p>This is a success message.</p>
</InfoBar>
```

### Style

The style prop determines the layout of the InfoBar.

```svelte
<InfoBar status="information" style="inline" title="Inline Style">
	<p>This is an inline styled InfoBar.</p>
</InfoBar>
<InfoBar status="information" style="multiline" title="Multiline Style">
	<p>This is a multiline styled InfoBar.</p>
</InfoBar>
```

### Hide Close Button

The hideCloseButton prop allows you to hide the close button in the InfoBar.

```svelte
<InfoBar status="information" title="Without Close Button" hideCloseButton>
	<p>This InfoBar does not have a close button.</p>
</InfoBar>
<InfoBar status="information" title="With Close Button">
	<p>This InfoBar has a close button.</p>
</InfoBar>
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:InfoBarProps -->

| Name                       | Type                                                                                           | Default         | Description                                                                               |
| -------------------------- | ---------------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------- |
| `status`                   | `'information'` &#124; `'attention'` &#124; `'warning'` &#124; `'critical'` &#124; `'success'` | `'information'` | The severity of the message, which picks the icon and the colors.                         |
| `style`                    | `'inline'` &#124; `'multiline'`                                                                | `'inline'`      | Lays the message out on a single line, or stacked below the title.                        |
| `title`                    | `string`                                                                                       |                 | The title of the InfoBar.                                                                 |
| `headingLevel`             | `1` &#124; `2` &#124; `3` &#124; `4` &#124; `5` &#124; `6`                                     | `3`             | The level of the heading that holds the title, to fit the headings of the page around it. |
| `icon`                     | `Snippet` &#124; `Component`                                                                   |                 | Custom icon, rendered instead of the one the `status` would pick on its own.              |
| `iconSize`                 | `number`                                                                                       | `20`            | The size of the icon in pixels.                                                           |
| `hideCloseButton`          | `boolean`                                                                                      |                 | Removes the button that dismisses the InfoBar.                                            |
| `children`                 | `Snippet`                                                                                      |                 | The message of the InfoBar.                                                               |
| Element Attributes (`div`) |                                                                                                |                 |                                                                                           |

<!-- /props:InfoBarProps -->

---

# Label

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A Label provides an accessible caption for a form control. It supports different sizes and weights, can be marked as required or disabled, and can be positioned relative to the control it wraps.

## Usage

```svelte
<script>
	import { Label, TextBox } from 'fluentui-svelte';
</script>

<Label label="Email"><TextBox /></Label>
```

The root is a `div` by default; `as="span"` selects a span. The text label and the field are siblings. Label is for the first field inside it, which takes the id of the label when it has none of its own; pass `for` to point the label at another field. Inside a Label, the own text of a Checkbox, RadioButton or ToggleSwitch is not rendered: the Label names the control. `size` and `weight` style only the label text. `class`, other label attributes and `ref` apply to the label; use `wrapperAttributes` and `wrapperRef` for the root.

## Examples

### Size

Use the `size` prop to control the label text size.

```svelte
<Label size="small" label="Small"><TextBox /></Label>
<Label size="medium" label="Medium"><TextBox /></Label>
<Label size="large" label="Large"><TextBox /></Label>
```

### Weight

Use the `weight` prop to switch between a regular and a semibold label.

```svelte
<Label weight="regular" label="Regular"><TextBox /></Label>
<Label weight="semibold" label="Semibold"><TextBox /></Label>
```

### Label Position

Use the `labelPosition` prop to place the label text relative to the wrapped control.

```svelte
<Label labelPosition="before" label="Before"><TextBox /></Label>
<Label labelPosition="after" label="After"><TextBox /></Label>
<Label labelPosition="above" label="Above"><TextBox /></Label>
<Label labelPosition="below" label="Below"><TextBox /></Label>
```

### Required

Pass a `required` object to mark the label as required and render a required indicator.

```svelte
<Label label="Email" required={{ message: 'Required field' }}><TextBox required /></Label>
```

### Tooltip

Pass `tooltipContent`, as text, a snippet or a component, to show more about the field in a tooltip from a badge after the label text. The badge is a button named after the label; `tooltipBadge` replaces its info icon, and `tooltipButtonAttributes` its `aria-label`. Keep links and buttons out of the tooltip.

```svelte
<Label
	label="Bank"
	labelPosition="above"
	required={{ message: 'Required field' }}
	tooltipContent="The bank that holds the account the payments come from."
>
	<Dropdown placeholder="Bank Name">
		<DropdownOption value="pichincha">Banco Pichincha</DropdownOption>
		<DropdownOption value="guayaquil">Banco Guayaquil</DropdownOption>
	</Dropdown>
</Label>
<Label
	label="IBAN"
	labelPosition="above"
	tooltipBadge={QuestionCircleRegular}
	tooltipContent="The international number of the account, as your bank prints it."
>
	<TextBox placeholder="EC00 0000 0000 0000" />
</Label>
```

### Other form controls

```svelte
<Label label="Accept terms"><Checkbox /></Label>
<Label label="Email updates"><ToggleSwitch /></Label>
<Label label="Standard plan"><RadioButton name="plan" value="standard" /></Label>
<Label label="Country">
	<Dropdown><DropdownOption value="bo">Bolivia</DropdownOption></Dropdown>
</Label>
```

Label renders its text and field as siblings, and is for the first field inside it, which takes the id of the label when it has none of its own. Pass for to point the label at another field. HTML attributes, class and ref apply to the label text element; wrapperAttributes and wrapperRef apply to the container. Size and weight affect only the label text.

A control inside Label needs no id or for. The own text of a Checkbox, RadioButton or ToggleSwitch inside it is not rendered: the Label names the control. A native `<label for>` outside a Label names a picker (Dropdown, TagPicker, DatePicker, TimePicker, CalendarDatePicker) only once the page hydrates, because the picker reads it from the page: when rendering on the server, use Label or pass `aria-labelledby`. A field with an id of its own keeps it: when the text comes before the field (`labelPosition` `'before'` or `'above'`, the default), pass that id to `for` too, or the label the server writes points at no field until the page hydrates.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:LabelProps -->

| Name                                | Type                                                          | Default            | Description                                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`                                | `'div'` &#124; `'span'`                                       | `'div'`            | The element used to wrap the label and its field.                                                                                                                                                                                                                                                   |
| `children`                          | `Snippet`                                                     |                    | The field described by the label, rendered beside the label text.                                                                                                                                                                                                                                   |
| `wrapperRef` _bindable_             | `HTMLDivElement` &#124; `HTMLSpanElement`                     |                    | The DOM reference of the wrapper element.                                                                                                                                                                                                                                                           |
| `wrapperAttributes`                 | `HTMLAttributes`                                              |                    | The attributes to spread on the wrapper element.                                                                                                                                                                                                                                                    |
| `label`                             | `string`                                                      | `'Label Element'`  | The text of the label.                                                                                                                                                                                                                                                                              |
| `size`                              | `'small'` &#124; `'medium'` &#124; `'large'`                  | `'medium'`         | The size of the label text.                                                                                                                                                                                                                                                                         |
| `weight`                            | `'regular'` &#124; `'semibold'`                               | `'regular'`        | The weight of the label text.                                                                                                                                                                                                                                                                       |
| `labelPosition`                     | `'before'` &#124; `'after'` &#124; `'above'` &#124; `'below'` | `'after'`          | Where the label sits relative to the field it describes.                                                                                                                                                                                                                                            |
| `required`                          | `{ abbr?: string; message: string; }`                         |                    | Marks the field as required, and describes why through the given message.                                                                                                                                                                                                                           |
| `disabled`                          | `boolean`                                                     |                    | Renders the label as disabled, to match the field it describes.                                                                                                                                                                                                                                     |
| `ref` _bindable_                    | `HTMLLabelElement` &#124; `null`                              |                    | The DOM reference of the label element.                                                                                                                                                                                                                                                             |
| `id`                                | `string`                                                      | `Generated`        | The id of the label element. A control inside the label is named after it, including a picker whose visible control stands in for its native field.                                                                                                                                                 |
| `for`                               | `string`                                                      | `The field inside` | The id of the field the label is for. Without it, the label is for the first field inside it, which takes a generated id when it has none of its own. With `labelPosition` `before` or `above` and a field that has an id of its own, pass that id here, so the server renders the association too. |
| `tooltipContent`                    | `string` &#124; `Snippet` &#124; `Component`                  |                    | More about the field, in a tooltip shown from a badge after the label text, on hover and on focus. People cannot move into a tooltip, so keep links and buttons out of it.                                                                                                                          |
| `tooltipBadge`                      | `Snippet` &#124; `Component`                                  | `InfoRegular`      | What the badge that shows the tooltip displays. Only rendered with `tooltipContent`.                                                                                                                                                                                                                |
| `tooltipProps`                      | `TooltipProps`                                                |                    | The props to spread on the tooltip.                                                                                                                                                                                                                                                                 |
| `tooltipButtonAttributes`           | `HTMLButtonAttributes`                                        |                    | The attributes to spread on the button of the badge. Its name is the label text followed by its `aria-label`.                                                                                                                                                                                       |
| `HTMLLabelAttributes` without `for` |                                                               |                    |                                                                                                                                                                                                                                                                                                     |

<!-- /props:LabelProps -->

---

# ListView

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The ListView is a component for rendering a set of vertically stacked items. These items can be focusable, selectable, have one primary action and one or more secondary actions, and support keyboard navigation and accessibility features.

## Usage

```svelte
<script>
	import { ListView, ListViewItem } from 'fluentui-svelte';
	let list = ['A', 'B', 'C'];
	let selected = ['A'];
</script>

<ListView selectedItems={selected}>
	{#each list as item (item)}
		<ListViewItem value={item}>{item}</ListViewItem>
	{/each}
</ListView>
```

## ListView API

### Best practices

- Keep lists that only display text out of the Tab sequence. Configure `navigationMode` on the outer ListView: use `items` for native link navigation and `composite` for selectable cards with secondary controls. Let the component manage item and control tabindex unless you opt out with `disableTabspot`.
- With the default grid roles in selectable composite lists, the component wraps each row's content in one `gridcell` and manages navigation to its controls. No manual `gridcell` wrappers are needed.
- Use `onAction` for an item's primary action and native buttons or links with `onclick` for secondary actions. Enter and Space both activate non-native actionable items; links retain native keyboard behavior. In composite selection rows, the checkmark changes selection independently, and secondary buttons and links do not trigger the row's action or selection.
- Keep the default roles for flat selection widgets; they depend on both `selectionMode` and `navigationMode`. Match the HTML tags: `ul`/`ol` with `li` items, or `as="div"` on both a card list and its items.
- Use ListViewItemBranch for expandable sublists. Branches are never selectable and manage their disclosure attributes and focus. Each nested list owns its selection. Set `role="list"` on each selectable list containing branches to preserve native list semantics.
- Give selectable ListView widgets an accessible name with `aria-label` or `aria-labelledby`. Give navigation a named `nav` landmark and mark the current link with `aria-current="page"`. Use meaningful visible text or `aria-label` for controls, a descriptive branch `label`, and stable item `value` strings when using selection.

### As

You can control which tag the ListView component should use: ul, ol, or div. Default: ul.

### Shape

Instead of setting this on every ListViewItem, you can set it here and every item will inherit it. Possible values are rounded, circular, or square. Default: rounded.

### Navigation Mode

`items` keeps each item in the Tab order; `composite` gives the entire list one tab stop and lets Right enter an item's secondary controls. Selection uses listbox/option roles in items mode, or grid/row/gridcell roles in composite mode. Set `role="list"` on each selectable navigation list with sublists to preserve native list semantics; use `aria-current` on links to announce the current page.

### Keyboard navigation

Up/Down move between siblings and Home/End reach the ends of the current level. Right opens a collapsed branch; Right on an expanded branch enters its sublist. Left closes an expanded branch; Left on a collapsed branch or child returns to its parent. Escape closes the nearest branch and restores focus to its button. Right also enters a composite item's controls; Left/Right move between them, and Left from the first control returns to the row. Enter activates links; Enter and Space activate buttons and selectable items. `disableTabspot` opts out of arrow-key focus management. Each nested ListView owns its selection state, so selecting a child does not select its parent.

## Examples

### Simple navigation

Use native anchors inside a named navigation landmark. Under `ul` or `ol`, ListViewItem wraps anchors and buttons in `li` elements.

```svelte
<nav aria-label="Main navigation">
	<ListView>
		<ListViewItem as="a" href="/">Home</ListViewItem>
		<ListViewItem as="a" href="/docs">Documentation</ListViewItem>
		<ListViewItem as="a" href="/docs/components/list-view" aria-current="page">ListView</ListViewItem>
	</ListView>
</nav>
```

### Navigation with sublists

Nest a ListView inside ListViewItemBranch. Branches are focusable disclosure buttons and never participate in selection. The component manages expanded state, aria-expanded, aria-controls, hidden content and focus restoration. Nested lists remain mounted when collapsed, preserving their selection. Hierarchy, indentation and keyboard groups are detected automatically; every nested list owns its selection. Use native list semantics: when selection is enabled, set `role="list"` on lists containing branches. Branches cannot be placed in listbox or grid lists. See the [WAI-ARIA disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).

```svelte
<script lang="ts">
	import { ListView, ListViewItem, ListViewItemBranch } from 'fluentui-svelte';
</script>

<nav aria-label="Component navigation">
	<ListView>
		<ListViewItem as="a" href="/">Home</ListViewItem>
		<ListViewItemBranch label="Components" expanded>
			<ListView>
				<ListViewItem as="a" href="/docs/components/button">Button</ListViewItem>
				<ListViewItem as="a" href="/docs/components/checkbox">Checkbox</ListViewItem>
			</ListView>
		</ListViewItemBranch>
	</ListView>
</nav>
```

### Value

Sets the value of the current item. You must set this when using the ListView selection system or if items change dynamically.

### On Action

This event is triggered when clicking or tapping the element. It executes the primary action and, if the role is not row, it also executes the selection itself.

### Selection Mode

Use `selectionMode` (`single`, `multiselect`, or `extended`) to control how items are selected.

```svelte
<ListView aria-label="Fruits" selectionMode="multiselect" selectedItems={['Apple']}>
	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
		<ListViewItem value={item}>{item}</ListViewItem>
	{/each}
</ListView>
```

### Toggle on click

In a multiselect list, a plain click selects only that item and Ctrl/Cmd + click toggles it. Set `toggleOnClick` to make a plain click toggle the item directly.

```svelte
<ListView aria-label="Fruits" selectionMode="multiselect" toggleOnClick>
	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
		<ListViewItem value={item}>{item}</ListViewItem>
	{/each}
</ListView>
```

### Checkmark

Add and configure a checkbox for the element. You can use the same props for the Checkbox component. The checkbox toggles the selection of its item without triggering `onAction`. Bind `selectedItems` to read or control the selection.

```svelte
<script>
	let selected = $state(['Apple']);
</script>

<ListView aria-label="Fruits" selectionMode="multiselect" bind:selectedItems={selected}>
	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
		<ListViewItem value={item} checkmark={{}}>{item}</ListViewItem>
	{/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>
```

### Cards with a primary action

With `navigationMode` set to `composite` and a `selectionMode`, every item is a row. Use `as="div"` for both the list and its card items to keep the HTML structure valid. Clicking a row runs its primary action (`onAction`), the checkbox toggles its selection, and any button inside is a secondary action. Use `checkmark.wrapperAttributes.style` to place the checkbox where you need it, like the top-right corner of the card. Secondary controls run their own actions without selecting the item or triggering its primary action.

```svelte
<script>
	const cards = [
		{ name: 'Fluent', description: 'Design system' },
		{ name: 'Svelte', description: 'UI framework' },
		{ name: 'Vite', description: 'Build tool' }
	];

	let selected = $state([]);
	let lastAction = $state('');
</script>

<ListView as="div" navigationMode="composite" selectionMode="multiselect" bind:selectedItems={selected}>
	{#each cards as card (card.name)}
		{#snippet install()}
			<Button
				onclick={() => {
					lastAction = 'Installed ' + card.name;
				}}>Install</Button
			>
		{/snippet}
		<ListViewItem
			as="div"
			value={card.name}
			checkmark={{ wrapperAttributes: { style: 'position: absolute; top: 0.5rem; right: 0.5rem; z-index: 2;' } }}
			style="padding: 0"
			onAction={() => (lastAction = 'Opened ' + card.name)}
		>
			<Card orientation="vertical" style="width: 100%;">
				<CardHeader title={card.name} description={card.description} />
				<CardFooter action={install} />
			</Card>
		</ListViewItem>
	{/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>
<p>Last action: {lastAction}</p>
```

## ListView Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ListViewProps -->

| Name                       | Type                                                                  | Default     | Description                                                                                                                                   |
| -------------------------- | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `role`                     | `AriaRole`                                                            |             | Overrides the list role and the roles derived for its items. Use `list` for nested navigation with independent selection.                     |
| `selectionMode`            | `'none'` &#124; `'single'` &#124; `'multiselect'` &#124; `'extended'` | `'none'`    | How many items can be selected, and how the selection is made.                                                                                |
| `navigationMode`           | `'items'` &#124; `'composite'`                                        | `'items'`   | Whether the list itself takes a single tab stop, or every item takes its own.                                                                 |
| `manageSpecialKeys`        | `boolean` &#124; `TabspotRootOptions['manageSpecialKeys']`            | `true`      | Which special keys Tabspot handles at the root. Set individual keys to leave Escape to an enclosing panel. Omitted keys in an object are off. |
| `selectedItems` _bindable_ | `string[]`                                                            |             | The values of the selected items.                                                                                                             |
| `shape`                    | `'circular'` &#124; `'rounded'` &#124; `'square'`                     | `'rounded'` | The items can have a circular, rounded or square shape.                                                                                       |
| `onSelectionChange`        | `(e: Event, selectedItems: string[]` &#124; `[]) => void`             |             | Called whenever the selection changes.                                                                                                        |
| `toggleOnClick`            | `boolean`                                                             | `false`     | When `selectionMode` is `'multiselect'`, clicking an item toggles its selection directly instead of requiring Ctrl/Cmd + click.               |
| `as`                       | `'ul'` &#124; `'ol'` &#124; `'div'`                                   | `'ul'`      | The HTML element to render the list as.                                                                                                       |
| `ref` _bindable_           | `HTMLUListElement` &#124; `HTMLOListElement` &#124; `HTMLDivElement`  |             | The DOM reference of the list element.                                                                                                        |
| `disableTabspot`           | `boolean`                                                             | `false`     | Opts the list out of the tabspot focus management, to wire your own.                                                                          |
| HTML Attributes            |                                                                       |             |                                                                                                                                               |

<!-- /props:ListViewProps -->

## ListViewItem Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ListViewItemProps -->

| Name             | Type                                                                                          | Default | Description                                                                                                                                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`             | `'li'` &#124; `'a'` &#124; `'button'` &#124; `'div'`                                          | `'li'`  | The HTML element to render the item as. Links and buttons are wrapped in a list item when the list renders as `ul` or `ol`. Use `li` or `div` for nested lists and content with multiple controls. Buttons cannot contain checkmarks or composite rows. |
| `shape`          | `'circular'` &#124; `'rounded'` &#124; `'square'`                                             |         | The item can have a circular, rounded or square shape. Inherited from the list by default.                                                                                                                                                              |
| `value`          | `string`                                                                                      |         | The value reported to the list when the item is selected. Falls back to a generated id.                                                                                                                                                                 |
| `active`         | `boolean`                                                                                     |         | Renders the item in its pressed state.                                                                                                                                                                                                                  |
| `role`           | `'treeitem'` &#124; `'menuitem'` &#124; `'option'` &#124; `'row'`                             |         | The ARIA role of the item. Derived from the list by default.                                                                                                                                                                                            |
| `disabled`       | `boolean`                                                                                     |         | Disables the user interaction.                                                                                                                                                                                                                          |
| `checkmark`      | `CheckboxProps`                                                                               |         | The props to spread on the checkbox rendered when the list is multiselect.                                                                                                                                                                              |
| `onAction`       | `(e: MouseEvent, value: string) => void`                                                      |         | Called when the item is clicked or activated with the keyboard.                                                                                                                                                                                         |
| `onfocus`        | `(e: Event, value: string) => void`                                                           |         | Called when the item receives the focus.                                                                                                                                                                                                                |
| `ref` _bindable_ | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLButtonElement` &#124; `HTMLDivElement` |         | The DOM reference of the item element.                                                                                                                                                                                                                  |
| HTML Attributes  |                                                                                               |         |                                                                                                                                                                                                                                                         |

<!-- /props:ListViewItemProps -->

## ListViewItemBranch Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ListViewItemBranchProps -->

| Name                                                                                                 | Type                                              | Default | Description                                                                                                                     |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `label`                                                                                              | `string`                                          |         | The accessible label rendered in the disclosure button.                                                                         |
| `icon`                                                                                               | `Snippet` &#124; `Component`                      |         | The decorative icon before the label.                                                                                           |
| `expanded` _bindable_                                                                                | `boolean`                                         | `false` | Whether the nested content is visible. Branches only expand or collapse and are never selectable.                               |
| `onExpandedChange`                                                                                   | `(e: Event, expanded: boolean) => void`           |         | Called when a user expands or collapses the branch.                                                                             |
| `disabled`                                                                                           | `boolean`                                         | `false` | Disables the disclosure button.                                                                                                 |
| `shape`                                                                                              | `'circular'` &#124; `'rounded'` &#124; `'square'` |         | The disclosure button shape. Inherited from the list by default.                                                                |
| `ref` _bindable_                                                                                     | `HTMLButtonElement`                               |         | The DOM reference of the native disclosure button. Additional HTML attributes, including class and id, also target this button. |
| `wrapperRef` _bindable_                                                                              | `HTMLLIElement` &#124; `HTMLDivElement`           |         | The DOM reference of the wrapper element, the list item that holds the button and the nested list.                              |
| `wrapperAttributes`                                                                                  | `HTMLAttributes`                                  |         | The attributes to spread on the wrapper element.                                                                                |
| `children`                                                                                           | `Snippet`                                         |         | Nested ListView content, kept mounted while collapsed to preserve its selection.                                                |
| `HTMLButtonAttributes` without `children`, `role`, `type`, `value`, `aria-expanded`, `aria-controls` |                                                   |         |                                                                                                                                 |

<!-- /props:ListViewItemBranchProps -->

---

# Media Player

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A video player with Fluent transport controls: a seek bar with the time, volume, subtitles, previous and next, skip back and forward, play and pause, picture-in-picture, full screen and playback speed, each with a tooltip. Video.js (`@videojs/html`) runs the playback underneath: the player state, keyboard shortcuts, touch and mouse gestures, and when the controls hide. It loads in the browser only, the first time a player mounts.

## Usage

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

<MediaPlayer src="video.mp4" poster="poster.jpg" />
```

## Examples

### Deferred loading

`deferred` shows a light splash in place of the player: the poster and a large play button, with no `<video>` and no Video.js. The player, its scripts and the media load when the play button is pressed, and the video starts within that same press. `click` downloads everything on the press, `intent` starts downloading the scripts when the pointer or the focus reaches the button, and `visible` when the splash scrolls into view. Set `aspectRatio` to the shape of the media: nothing moves when the player replaces the splash.

```svelte
<MediaPlayer src="video.mp4" poster="poster.jpg" deferred="intent" aspectRatio="16 / 9" />
```

### Compact layout

`layout="compact"` puts the play button, the seek bar and the essential buttons in a single row.

```svelte
<MediaPlayer src="video.mp4" layout="compact" />
```

### Narrow players

Under 26rem wide, the standard layout keeps only the volume, play, picture-in-picture and full screen buttons.

### Controls that hide

The transport controls hide while the media plays and the user rests, and come back on any activity or keyboard focus. A pause keeps them on screen. `autoHideWhenPaused` lets them hide during a pause too, and `autoHideControls={false}` keeps them on screen always.

```svelte
<MediaPlayer src="video.mp4" autoHideWhenPaused />
<MediaPlayer src="video.mp4" autoHideControls={false} />
```

### Vertical video

A vertical video fills the height its width allows. Give the player a width and set `aspectRatio` to the shape of the media to reserve its space while it loads.

```svelte
<MediaPlayer
	src="vertical.mp4"
	poster="vertical-poster.jpg"
	aspectRatio="9 / 16"
	wrapperAttributes={{ style: 'max-width: 20rem' }}
/>
```

### Repeat

`showRepeat` adds a repeat button to the start group, which toggles `loop`. Bind `loop` to follow it.

```svelte
<script>
	let loop = $state(false);
</script>

<MediaPlayer src="video.mp4" showRepeat bind:loop />
```

### Subtitles

Pass WebVTT files in `tracks`. The player draws the subtitles itself, in a Fluent panel that rises above the controls while they show. One track shows a toggle button; several show a menu to pick one. Media from another origin needs `crossorigin="anonymous"` for its tracks to load.

```svelte
<MediaPlayer
	src="video.mp4"
	tracks={[
		{ src: '/subtitles-en.vtt', srclang: 'en', label: 'English', default: true },
		{ src: '/subtitles-es.vtt', srclang: 'es', label: 'Español' }
	]}
/>
```

`subtitlesAppearance` sets how the subtitles look: `acrylic` (default), a translucent panel of the theme like the controls, or `translucent`, light text on a dark veil in either theme, close to the native subtitles. `subtitlesSize` takes `small`, `medium` (default) or `large`; a narrow player takes one step down.

```svelte
<MediaPlayer src="video.mp4" subtitlesAppearance="translucent" subtitlesSize="small" tracks={[/* ... */]} />
```

### Vertical volume

`volumeOrientation="vertical"` shows the volume slider upright above its button.

### Skip buttons and playback speed

`skipBackward` takes `10` or `15` seconds and `skipForward` takes `10`, `15` or `30`. `0` hides the button. `playbackRates` sets the speeds of the more options menu; an empty list removes them.

```svelte
<MediaPlayer src="video.mp4" skipBackward={15} skipForward={15} playbackRates={[1, 1.5, 2]} />
```

### Previous and next

`onPrevious` and `onNext` show the previous and next buttons around the playback buttons. The system media controls, picture-in-picture included, call them too. Leave one `undefined` to hide its button.

```svelte
<script>
	const playlist = ['intro.mp4', 'chapter-1.mp4', 'chapter-2.mp4'];
	let index = $state(0);
</script>

<MediaPlayer
	src={playlist[index]}
	autoplay={index > 0}
	onPrevious={index > 0 ? () => index-- : undefined}
	onNext={index < playlist.length - 1 ? () => index++ : undefined}
	onended={() => index < playlist.length - 1 && index++}
/>
```

### Custom controls and menu items

`startContent`, `centerContent` and `endContent` add controls to the start, middle and end groups of the button row; `moreContent` adds items, such as `MenuItem`, to the more options menu. Each is a snippet or a component that receives `{ store, layout, narrow, labels }`. `MediaPlayerButton` draws an icon button like the built-in ones: `label` names it and shows in its tooltip, and the `optional` class hides it in a narrow player.

```svelte
<script>
	import { MediaPlayer, MediaPlayerButton, MenuItem } from 'fluentui-svelte';
	import ArrowDownloadRegular from 'fluentui-icons-svelte/ArrowDownloadRegular.svelte';
	import ShareRegular from 'fluentui-icons-svelte/ShareRegular.svelte';

	/** Copies a link to the current moment of the video. */
	const share = (time = 0) => navigator.clipboard.writeText(`${location.href}#t=${Math.floor(time)}`);
</script>

<MediaPlayer src="video.mp4">
	{#snippet endContent({ store })}
		<MediaPlayerButton label="Share this moment" class="optional" onclick={() => share(store?.currentTime)}>
			<ShareRegular />
		</MediaPlayerButton>
	{/snippet}
	{#snippet moreContent()}
		<MenuItem icon={ArrowDownloadRegular}>Download</MenuItem>
	{/snippet}
</MediaPlayer>
```

### Controlling the player from code

`playerRef` is the `<video-player>` element of Video.js. Its `store` holds the state (`paused`, `currentTime`, `volume`, `muted`, `isFullscreen` and more) and the actions (`play()`, `pause()`, `seek(time)`, `setVolume(volume)` and more), and `store.subscribe(callback)` reports every change. It is `null` until the player has loaded in the browser.

```svelte
<script>
	let player = $state(null);
</script>

<MediaPlayer src="video.mp4" bind:playerRef={player} />
<button onclick={() => player?.store.seek(0)}>Restart</button>
```

### Texts and translations

`labels` sets the names and tooltips of the controls, their menus and messages: `play`, `pause`, `previous`, `next`, `skipBackward(seconds)`, `skipForward(seconds)`, `seek`, `seekValue(time, duration)`, `volume`, `mute`, `unmute`, `repeat`, `subtitles`, `subtitlesOff`, `pictureInPicture`, `exitPictureInPicture`, `fullScreen`, `exitFullScreen`, `moreOptions`, `playbackSpeed`, `normalSpeed`, `loading`, `error` and `dismiss`. The texts left out fall back to the English ones of `MEDIA_PLAYER_LABELS`. Custom content receives the final texts as `labels`, to name its own controls alike. `label` names the player itself.

```svelte
<MediaPlayer
	src="video.mp4"
	label="Reproductor multimedia"
	labels={{
		play: 'Reproducir',
		pause: 'Pausar',
		fullScreen: 'Pantalla completa',
		moreOptions: 'Más opciones',
		skipBackward: (seconds) => `Retroceder ${seconds} segundos`
	}}
/>
```

## Keyboard

With the focus in the player: Space or K plays and pauses, the left and right arrows (J and L) seek, the up and down arrows change the volume, M mutes, F toggles full screen, C toggles subtitles, I toggles picture-in-picture, Home and End jump to the start and the end.

With the mouse, a click on the video plays and pauses and a double click toggles full screen. Clicks on the controls and their popups never do.

The root is the native `<video>` element: HTML attributes such as `autoplay`, `muted`, `loop`, `preload` and `crossorigin` apply to it, and so does `ref`. `wrapperAttributes` styles the element that draws the player.

## Component Props

<!-- props:MediaPlayerProps -->

| Name                                                                          | Type                                           | Default                              | Description                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`                                                                         | `string`                                       |                                      | The URL of the media to play.                                                                                                                                                                                         |
| `poster`                                                                      | `string`                                       |                                      | The image shown until the media plays.                                                                                                                                                                                |
| `tracks`                                                                      | `MediaPlayerTrack[]`                           |                                      | The text tracks of the media: subtitles, captions or chapters.                                                                                                                                                        |
| `layout`                                                                      | `'standard'` &#124; `'compact'`                | `'standard'`                         | How the transport controls are laid out.                                                                                                                                                                              |
| `deferred`                                                                    | `'click'` &#124; `'intent'` &#124; `'visible'` |                                      | Shows a light splash in place of the player, with the poster and a play button, and loads the player, its scripts and the media only when the play button is pressed. Video.js and the media download nothing before. |
| `aspectRatio`                                                                 | `string`                                       | `'16 / 9'`                           | The shape of the player until its media loads, and of the splash of a deferred player, as a CSS `aspect-ratio`. Match it to the media and nothing moves once the video arrives.                                       |
| `volumeOrientation`                                                           | `'horizontal'` &#124; `'vertical'`             | `'horizontal'`                       | The direction of the volume slider in its popup.                                                                                                                                                                      |
| `autoHideControls`                                                            | `boolean`                                      | `true`                               | Hides the transport controls while the media plays and the user rests, and shows them again on any activity. `false` keeps them on screen.                                                                            |
| `autoHideWhenPaused`                                                          | `boolean`                                      |                                      | Hides the transport controls of a paused media too, once the user rests. Without it, a pause keeps them on screen.                                                                                                    |
| `subtitlesAppearance`                                                         | `'acrylic'` &#124; `'translucent'`             | `'acrylic'`                          | How the subtitles look.                                                                                                                                                                                               |
| `subtitlesSize`                                                               | `'small'` &#124; `'medium'` &#124; `'large'`   | `'medium'`                           | The size of the subtitles text. A narrow player takes one step down.                                                                                                                                                  |
| `loop` _bindable_                                                             | `boolean`                                      |                                      | Plays the media again from the start when it ends. The repeat button toggles it.                                                                                                                                      |
| `showRepeat`                                                                  | `boolean`                                      |                                      | Shows a repeat button, which toggles `loop`.                                                                                                                                                                          |
| `skipBackward`                                                                | `0` &#124; `10` &#124; `15`                    | `10`                                 | How many seconds the skip back button rewinds. `0` hides the button.                                                                                                                                                  |
| `skipForward`                                                                 | `0` &#124; `10` &#124; `15` &#124; `30`        | `30`                                 | How many seconds the skip forward button advances. `0` hides the button.                                                                                                                                              |
| `playbackRates`                                                               | `number[]`                                     | `[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | The speeds of the more options menu. An empty list removes the playback speed group.                                                                                                                                  |
| `onPrevious`                                                                  | `() => void`                                   |                                      | Shows a previous button and calls this when it is pressed, or when the system media controls ask for the previous track.                                                                                              |
| `onNext`                                                                      | `() => void`                                   |                                      | Shows a next button and calls this when it is pressed, or when the system media controls ask for the next track.                                                                                                      |
| `startContent`                                                                | `Snippet` &#124; `Component`                   |                                      | Custom controls at the start of the button row, after the volume and subtitles buttons.                                                                                                                               |
| `centerContent`                                                               | `Snippet` &#124; `Component`                   |                                      | Custom controls in the middle of the button row, after the next button.                                                                                                                                               |
| `endContent`                                                                  | `Snippet` &#124; `Component`                   |                                      | Custom controls at the end of the button row, before the picture-in-picture button.                                                                                                                                   |
| `moreContent`                                                                 | `Snippet` &#124; `Component`                   |                                      | Custom items for the more options menu, after the playback speed group. Use the Menu items.                                                                                                                           |
| `label`                                                                       | `string`                                       | `'Media player'`                     | The accessible name of the player.                                                                                                                                                                                    |
| `labels`                                                                      | `Partial<MediaPlayerLabels>`                   |                                      | The texts of the controls, their tooltips and menus. The ones left out fall back to English.                                                                                                                          |
| `ref` _bindable_                                                              | `HTMLVideoElement` &#124; `null`               |                                      | The DOM reference of the native video element. The other attributes of the player are applied to it.                                                                                                                  |
| `playerRef` _bindable_                                                        | `VideoPlayerElement`                           |                                      | The `<video-player>` element of Video.js. Its `store` holds the state and the actions of the player.                                                                                                                  |
| `wrapperAttributes`                                                           | `HTMLAttributes`                               |                                      | The attributes to spread on the element that draws the player.                                                                                                                                                        |
| `children`                                                                    | `Snippet`                                      |                                      | Extra `<source>` or `<track>` elements for the video.                                                                                                                                                                 |
| `HTMLVideoAttributes` without `src`, `poster`, `controls`, `children`, `loop` |                                                |                                      |                                                                                                                                                                                                                       |

<!-- /props:MediaPlayerProps -->

### MediaPlayerButton Props

<!-- props:MediaPlayerButtonProps -->

| Name                                                            | Type                              | Default | Description                                                   |
| --------------------------------------------------------------- | --------------------------------- | ------- | ------------------------------------------------------------- |
| `label`                                                         | `string`                          |         | The accessible name of the button, also shown in its tooltip. |
| `tooltipPlacement`                                              | `Placement`                       | `'top'` | Where the tooltip is placed relative to the button.           |
| `hideTooltip`                                                   | `boolean`                         |         | Keeps the tooltip closed, for a button whose popup is open.   |
| `ref` _bindable_                                                | `HTMLButtonElement` &#124; `null` |         | The DOM reference of the button element.                      |
| `children`                                                      | `Snippet`                         |         | The icon of the button.                                       |
| `ButtonProps<'button'>` without `ref`, `children`, `appearance` |                                   |         |                                                               |

<!-- /props:MediaPlayerButtonProps -->

---

# Menu

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

Menu is a component for displaying a list of actions or options in a dropdown format. It can be used in various contexts, such as navigation, settings, or context menus.

This component relies on the Floating UI library for positioning. It provides a flexible API for creating complex menu structures, including nested menus, checkable items, and disabled items.

To create a menu, you will need to use the following components:

- `Menu`: The root component that creates all the state and provides context to its children.
- `MenuTrigger`: Handles all the logic for the trigger element that opens the menu. It uses a render prop pattern to provide the necessary props and state to the trigger element.
- `ContextMenuTrigger`: A variant of MenuTrigger that is designed to be used for context menus. It attaches the menu to a specified element and opens on right-click.
- `MenuPopover`: The container for the menu content. It handles the positioning and accessibility of the menu.
- `MenuList`: A wrapper for the list of menu items.
- `MenuItem`: Represents a single item in the menu. It can be a simple action or a trigger for a nested menu.
- `SplitButton` or `Button`: The trigger element for the menu.

Other components that can be used within the menu include:

- `MenuGroup`: A wrapper for grouping related menu items together, with an optional header.
- `MenuDivider`: A visual separator between menu items or groups.
- `MenuItemCheckbox`: A menu item that can be checked or unchecked.
- `MenuItemSwitch`: A menu item that can be toggled on or off.
- `MenuItemRadio`: A menu item that can be selected as part of a group of radio items.
- `MenuCommandBar`: A row of icon-only commands placed at the top or at the bottom of the menu, with an optional overflow submenu.
- `MenuCommandBarItem`: A square, icon-only command of a MenuCommandBar, with a label that names it and shows as its tooltip.

## Usage

To correctly attach events to the trigger element, you should wrap the element with the `children()` `snippet`. This allows you to bind the necessary props and state to your trigger element, ensuring that the menu opens and closes as expected.

```svelte
<script>
	import { Button, Menu, MenuTrigger, MenuPopover, MenuList, MenuGroup, MenuItem, MenuDivider } from 'fluentui-svelte';
</script>

<Menu>
	<MenuTrigger>
		{#snippet children({ state, menuTriggerProps })}
			<Button bind:ref={state.ref} {...menuTriggerProps}>Open Menu</Button>
		{/snippet}
	</MenuTrigger>
	<MenuPopover>
		<MenuList>
			<MenuGroup header="Group 1">
				<MenuItem>Item 1</MenuItem>
				<MenuItem>Item 2</MenuItem>
			</MenuGroup>
			<MenuDivider />
			<MenuGroup header="Group 2">
				<MenuItem>Item 3</MenuItem>
				<MenuItem>Item 4</MenuItem>
			</MenuGroup>
		</MenuList>
	</MenuPopover>
</Menu>
```

## More Examples

### Menu with checkable items and nested submenus

```svelte
<Menu hasCheckmarks hasIcons {checkedValues} onCheckedValueChange={(e, value) => (checkedValues = value)}>
	<MenuTrigger>
		{#snippet children({ state, menuTriggerProps })}
			<Button isMenuButton bind:ref={state.ref} {...menuTriggerProps}>
				<AccessTimeRegular /> Open Menu
			</Button>
		{/snippet}
	</MenuTrigger>
	<MenuPopover>
		<MenuList>
			<MenuItem subText="An explanation here">Item With Subtext</MenuItem>
			<MenuDivider />
			<MenuItem disabled>I'm Disabled</MenuItem>
			<MenuItemCheckbox name="item4" value="item4" icon={AccessTimeRegular}>I'm a checkbox</MenuItemCheckbox>
			<MenuItemSwitch>I'm a switch</MenuItemSwitch>
			<MenuItemRadio name="item6" value="item6" icon={AccessTimeRegular}>I'm a radio</MenuItemRadio>
		</MenuList>
	</MenuPopover>
</Menu>
```

### Menu with a SplitButton trigger

```svelte
<Menu>
	<MenuTrigger>
		{#snippet children({ state, menuTriggerProps, primaryButtonProps })}
			<SplitButton
				bind:menuTriggerRef={state.ref}
				menuTriggerProps={{ ...menuTriggerProps, 'aria-label': 'More options' }}
				primaryButtonProps={{ onclick: () => alert('Primary action'), ...primaryButtonProps }}
			>
				Primary Action
			</SplitButton>
		{/snippet}
	</MenuTrigger>
	<MenuPopover>
		<MenuList>
			<MenuItem>Item 1</MenuItem>
			<MenuItem>Item 2</MenuItem>
		</MenuList>
	</MenuPopover>
</Menu>
```

### Menu with a command bar

A command bar flyout pairs a row of square, icon-only primary commands with the items of the menu. Place a `MenuCommandBar` at the top or at the bottom of the `MenuList` and set its `position` to match. Fill it with `MenuCommandBarItem`, each with an `icon` and a `label` that names it and shows as its tooltip. The `overflow` snippet adds a "more" button at the end of the row that opens the secondary commands in a submenu.

Left and Right move along the bar. Up and Down move between the bar and the items of the menu.

```svelte
<Menu>
	<MenuTrigger>
		{#snippet children({ state, menuTriggerProps })}
			<Button bind:ref={state.ref} {...menuTriggerProps}>Commands on top</Button>
		{/snippet}
	</MenuTrigger>
	<MenuPopover>
		<MenuList>
			<!-- position="bottom" when the bar comes after the items -->
			<MenuCommandBar>
				<MenuCommandBarItem icon={CutRegular} label="Cut" />
				<MenuCommandBarItem icon={CopyRegular} label="Copy" />
				<MenuCommandBarItem icon={ClipboardPasteRegular} label="Paste" />
				{#snippet overflow()}
					<MenuItem>Select all</MenuItem>
					<MenuItem>Rename</MenuItem>
				{/snippet}
			</MenuCommandBar>
			<MenuItem>Open</MenuItem>
			<MenuItem>Open with</MenuItem>
			<MenuItem>Properties</MenuItem>
		</MenuList>
	</MenuPopover>
</Menu>
```

By default every command is a square that shows only its icon. `showLabels` shows the label of every command below its icon, and `showDividers` draws a divider between every two commands; with either of them the commands share the width of the bar evenly.

```svelte
<MenuCommandBar showLabels showDividers>
	<MenuCommandBarItem icon={CutRegular} label="Cut" />
	<MenuCommandBarItem icon={CopyRegular} label="Copy" />
	<MenuCommandBarItem icon={EditRegular} label="Rename" />
	<MenuCommandBarItem icon={ShareRegular} label="Share" />
	<MenuCommandBarItem icon={DeleteRegular} label="Delete" />
</MenuCommandBar>
```

## Context Menu

This variant of the `MenuTrigger` component allows you to create context menus that open on right-click. You can specify the element to which the context menu should be attached using the `ref` prop. If no element is provided, it will attach to the `document.body` by default.

```svelte
<Menu>
	<ContextMenuTrigger ref={document.querySelector('#context-menu-box')} />
	<MenuPopover>
		<MenuList>
			<MenuItem>Item 1</MenuItem>
			<MenuItem>Item 2</MenuItem>
		</MenuList>
	</MenuPopover>
</Menu>
```

## Component Props (Menu)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuProps -->

| Name                      | Type                                                          | Default | Description                                                                |
| ------------------------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `positionConfig`          | `ComputePositionConfig`                                       |         | The position configuration handed over to floating-ui.                     |
| `hasIcons`                | `boolean`                                                     |         | Reserves the room every item needs for an icon, so the labels line up.     |
| `hasCheckmarks`           | `boolean`                                                     |         | Reserves the room every item needs for a checkmark, so the labels line up. |
| `open`                    | `boolean`                                                     |         | Controls the open state of the menu.                                       |
| `onOpenChange`            | `(e: Event, open: boolean) => void`                           |         | Called whenever the menu opens or closes.                                  |
| `checkedValues`           | `Record<string, string[]>`                                    | `{}`    | The checked values of the menu, grouped by the `name` of each item.        |
| `onCheckedValueChange`    | `(e: Event, checkedValues: Record<string, string[]>) => void` |         | Called whenever a checkbox or radio item changes.                          |
| `openOnHover`             | `boolean`                                                     | `false` | Opens the menu on hover instead of on click.                               |
| `openingDelay`            | `number`                                                      | `0`     | How long to wait, in milliseconds, before opening the menu.                |
| `persistOnItemActivation` | `boolean`                                                     | `false` | Keeps the menu open after an item is activated.                            |
| `children`                | `Snippet`                                                     |         | The parts of the menu: a trigger and a popover.                            |

<!-- /props:MenuProps -->

## Component Props (MenuPopover)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuPopoverProps -->

| Name              | Type                                 | Default | Description                                              |
| ----------------- | ------------------------------------ | ------- | -------------------------------------------------------- |
| `ref`             | `HTMLElement` &#124; `null`          |         | The element used to position the popover.                |
| `open` _bindable_ | `boolean` &#124; `null`              |         | Controls the open state of the popover.                  |
| `keepMounted`     | `boolean`                            | `false` | Keeps the popover mounted in the DOM while it is closed. |
| `placement`       | `ComputePositionConfig['placement']` |         | Where the popover is positioned relative to its trigger. |
| `positionConfig`  | `ComputePositionConfig`              |         | The position configuration handed over to floating-ui.   |
| `children`        | `Snippet`                            |         | The content of the popover.                              |

<!-- /props:MenuPopoverProps -->

## Component Props (MenuTrigger)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuTriggerProps -->

| Name       | Type                                              | Default | Description                                                                               |
| ---------- | ------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `disabled` | `boolean`                                         |         | Disables the user interaction.                                                            |
| `shape`    | `'circular'` &#124; `'rounded'` &#124; `'square'` |         | The trigger can be rounded, circular, or square.                                          |
| `icon`     | `Snippet` &#124; `Component`                      |         | An optional icon for the trigger.                                                         |
| `children` | `Snippet`                                         |         | A custom trigger. It receives the menu state and the props to spread on your own buttons. |

<!-- /props:MenuTriggerProps -->

## Component Props (MenuItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuItemProps -->

| Name               | Type                         | Default | Description                                      |
| ------------------ | ---------------------------- | ------- | ------------------------------------------------ |
| `icon`             | `Snippet` &#124; `Component` |         | The icon to display before the label.            |
| `secondaryContent` | `string`                     |         | Right aligned text, usually a keyboard shortcut. |
| `disabled`         | `boolean`                    |         | Disables the user interaction.                   |
| `subText`          | `string`                     |         | A second line of text below the label.           |
| `href`             | `string`                     |         | Renders the item as a link pointing to this URL. |

<!-- /props:MenuItemProps -->

## Component Props (MenuItemCheckbox/Switch/Radio)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuItemActionableProps -->

| Name                           | Type                    | Default | Description                                                                                |
| ------------------------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `checked` _bindable_           | `boolean` &#124; `null` |         | Whether the item is checked.                                                               |
| `value`                        | `string`                | `id`    | The value reported to the menu when the item is checked. Falls back to the id of the item. |
| `name`                         | `string`                | `id`    | The group of items this one belongs to. Falls back to the id of the item.                  |
| `MenuItemProps` without `href` |                         |         |                                                                                            |
| `ButtonProps<'button'>`        |                         |         |                                                                                            |

<!-- /props:MenuItemActionableProps -->

## Component Props (MenuGroup)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuGroupProps -->

| Name             | Type                           | Default | Description                             |
| ---------------- | ------------------------------ | ------- | --------------------------------------- |
| `ref` _bindable_ | `HTMLDivElement` &#124; `null` |         | The DOM reference of the group element. |
| `header`         | `string`                       |         | The label of the group.                 |
| `children`       | `Snippet`                      |         | The items of the group.                 |

<!-- /props:MenuGroupProps -->

## Component Props (MenuCommandBar)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuCommandBarProps -->

| Name                                                        | Type                           | Default          | Description                                                                                                    |
| ----------------------------------------------------------- | ------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                            | `HTMLDivElement` &#124; `null` |                  | The DOM reference of the command bar element.                                                                  |
| `position`                                                  | `'top'` &#124; `'bottom'`      | `'top'`          | Where the bar sits in the menu. A bar at the top has its divider below it, and one at the bottom has it above. |
| `label`                                                     | `string`                       | `'Commands'`     | The accessible name of the group of commands.                                                                  |
| `overflowLabel`                                             | `string`                       | `'More options'` | The accessible name of the button that opens the overflow.                                                     |
| `overflow`                                                  | `Snippet`                      |                  | The secondary commands. When present, a "more" button at the end of the bar opens them in a submenu.           |
| `showLabels`                                                | `boolean`                      | `false`          | Shows the label of every command below its icon. Without labels, every command is a square.                    |
| `showDividers`                                              | `boolean`                      | `false`          | Draws a divider between every two commands.                                                                    |
| `children`                                                  | `Snippet`                      |                  | The primary commands, as `MenuCommandBarItem`s.                                                                |
| `HTMLAttributes<HTMLDivElement>` without `children`, `role` |                                |                  |                                                                                                                |

<!-- /props:MenuCommandBarProps -->

## Component Props (MenuCommandBarItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:MenuCommandBarItemProps -->

| Name                                                                        | Type                              | Default | Description                                                                                                                                          |
| --------------------------------------------------------------------------- | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                                            | `HTMLButtonElement` &#124; `null` |         | The DOM reference of the button element.                                                                                                             |
| `icon`                                                                      | `Snippet` &#124; `Component`      |         | The icon of the command.                                                                                                                             |
| `label`                                                                     | `string`                          |         | The name of the command. Without visible labels it is the accessible name of the button and shows as its tooltip; with them it shows below the icon. |
| `disabled`                                                                  | `boolean`                         |         | Disables the user interaction.                                                                                                                       |
| `onclick`                                                                   | `(e: MouseEvent) => void`         |         | Called when the command is activated. The menu closes afterwards, unless it persists on item activation.                                             |
| `AriaAttributes` without `aria-label`                                       |                                   |         |                                                                                                                                                      |
| `id`, `class`, `onkeydown`, `onfocus`, `onblur` from `HTMLButtonAttributes` |                                   |         |                                                                                                                                                      |

<!-- /props:MenuCommandBarItemProps -->

---

# Number Box

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The NumberBox component allows users to input numeric values with specified constraints such as minimum, maximum, and step values.

## Usage

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

<NumberBox aria-label="Quantity" value={0} min={0} max={100} step={1} />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Variant

The variant prop determines the visual style of the NumberBox.

```svelte
<NumberBox aria-label="Quantity" hideActionButtons min={0} max={100} step={1} />
<NumberBox aria-label="Quantity" hideActionButtons min={0} max={100} step={1} variant="compact" />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:NumberBoxProps -->

| Name                          | Type                          | Default    | Description                                           |
| ----------------------------- | ----------------------------- | ---------- | ----------------------------------------------------- |
| `value` _bindable_            | `number` &#124; `null`        |            | The current value of the input.                       |
| `variant`                     | `'inline'` &#124; `'compact'` | `'inline'` | How the increment and decrement buttons are laid out. |
| `TextBoxProps` without `type` |                               |            |                                                       |

<!-- /props:NumberBoxProps -->

---

# Persona

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A Persona is a visual representation of a person that combines an avatar, presence status, and up to three lines of descriptive text.

## Usage

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

<Persona
	name="John Doe"
	primaryText="Software Engineer"
	secondaryText="Intranet"
	tertiaryText="Team A"
	presence={{ status: 'available' }}
	avatarProps={{ color: 'colorful' }}
/>
```

## Component API

### Text Align

A Persona supports three text alignments, with 'left' as the default position.

```svelte
<Persona name="Alex Johnson" avatarProps={{ initials: 'AJ' }} secondaryText="Available" />
<Persona name="Alex Johnson" avatarProps={{ initials: 'AJ' }} secondaryText="Available" textAlign="center" />
<Persona name="Alex Johnson" avatarProps={{ initials: 'AJ' }} secondaryText="Available" textAlign="right" />
```

### Text Position

A Persona supports four text positions: 'top', 'bottom', 'left', and 'right'. The default position is 'right'.

```svelte
<Persona name="Alex Johnson" avatarProps={{ initials: 'AJ' }} secondaryText="Available" />
<Persona
	name="Alex Johnson"
	avatarProps={{ initials: 'AJ' }}
	secondaryText="Available"
	textPosition="bottom"
	textAlign="center"
/>
<Persona name="Alex Johnson" avatarProps={{ initials: 'AJ' }} secondaryText="Available" textPosition="left" />
<Persona
	name="Alex Johnson"
	avatarProps={{ initials: 'AJ' }}
	secondaryText="Available"
	textPosition="top"
	textAlign="center"
/>
```

### Size

A Persona supports custom sizes, with a default of 42px. You can set the size using the size prop. This applies to both the avatar or presence-only display and all text.

```svelte
<Persona name="John Doe" size={24} />
<Persona name="John Doe" size={32} />
<Persona name="John Doe" size={56} />
```

### Avatar

A Persona wraps an avatar inside it, which can be customized with all the props available to the Avatar component.

```svelte
<Persona name="John Doe" avatarProps={{ color: 'attention' }} />
<Persona name="John Doe" avatarProps={{ color: 'colorful', idForColor: '' }} />
<Persona
	name="John Doe"
	avatarProps={{ image: { src: 'https://placehold.co/96x96/jpeg', alt: 'Placeholder Image' } }}
/>
```

### Presence

A Persona can display presence information, such as online status or availability. This is controlled through the presence prop, which accepts an object with a status key.

```svelte
<Persona name="John Doe" presence={{ status: 'available' }} />
<Persona name="John Doe" presence={{ status: 'away' }} />
<Persona name="John Doe" presence={{ status: 'busy' }} />
<Persona name="John Doe" presence={{ status: 'do-not-disturb' }} />
<Persona name="John Doe" presence={{ status: 'offline' }} />
<Persona name="John Doe" presence={{ status: 'out-of-office' }} />
<Persona name="John Doe" presence={{ status: 'blocked' }} />
<Persona name="John Doe" presence={{ status: 'unknown' }} />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:PersonaProps -->

| Name                       | Type                                                       | Default    | Description                                                                                                   |
| -------------------------- | ---------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `name`                     | `string`                                                   |            | The name of the person or entity represented by this Persona. It is also used by the avatar for its initials. |
| `size`                     | `number`                                                   | `42`       | The size of the avatar in pixels. The text scales with it.                                                    |
| `primaryText`              | `string`                                                   |            | Text to display below the name.                                                                               |
| `secondaryText`            | `string`                                                   |            | Text to display below the primary text.                                                                       |
| `tertiaryText`             | `string`                                                   |            | Text to display below the secondary text.                                                                     |
| `textAlign`                | `'left'` &#124; `'center'` &#124; `'right'`                | `'left'`   | How the text block is aligned.                                                                                |
| `textPosition`             | `'top'` &#124; `'bottom'` &#124; `'left'` &#124; `'right'` | `'right'`  | Where the text block sits relative to the avatar.                                                             |
| `presenceOnly`             | `boolean`                                                  |            | Renders the presence badge on its own, without the avatar behind it.                                          |
| `avatarAlign`              | `'start'` &#124; `'center'` &#124; `'end'`                 | `'center'` | How the avatar is aligned against the text block.                                                             |
| `element` _bindable_       | `HTMLDivElement` &#124; `null`                             |            | The DOM reference of the persona element.                                                                     |
| `avatarProps`              | `AvatarProps`                                              |            | The props to spread on the avatar.                                                                            |
| `presence`                 | `BadgePresence`                                            |            | The presence badge to display as a status indicator.                                                          |
| Element Attributes (`div`) |                                                            |            |                                                                                                               |

<!-- /props:PersonaProps -->

---

# PillButton

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A native checkbox styled as a Fluent 2 pill. Use it for independent filters or multiple choices. Its role is checkbox; Space toggles it. It uses the existing theme tokens in light and dark themes.

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

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

## Forms

Native input attributes go on the component: `name`, `value`, `form`, `required`, `defaultChecked`, `disabled`, `oninput`, `onchange` and ARIA attributes. Only a checked, enabled input with a name is submitted. With no value, the browser submits `on`. Multiple pills can share a name. Disabled fieldsets work natively.

Omit `checked` to initialize from `defaultChecked`. An explicit `checked` value takes precedence initially. Reset restores `defaultChecked` (false when omitted) and updates `bind:checked`. Validation uses the native checkbox; `required` requires that particular pill to be checked.

## Accessibility and styling

Visible children name the input. An enclosing `Label` is supported. Explicit `aria-label` or `aria-labelledby` takes precedence; provide one when children are omitted. Icons are decorative. Use plain label content without nested interactive controls. Keyboard focus surrounds the pill, and invalid fields expose native validity and support `aria-invalid` / `aria-describedby` for error messages.

`class`, `style`, input events and `ref` target the checkbox. Use `wrapperAttributes` and `wrapperRef` for the visible pill. Sizes are `small` (24px), `medium` (32px), `large` (40px) and `extra-large` (48px); appearances are `filled`, `outline` and `brand`.

Text scales with `size`: 12px, 14px, 16px and 18px respectively. `shape` defaults to `circular` and also supports `rounded` and `square`. Invalid labels and borders use the critical theme token; pair them with an explanatory error message.

Use `media` for a decorative avatar. A snippet receives `{ shape }`; a component receives the same object as props. Forward `shape` to `Avatar` so it follows the pill, including reactive changes. Media is hidden from assistive technologies and fitted to the control height with a uniform 4px inset. It takes precedence over `icon`.

```svelte
<script>
	import { Avatar, PillButton } from 'fluentui-svelte';
</script>

<PillButton checked>
	{#snippet media({ shape })}<Avatar {shape} name="Alex" />{/snippet}
	Alex
</PillButton>
```

## Props

<!-- props:PillButtonProps -->

| Name                                                                       | Type                                                                                 | Default      | Description                                                                                                                                                                                                    |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                                           | `HTMLInputElement` &#124; `null`                                                     |              | The DOM reference of the native checkbox.                                                                                                                                                                      |
| `wrapperRef` _bindable_                                                    | `HTMLElement` &#124; `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` &#124; `null`                                                              |              | Whether the pill is checked. When omitted, `defaultChecked` determines the initial state.                                                                                                                      |
| `appearance`                                                               | `'filled'` &#124; `'outline'` &#124; `'brand'`                                       | `'filled'`   | The pill appearance.                                                                                                                                                                                           |
| `size`                                                                     | `'small'` &#124; `'medium'` &#124; `'large'` &#124; `'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'` &#124; `'rounded'` &#124; `'square'`                                    | `'circular'` | The shape of the pill: `circular`, `rounded` or `square`.                                                                                                                                                      |
| `icon`                                                                     | `Snippet<[SVGAttributes<SVGElement>]>` &#124; `Component<SVGAttributes<SVGElement>>` |              | An optional decorative Fluent icon before the content.                                                                                                                                                         |
| `media`                                                                    | `Snippet<[PillButtonMediaProps]>` &#124; `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:` |                                                                                      |              |                                                                                                                                                                                                                |

<!-- /props:PillButtonProps -->

---

# Progress Bar

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A progress bar is a horizontal indicator that communicates the progress of an operation. Set `value` for determinate progress, or omit it for an indeterminate animation when the duration is unknown.

## Usage

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

<ProgressBar value={50} />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props section below.

## Examples

### Value

The value prop sets the current progress value of the bar. It should be a number between 0 and 100.

```svelte
<ProgressBar value={30} />
<ProgressBar value={50} />
<ProgressBar value={70} />
```

### Indeterminate

If you do not set the value prop, the progress bar enters an indeterminate state, meaning it does not have a specific value. This is useful for operations where the duration is unknown.

```svelte
<ProgressBar indeterminate />
```

### Hide Rail

The hideRail prop can be used to hide the progress bar rail.

```svelte
<ProgressBar value={50} hideRail />
```

### Status

The status prop allows you to set the status of the progress bar to 'paused' or 'error'. This changes the color of the progress bar to indicate different states.

```svelte
<ProgressBar value={50} status="paused" />
<ProgressBar value={50} status="error" />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ProgressBarProps -->

| Name                               | Type                           | Default | Description                                                                     |
| ---------------------------------- | ------------------------------ | ------- | ------------------------------------------------------------------------------- |
| `value` _bindable_                 | `number` &#124; `null`         |         | The current value of the progress bar. Leave it unset for an indeterminate bar. |
| `class`                            | `string`                       |         | The class to apply to the progress bar.                                         |
| `ref` _bindable_                   | `SVGElement` &#124; `null`     |         | The DOM reference of the progress bar element.                                  |
| `min`                              | `number`                       | `0`     | The minimum value of the progress bar.                                          |
| `max`                              | `number`                       | `100`   | The maximum value of the progress bar.                                          |
| `hideRail`                         | `boolean`                      |         | Whether to hide the rail element.                                               |
| `railElement` _bindable_           | `SVGRectElement` &#124; `null` |         | The DOM reference of the rail element.                                          |
| `secondaryTrackElement` _bindable_ | `SVGRectElement` &#124; `null` |         | The DOM reference of the secondary track element, used while indeterminate.     |
| `trackElement` _bindable_          | `SVGRectElement` &#124; `null` |         | The DOM reference of the track element.                                         |
| `status`                           | `'paused'` &#124; `'error'`    |         | The current status of the progress bar, which recolors the track.               |
| Element Attributes                 |                                |         |                                                                                 |

<!-- /props:ProgressBarProps -->

---

# Progress Ring

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A circular progress indicator that shows determinate or indeterminate progress, with paused and error states.

## Usage

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

<ProgressRing value={50} />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Value

The value prop determines the percentage of the progress ring that is filled. It should be a number between 0 and 100.

```svelte
<ProgressRing value={0} />
<ProgressRing value={25} />
<ProgressRing value={50} />
<ProgressRing value={75} />
<ProgressRing value={100} />
```

### Indeterminate

The indeterminate prop allows the progress ring to display an indeterminate state, which is useful when the progress cannot be determined.

```svelte
<ProgressRing indeterminate />
<ProgressRing indeterminate status="paused" />
<ProgressRing indeterminate status="error" />
```

### Hide Rail

The hideRail prop allows the progress ring to hide the rail, which is a background track for the progress indicator.

```svelte
<ProgressRing value={50} hideRail />
<ProgressRing value={75} hideRail />
<ProgressRing value={100} hideRail />
```

### Status

The status prop allows you to set the status of the progress ring for visual feedback. It accepts values such as 'paused' or 'error'.

```svelte
<ProgressRing value={40} />
<ProgressRing value={50} status="paused" />
<ProgressRing value={75} status="error" />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ProgressRingProps -->

| Name                      | Type                             | Default | Description                                                        |
| ------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------ |
| `value` _bindable_        | `number`                         | `0`     | The current value of the progress ring.                            |
| `min`                     | `number`                         | `0`     | The minimum value of the progress ring.                            |
| `max`                     | `number`                         | `100`   | The maximum value of the progress ring.                            |
| `indeterminate`           | `boolean`                        |         | Spins the ring continuously instead of reporting a value.          |
| `hideRail`                | `boolean`                        |         | Whether to hide the rail element.                                  |
| `size`                    | `number`                         | `32`    | The size of the progress ring in pixels.                           |
| `ref` _bindable_          | `SVGElement` &#124; `null`       |         | The DOM reference of the progress ring element.                    |
| `railElement` _bindable_  | `SVGCircleElement` &#124; `null` |         | The DOM reference of the rail element.                             |
| `trackElement` _bindable_ | `SVGCircleElement` &#124; `null` |         | The DOM reference of the track element.                            |
| `status`                  | `'paused'` &#124; `'error'`      |         | The current status of the progress ring, which recolors the track. |
| `class`                   | `string`                         |         | The class to apply to the progress ring.                           |
| Element Attributes        |                                  |         |                                                                    |

<!-- /props:ProgressRingProps -->

---

# Radio Button

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Radio Button component lets users choose a single option from a set of mutually exclusive choices.

## Usage

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

<RadioButton label="Option 1" />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props section below.

## Examples

### Grouping

While you can use name="inputName" to group items and have only one checked, you can use bind:group={someVariable} to update that variable with the value of the selected input and inspect it in your console. (Read More: https://svelte.dev/tutorial/svelte/group-inputs)

```svelte
<script>
	import { RadioButton } from 'fluentui-svelte';
	let groupValue = $state('');
	$inspect(groupValue);
</script>

<RadioButton label="Option 1" name="group1" value="$1" bind:group={groupValue} />
<RadioButton label="Option 2" name="group1" value="$2" bind:group={groupValue} />
<RadioButton label="Option 3" name="group1" value="$3" disabled bind:group={groupValue} />
```

### Disabled

The disabled prop can be used to disable a radio button, preventing user interaction.

```svelte
<RadioButton label="Enabled Option" value="D" />
<RadioButton label="Disabled Option" value="E" disabled />
```

### Checked

The checked prop allows you to control the checked state of the radio button. This is useful for controlled components.

```svelte
<RadioButton label="Checked Option" value="F" checked />
<RadioButton label="Unchecked Option" value="G" />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:RadioButtonProps -->

| Name                         | Type                             | Default | Description                                                                          |
| ---------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `label`                      | `string`                         |         | The label displayed next to the radio button. Inside a `Label`, it is not rendered   |
| `group` _bindable_           | `unknown`                        |         | Bindable value representing a group of radio inputs that the input will be bound to. |
| `checked` _bindable_         | `boolean` &#124; `null`          | `false` | Whether the radio button is selected.                                                |
| `ref` _bindable_             | `HTMLInputElement` &#124; `null` |         | The DOM reference of the radio button element.                                       |
| `wrapperAttributes`          | `HTMLAttributes`                 |         | The attributes to spread on the wrapper element.                                     |
| `wrapperRef` _bindable_      | `HTMLDivElement` &#124; `null`   |         | The DOM reference of the wrapper element.                                            |
| Element Attributes (`input`) |                                  |         |                                                                                      |

<!-- /props:RadioButtonProps -->

---

# Rating

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A rating lets users give a value to an item by selecting one of a row of stars. It supports half-filled stars, four sizes and a custom number of items.

## Usage

```svelte
<script>
	import { Rating } from 'fluentui-svelte';

	let value = $state(3);
</script>

<Rating bind:value />
```

## Component API

A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.

## Examples

### Bind the value

Use `bind:value` to read the rating the user picks.

```svelte
<script>
	let value = $state(3);
</script>

<Rating bind:value />
```

### Half stars

Set `step={0.5}` to let users pick half-filled stars.

```svelte
<Rating value={2.5} step={0.5} />
```

### Quarter stars

Until the user rates, a fractional `value` is drawn in quarters, which is handy to show an average. Once the user picks a star, the rating snaps to the `step`.

```svelte
<Rating value={3.75} />
```

### Size

Use `size` to choose between `small`, `medium`, `large` and `extra-large`.

```svelte
<Rating value={3} size="small" />
<Rating value={3} size="medium" />
<Rating value={3} size="large" />
<Rating value={3} size="extra-large" />
```

### Shape

Use `iconFilled` and `iconOutline` to replace the stars with any other icon component. Both fall back to the star when omitted, and partially filled items are clipped, so custom shapes also work with `step={0.5}`.

```svelte
<script>
	import HeartFilled from 'fluentui-icons-svelte/HeartFilled.svelte';
	import HeartRegular from 'fluentui-icons-svelte/HeartRegular.svelte';
</script>

<Rating value={3} iconFilled={HeartFilled} iconOutline={HeartRegular} />
```

### Max

Use `max` to change the number of stars.

```svelte
<Rating value={4} max={10} />
```

### Item label

Use `itemLabel` to customize the accessible label of each radio input.

```svelte
<Rating value={3} itemLabel={(rating) => `${rating} out of 5 stars`} />
```

The root is the control element. HTML attributes, class and ref apply to that element. There is no separate wrapper API.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:RatingProps -->

| Name                                                                                                                               | Type                                                                | Default                       | Description                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` _bindable_                                                                                                                 | `number`                                                            | `0`                           | The current rating. Fractions are drawn in quarters until the user rates.                                                                   |
| `max`                                                                                                                              | `number`                                                            | `5`                           | The number of items displayed. Must be a whole number greater than 1.                                                                       |
| `step`                                                                                                                             | `1` &#124; `0.5`                                                    | `1`                           | The precision of the rating. `0.5` allows half-filled items.                                                                                |
| `size`                                                                                                                             | `'small'` &#124; `'medium'` &#124; `'large'` &#124; `'extra-large'` | `'extra-large'`               | The size of the rating items.                                                                                                               |
| `iconFilled`                                                                                                                       | `Component`                                                         |                               | The icon of a filled item. Falls back to a filled star. Partially filled items are clipped, so it also works with half steps.               |
| `iconOutline`                                                                                                                      | `Component`                                                         |                               | The icon of an empty item. Falls back to an outlined star.                                                                                  |
| `itemLabel`                                                                                                                        | `(rating: number) => string`                                        | `` (rating) => `${rating}` `` | Generates the accessible label of the radio input for a rating value.                                                                       |
| `onChange`                                                                                                                         | `(value: number) => void`                                           |                               | Called when the user changes the rating.                                                                                                    |
| `wrapperRef` _bindable_                                                                                                            | `HTMLDivElement` &#124; `null`                                      |                               | The DOM reference of the radiogroup element.                                                                                                |
| `wrapperAttributes`                                                                                                                | `HTMLAttributes`                                                    |                               | The attributes to spread on the radiogroup element. This is where its `aria-label`, `aria-labelledby`, `aria-invalid`, `id` and `class` go. |
| `HTMLInputAttributes` without `type`, `value`, `checked`, `max`, `step`, `size`, `style`, `aria-label`, `aria-invalid`, `children` |                                                                     |                               |                                                                                                                                             |

<!-- /props:RatingProps -->

---

# SideNav

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

App navigation built on ListView. SideNavItem renders an anchor by default. Use `as="button"` for actions, or `as="li"` / `as="div"` for content with multiple controls. The navigation owns no router: set href and active from your app's current route.

## Usage

```svelte
<script>
	import { AppWindow, AppSurface, SideNav, SideNavItem } from 'fluentui-svelte';
	import HomeRegular from 'fluentui-icons-svelte/HomeRegular.svelte';
	import FolderRegular from 'fluentui-icons-svelte/FolderRegular.svelte';
	import SettingsRegular from 'fluentui-icons-svelte/SettingsRegular.svelte';
</script>

<AppWindow width={480} height={240}>
	<SideNav header="Workspace">
		<SideNavItem href="#home" label="Home" icon={HomeRegular} active />
		<SideNavItem href="#documents" label="Documents" icon={FolderRegular} />
		<SideNavItem href="#settings" label="Settings" icon={SettingsRegular} />
	</SideNav>
	<AppSurface style="padding: 1rem">Page content</AppSurface>
</AppWindow>
```

SideNav also works on its own, in any container with a height. Use `bind:collapsed` to control it, `SideNavBranch` to nest items and the `footer` snippet to pin items to the bottom.

## Modes and accessibility

Docked navigation occupies layout space and collapses to an icon rail. Labels remain available to assistive technology. Items without icons show their initial in the rail. Opening a branch from the rail expands the navigation first.

With `floating`, SideNav overlays AppWindow's body below its optional TitleBar. Closed floating navigation shows only the hamburger; opening it does not move page content. It is non-modal and does not trap focus. Escape, an outside pointer press, moving focus outside, and activating a SideNavItem close it. Set `closeOnSelect={false}` to keep it open after activation. A standalone floating SideNav needs a positioned parent.

Inside an AppWindow whose TitleBar has a global navigation button (`TitleBarLeftControls globalNav`), that button expands and collapses the SideNav, follows its state in `aria-expanded`, and SideNav hides its own hamburger. Set `showToggle` to `true` to keep both, or to `false` to hide the hamburger and control it yourself (`getAppWindowContext().state.sideNav.setCollapsed`). While a floating navigation is open, the global button is not an outside press.

The Button toggle exposes aria-expanded and aria-controls. SideNav is a named navigation landmark with native lists and links. The underlying ListView supplies arrow navigation, disabled-item handling and selection. Avoid menu/listbox roles for ordinary route navigation. There is no back button.

## Custom content and footer

Only two regions accept text, snippets or components: `topContent`, between the hamburger section and the list, and `footerContent`, after the list and before the pinned navigation footer. Strings render as text and are hidden in the compact rail. Snippets receive `{ collapsed, floating }`; components receive these as props, so they can render compact controls or hide their content. Use a snippet to supply other required component props.

The header is plain text. SideNavItem uses its label or ordinary ListViewItem children markup. The `footer` snippet contains navigation entries and remains pinned while the main list scrolls. Compose real Menu, TextBox, Avatar and Button components in the two custom regions.

## ListView customization

`listViewProps` customizes every list of the navigation: the main one, the footer and the ones inside a SideNavBranch. Defaults are role="list", selectionMode="none" and navigationMode="items". Keep native list semantics when using branches. Selection can be enabled and bound through `selectedItems`, shared across all of them. Set each item's value when using selection.

## Component Props (SideNav)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SideNavProps -->

| Name                                             | Type                                         | Default                 | Description                                                                                                                                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                 | `HTMLElement` &#124; `null`                  |                         | The DOM reference of the navigation landmark.                                                                                                                                                                                                                   |
| `label`                                          | `string`                                     | `'Main navigation'`     | The accessible name of the navigation landmark.                                                                                                                                                                                                                 |
| `collapsed` _bindable_                           | `boolean`                                    | `false`                 | Shows an icon rail when docked, or only the toggle when floating.                                                                                                                                                                                               |
| `position`                                       | `'left'` &#124; `'right'`                    | `'left'`                | The side of the window the navigation is on. It mirrors in right-to-left layouts, and AppSurface rounds the corners that face it.                                                                                                                               |
| `showToggle`                                     | `boolean`                                    | `Automatic`             | Whether the navigation shows its own hamburger toggle. By default it hides it when the title bar of its window has a global navigation button, which then controls the navigation. Set it to true to keep both, or to false to control the navigation yourself. |
| `floating`                                       | `boolean`                                    | `false`                 | Overlays the content of a positioned parent instead of taking layout space. The overlay is non-modal.                                                                                                                                                           |
| `width`                                          | `number` &#124; `string`                     | `200`                   | The expanded width. Numbers are pixels converted to rem; strings are CSS lengths.                                                                                                                                                                               |
| `expandLabel`                                    | `string`                                     | `'Expand navigation'`   | The accessible label of the toggle while collapsed.                                                                                                                                                                                                             |
| `collapseLabel`                                  | `string`                                     | `'Collapse navigation'` | The accessible label of the toggle while expanded.                                                                                                                                                                                                              |
| `closeOnSelect`                                  | `boolean`                                    | `true`                  | Closes a floating panel after activating a SideNavItem.                                                                                                                                                                                                         |
| `onCollapsedChange`                              | `(event: Event, collapsed: boolean) => void` |                         | Called when the user expands or collapses the navigation.                                                                                                                                                                                                       |
| `selectedItems` _bindable_                       | `string[]`                                   |                         | The selection shared by every list in the navigation. Selection is off by default.                                                                                                                                                                              |
| `listViewProps`                                  | `SideNavListViewProps`                       |                         | Overrides the defaults of every list in the navigation, the main one, the footer and the ones inside a SideNavBranch: native list semantics, no selection and one tab stop per item.                                                                            |
| `header`                                         | `string`                                     |                         | The text heading beside the hamburger button. Hidden in the compact rail.                                                                                                                                                                                       |
| `topContent`                                     | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content between the hamburger section and the list. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                                       |
| `footerContent`                                  | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content after the scrolling list and before the pinned footer. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                            |
| `footer`                                         | `Snippet`                                    |                         | Footer list items pinned to the bottom, outside the main list's scroll area.                                                                                                                                                                                    |
| `children`                                       | `Snippet`                                    |                         | Main navigation items. Use SideNavItem and SideNavBranch.                                                                                                                                                                                                       |
| `HTMLAttributes<HTMLElement>` without `children` |                                              |                         |                                                                                                                                                                                                                                                                 |

<!-- /props:SideNavProps -->

## Component Props (SideNavItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SideNavItemProps -->

| Name                                                                                                        | Type                                                                                          | Default | Description                                                                                    |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `as`                                                                                                        | `'li'` &#124; `'a'` &#124; `'button'` &#124; `'div'`                                          | `'a'`   | The HTML tag. Links are the default; use button for actions and li or div for custom controls. |
| `ref` _bindable_                                                                                            | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLButtonElement` &#124; `HTMLDivElement` |         | The DOM reference of the item.                                                                 |
| `label`                                                                                                     | `string`                                                                                      |         | The accessible label, also used as visible content when children are absent.                   |
| `icon`                                                                                                      | `Snippet` &#124; `Component`                                                                  |         | The decorative icon shown in both expanded and collapsed modes.                                |
| `children`                                                                                                  | `Snippet`                                                                                     |         | Optional item markup, following ListViewItem. The label is rendered when children are absent.  |
| `shape`, `value`, `active`, `role`, `disabled`, `checkmark`, `onAction`, `onfocus` from `ListViewItemProps` |                                                                                               |         |                                                                                                |
| HTML Attributes                                                                                             |                                                                                               |         |                                                                                                |

<!-- /props:SideNavItemProps -->

## Component Props (SideNavBranch)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SideNavBranchProps -->

| Name                                                                                                 | Type                                    | Default | Description                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`                                                                                              | `string`                                |         | The accessible label of the disclosure button. In the compact rail, its initial stands in when there is no icon.                                                                               |
| `icon`                                                                                               | `Snippet` &#124; `Component`            |         | The decorative icon before the label.                                                                                                                                                          |
| `expanded` _bindable_                                                                                | `boolean`                               | `false` | Whether the nested items are visible. Branches only expand or collapse and are never selectable. The compact rail reports a branch as collapsed, and opens the navigation when one is pressed. |
| `onExpandedChange`                                                                                   | `(e: Event, expanded: boolean) => void` |         | Called when a user expands or collapses the branch.                                                                                                                                            |
| `disabled`                                                                                           | `boolean`                               | `false` | Disables the disclosure button.                                                                                                                                                                |
| `ref` _bindable_                                                                                     | `HTMLButtonElement`                     |         | The DOM reference of the native disclosure button. Additional HTML attributes, including class and id, also target this button.                                                                |
| `wrapperRef` _bindable_                                                                              | `HTMLLIElement` &#124; `HTMLDivElement` |         | The DOM reference of the wrapper element, the list item that holds the button and the nested list.                                                                                             |
| `wrapperAttributes`                                                                                  | `HTMLAttributes`                        |         | The attributes to spread on the wrapper element.                                                                                                                                               |
| `shape`                                                                                              | `ListViewItemBranchProps['shape']`      |         | The disclosure button shape. Inherited from the list by default.                                                                                                                               |
| `children`                                                                                           | `Snippet`                               |         | The nested SideNavItem and SideNavBranch content.                                                                                                                                              |
| `HTMLButtonAttributes` without `children`, `role`, `type`, `value`, `aria-expanded`, `aria-controls` |                                         |         |                                                                                                                                                                                                |

<!-- /props:SideNavBranchProps -->

---

# Skeleton

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The skeleton component provides a placeholder for content that is loading, giving users a visual indication of where content will appear once it has loaded.

## Usage

The skeleton renders a placeholder element and sizes itself via standard HTML/CSS. Use the `style`, `class`, `width` and `height` attributes (or the `justify` prop) to control its dimensions.

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

<Skeleton style="width: 42px;" />
<Skeleton justify style="height: 12px;" />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Animation

The `animation` prop controls which type of animation is used for the skeleton. It can be set to `pulse` or `wave`. The default is `wave`.

```svelte
<Skeleton style="width: 72px;" animation="pulse" />
```

### Justify

Control if the skeleton should take the full width of its container or not. The default is `false`, meaning it will only take the `1:1` ratio of its width.

```svelte
<Skeleton style="width: 120px;" justify />
```

### Shape

The `shape` prop allows you to change the shape of the skeleton. It can be set to `circle`, `square`, or `rounded`. The default is `rounded`.

```svelte
<Skeleton style="width: 72px;" shape="circle" />
<Skeleton style="width: 72px;" shape="rounded" />
<Skeleton style="width: 72px;" shape="square" />
```

### As

The `as` prop lets you choose the HTML tag used to render the skeleton. Possible values: `'div'` (default) or `'span'`.

```svelte
<Skeleton as="span" style="width: 72px;" />
```

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SkeletonProps -->

| Name             | Type                                              | Default     | Description                                                   |
| ---------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------- |
| `as`             | `'div'` &#124; `'span'`                           | `'div'`     | The HTML element to render the skeleton as.                   |
| `animation`      | `'wave'` &#124; `'pulse'`                         | `'wave'`    | The animation played while the content is loading.            |
| `shape`          | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'` | The skeleton can have a circular, rounded or square shape.    |
| `justify`        | `boolean`                                         |             | The skeleton is justified to the full width of the container. |
| `ref` _bindable_ | `HTMLElement` &#124; `null`                       |             | The DOM reference of the skeleton element.                    |
| HTML Attributes  |                                                   |             |                                                               |

<!-- /props:SkeletonProps -->

---

# Slider

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A slider lets users select a value from a continuous or discrete range by dragging a thumb along a track. It supports horizontal and vertical orientations, tick marks, a value tooltip and reverse direction.

## Usage

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

<Slider value={50} min={0} max={100} />
```

## Component API

A slider allows users to select a value from a continuous or discrete range by moving a thumb along a track. It supports horizontal and vertical orientations, ticks, tooltips, and reverse direction.

## Examples

### Range and Step

Use the `min`, `max`, and `step` props to control the range of values and the increment between them.

```svelte
<Slider value={20} min={0} max={50} step={5} />
```

### Ticks

Provide an array of values to the `ticks` prop to render tick marks along the track. Use `tickPlacement` to position them `around`, `before`, or `after` the rail.

```svelte
<Slider value={50} step={25} ticks={[0, 25, 50, 75, 100]} />
```

### Vertical Orientation

Set `orientation="vertical"` to lay the slider out vertically.

```svelte
<Slider value={40} orientation="vertical" />
```

### Buffer

Set `buffer` to draw a second value on the rail, behind the track, such as how much of a media has loaded. It takes the scale of `value` and does not move the thumb.

```svelte
<Slider value={30} buffer={65} />
```

### Disabled

Set the `disabled` prop to prevent interaction with the slider.

```svelte
<Slider value={30} disabled />
```

The root is the control element. HTML attributes, class and ref apply to that element. There is no separate wrapper API.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:SliderProps -->

| Name                                         | Type                                          | Default        | Description                                                                                                                                                                                                        |
| -------------------------------------------- | --------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `value` _bindable_                           | `number`                                      | `0`            | The current value of the slider.                                                                                                                                                                                   |
| `defaultValue`                               | `number`                                      | `min`          | The value a form reset returns the slider to. A range input without one would fall back to an empty value.                                                                                                         |
| `min`                                        | `number`                                      | `0`            | The minimum value of the slider.                                                                                                                                                                                   |
| `max`                                        | `number`                                      | `100`          | The maximum value of the slider.                                                                                                                                                                                   |
| `step`                                       | `number`                                      | `1`            | How much the value moves on every step.                                                                                                                                                                            |
| `ticks`                                      | `number[]`                                    | `[]`           | The values the tick marks are drawn at.                                                                                                                                                                            |
| `tickPlacement`                              | `'around'` &#124; `'before'` &#124; `'after'` | `'around'`     | Where the tick marks sit relative to the rail.                                                                                                                                                                     |
| `prefix`                                     | `string`                                      | `''`           | Text prepended to the value in the tooltip.                                                                                                                                                                        |
| `suffix`                                     | `string`                                      | `''`           | Text appended to the value in the tooltip.                                                                                                                                                                         |
| `track`                                      | `boolean`                                     | `true`         | Whether to fill the rail up to the current value.                                                                                                                                                                  |
| `buffer`                                     | `number`                                      |                | A second value drawn on the rail behind the track, such as how much of a media has loaded. It takes the scale of `value` and does not move the thumb.                                                              |
| `orientation`                                | `'horizontal'` &#124; `'vertical'`            | `'horizontal'` | The direction the slider runs in.                                                                                                                                                                                  |
| `reverse`                                    | `boolean`                                     | `false`        | Runs the slider from the maximum to the minimum instead.                                                                                                                                                           |
| `disabled`                                   | `boolean`                                     | `false`        | Disables the user interaction.                                                                                                                                                                                     |
| `sync`                                       | `boolean`                                     |                | Snaps the thumb to the pointer as soon as it is pressed, instead of stepping towards it. Without it, a value between two steps is drawn as it is, while the native input, and so the form, holds the nearest step. |
| `tooltip`                                    | `boolean`                                     | `true`         | Whether to show the value in a tooltip while dragging.                                                                                                                                                             |
| `tooltipPlacement`                           | `Placement`                                   | `'top'`        | Where the tooltip is placed relative to the thumb.                                                                                                                                                                 |
| `tooltipContent`                             | `string` &#124; `Snippet` &#124; `Component`  |                | Custom content for the tooltip, replacing the plain value.                                                                                                                                                         |
| `tooltipPositionConfig`                      | `Partial<ComputePositionConfig>`              |                | The position configuration handed over to floating-ui for the tooltip, as in Tooltip.                                                                                                                              |
| `onChange`                                   | `(value: number) => void`                     |                | Called whenever the value changes.                                                                                                                                                                                 |
| `ref` _bindable_                             | `HTMLInputElement` &#124; `null`              |                | The DOM reference of the native range input that holds the value and takes the keyboard focus. The other attributes of the slider are applied to it.                                                               |
| `wrapperRef` _bindable_                      | `HTMLDivElement` &#124; `null`                |                | The DOM reference of the element that draws the slider.                                                                                                                                                            |
| `wrapperAttributes`                          | `HTMLAttributes`                              |                | The attributes to spread on the element that draws the slider.                                                                                                                                                     |
| `thumbRef` _bindable_                        | `HTMLElement` &#124; `null`                   |                | The DOM reference of the thumb element.                                                                                                                                                                            |
| `tooltipRef` _bindable_                      | `HTMLElement` &#124; `null`                   |                | The DOM reference of the tooltip element.                                                                                                                                                                          |
| `railRef` _bindable_                         | `HTMLElement` &#124; `null`                   |                | The DOM reference of the rail element.                                                                                                                                                                             |
| `trackRef` _bindable_                        | `HTMLElement` &#124; `null`                   |                | The DOM reference of the track element.                                                                                                                                                                            |
| `tickBarRef` _bindable_                      | `HTMLElement` &#124; `null`                   |                | The DOM reference of the tick bar element.                                                                                                                                                                         |
| `HiddenInputAttributes<HTMLInputAttributes>` |                                               |                |                                                                                                                                                                                                                    |

<!-- /props:SliderProps -->

---

# TabView

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

TabView lays a set of tabs out as a strip, in the shape a browser gives its document tabs. Every tab can carry an icon and a close button, and a new tab button can sit at the end of the strip.

The strip owns the selection and nothing else. What a tab opens is rendered by you, wherever it belongs on the page, so a tab can open a panel underneath it, swap a region somewhere else, or drive a route.

To create a tab strip, you will need to use the following components:

- `TabView`: The root component that creates the context every tab reads: which tab is selected, whether the tabs close, and how they take their width. It renders the `tablist` and, optionally, the new tab button.
- `TabViewTab`: A single tab of the strip. It reports its own selection and can carry an icon and a close button.

## Usage

A tab strip expects a `value` on every tab and an `activeTab` to match it against. Bind `activeTab` to follow the selection, and render whatever the selected tab opens yourself.

```svelte
<script>
	import { TabView, TabViewTab } from 'fluentui-svelte';

	let activeTab = $state('document');
</script>

<TabView bind:activeTab listAttributes={{ 'aria-label': 'Workspaces' }}>
	<TabViewTab id="tab-document" value="document">Document</TabViewTab>
	<TabViewTab id="tab-mail" value="mail">Mail</TabViewTab>
</TabView>

{#if activeTab === 'document'}
	<div role="tabpanel" aria-labelledby="tab-document">The document you are working on.</div>
{:else}
	<div role="tabpanel" aria-labelledby="tab-mail">Everything that landed in your inbox.</div>
{/if}
```

## Examples

### Closing Tabs

`closable` gives every tab a close button, and a single tab can opt in or out on its own. The strip never removes a tab: the tabs are your markup, so `onTabClose` hands the value back and leaves the removal — and which tab takes over — to you.

```svelte
<script>
	import { TabView, TabViewTab } from 'fluentui-svelte';

	let tabs = $state([
		{ value: 'notes', label: 'Notes' },
		{ value: 'draft', label: 'Draft' }
	]);
	let activeTab = $state('notes');

	const closeTab = (event, value) => {
		const index = tabs.findIndex((tab) => tab.value === value);
		tabs = tabs.filter((tab) => tab.value !== value);
		if (activeTab !== value) return;
		activeTab = tabs[Math.min(index, tabs.length - 1)]?.value ?? '';
	};
</script>

<TabView bind:activeTab closable onTabClose={closeTab}>
	{#each tabs as tab (tab.value)}
		<TabViewTab value={tab.value}>{tab.label}</TabViewTab>
	{/each}
</TabView>
```

### New Tab Button

`showNewTabButton` adds a button at the end of the strip, outside the `tablist` so it never reads as a tab. `onNewTab` fires when it is activated.

```svelte
<TabView bind:activeTab showNewTabButton onNewTab={addTab}>
	{#each tabs as tab (tab.value)}
		<TabViewTab value={tab.value}>{tab.label}</TabViewTab>
	{/each}
</TabView>
```

### Tab Width

`tabWidthMode` decides how the tabs take their width: `equal` shares the strip evenly, `size-to-content` sizes every tab to its own label, and `compact` shrinks every resting tab to its icon and spells out only the selected one.

```svelte
<TabView tabWidthMode="equal">...</TabView>
<TabView tabWidthMode="size-to-content">...</TabView>
<TabView tabWidthMode="compact">...</TabView>
```

### Disabled

A disabled tab cannot be selected, and the arrow keys pass over it rather than landing on it.

```svelte
<TabView activeTab="mail">
	<TabViewTab value="document">Document</TabViewTab>
	<TabViewTab value="mail">Mail</TabViewTab>
	<TabViewTab value="calendar" disabled>Calendar</TabViewTab>
</TabView>
```

## Component Props (TabView)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TabViewProps -->

| Name                       | Type                                                    | Default   | Description                                                                                                                                       |
| -------------------------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null`                          |           | The DOM reference of the element wrapping the strip.                                                                                              |
| `listRef` _bindable_       | `HTMLDivElement` &#124; `null`                          |           | The DOM reference of the tab list.                                                                                                                |
| `listAttributes`           | `HTMLAttributes`                                        |           | The Attributes to spread on the tab list element, where the `tablist` role and its label belong.                                                  |
| `activeTab` _bindable_     | `string`                                                |           | The value of the selected tab.                                                                                                                    |
| `onTabChange`              | `(event: Event, value: string) => void`                 |           | Fired when the selected tab changes.                                                                                                              |
| `closable`                 | `boolean`                                               | `false`   | Every tab shows a close button, unless the tab opts out of it.                                                                                    |
| `onTabClose`               | `(event: Event, value: string) => void`                 |           | Fired when a tab asks to be closed. Removing the tab is left to the consumer.                                                                     |
| `showNewTabButton`         | `boolean`                                               | `false`   | Shows the button that adds a new tab at the end of the strip.                                                                                     |
| `onNewTab`                 | `(event: MouseEvent) => void`                           |           | Fired when the new tab button is activated.                                                                                                       |
| `newTabButtonAttributes`   | `HTMLButtonAttributes`                                  |           | The props to spread on the new tab button.                                                                                                        |
| `tabWidthMode`             | `'equal'` &#124; `'size-to-content'` &#124; `'compact'` | `'equal'` | How the tabs take their width: sharing the strip evenly, sizing to their own content, or shrinking to the icon of every tab but the selected one. |
| `disableTabspot`           | `boolean`                                               | `false`   | Opts the strip out of the tabspot focus management, to wire your own.                                                                             |
| Element Attributes (`div`) |                                                         |           |                                                                                                                                                   |

<!-- /props:TabViewProps -->

## Component Props (TabViewTab)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TabViewTabProps -->

| Name                       | Type                                    | Default | Description                                                                             |
| -------------------------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null`          |         | The DOM reference of the tab element.                                                   |
| `value`                    | `string`                                |         | The value that identifies the tab. Defaults to a generated id.                          |
| `icon`                     | `Snippet` &#124; `Component`            |         | The icon to display before the label.                                                   |
| `closable`                 | `boolean`                               |         | Shows the close button of the tab. Falls back to the `closable` of the strip.           |
| `disabled`                 | `boolean`                               |         | Disables the user interaction.                                                          |
| `onClose`                  | `(event: Event, value: string) => void` |         | Fired when the tab asks to be closed, either from its close button or the `Delete` key. |
| Element Attributes (`div`) |                                         |         |                                                                                         |

<!-- /props:TabViewTabProps -->

## Keyboard Navigation

The strip is a single tab stop. `ArrowLeft` and `ArrowRight` walk the tabs, `Home` and `End` jump to the ends, `Enter` and `Space` select the focused tab, and `Delete` closes it when it is closable. `disableTabspot` hands the focus management back to you.

## Accessibility

The strip renders a `tablist` and every tab a `tab`, so give the list a name through the `aria-label` you pass in `listAttributes`. Since you render what a tab opens, give that element a `tabpanel` role and point its `aria-labelledby` at the `id` of its tab.

---

# Table

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A table displays sets of two dimensional data. Every part is a primitive that can be composed freely, so the table itself stays unopinionated about where the data comes from.

The components are deliberately low level: sorting, selection and filtering are not built in. The table renders what you hand it and reports the state you give it, so any data layer — plain runes, a store, a server load function — drives it without fighting an internal engine.

To create a table, you will need the following components:

- `Table`: The root component. It creates the context every other part reads: the size, whether the parts render as native table elements, whether the columns are sortable, and whether the arrow keys move between cells.
- `TableHeader`: The header section of the table. Renders a `thead`.
- `TableHeaderCell`: A column header. Renders a `th`, and turns into a sort button when the column is sortable.
- `TableBody`: The body section of the table. Renders a `tbody`.
- `TableRow`: A row of the table. Renders a `tr`, and can be filled to mark it as selected.
- `TableCell`: A single cell. Renders a `td`.

Other components that can be used within the table include:

- `TableCellLayout`: Lays a cell out as media, main content and an optional description.
- `TableSelectionCell`: A cell holding the checkbox or radio button that reports whether the row is selected.
- `TableCellActions`: Actions pinned to the end of a cell, revealed while the row is hovered or holds the focus.

## Usage

```svelte
<script>
	import { Table, TableHeader, TableHeaderCell, TableBody, TableRow, TableCell } from 'fluentui-svelte';

	const columns = ['File', 'Author', 'Last updated'];
	const items = [{ file: 'Meeting notes', author: 'Max Mustermann', lastUpdated: '7h ago' }];
</script>

<Table aria-label="Files">
	<TableHeader>
		<TableRow>
			{#each columns as column (column)}
				<TableHeaderCell>{column}</TableHeaderCell>
			{/each}
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each items as item (item.file)}
			<TableRow>
				<TableCell>{item.file}</TableCell>
				<TableCell>{item.author}</TableCell>
				<TableCell>{item.lastUpdated}</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

## More Examples

### Size

`size` sets the row height and the type scale of every part at once: `medium` (the default), `small` and `extra-small`.

```svelte
<Table size="extra-small">
	<TableHeader>
		<TableRow>
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		<TableRow>
			<TableCell>Meeting notes</TableCell>
		</TableRow>
	</TableBody>
</Table>
```

### Sort

`sortable` on the table turns every header cell into a button; a single cell can opt in or out with its own `sortable`. The table never sorts the data: give each header the `sortDirection` it should announce through `aria-sort`, handle `onclick`, and hand back the rows in the order you want.

```svelte
<script>
	let sortColumn = $state('file');
	let sortDirection = $state('ascending');

	const sorted = $derived(
		[...items].sort((a, b) => (sortDirection === 'ascending' ? 1 : -1) * a[sortColumn].localeCompare(b[sortColumn]))
	);

	const toggleSort = (column) => {
		if (sortColumn === column) {
			sortDirection = sortDirection === 'ascending' ? 'descending' : 'ascending';
		} else {
			sortColumn = column;
			sortDirection = 'ascending';
		}
	};
</script>

<Table sortable aria-label="Table with sort">
	<TableHeader>
		<TableRow>
			<TableHeaderCell
				sortDirection={sortColumn === 'file' ? sortDirection : undefined}
				onclick={() => toggleSort('file')}
			>
				File
			</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each sorted as item (item.file)}
			<TableRow>
				<TableCell>{item.file}</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

### Multiple Selection

`TableSelectionCell` displays the selection, it does not own it. The click on the indicator also reaches the row underneath, so the row is the single place to wire `onclick`: hitting the checkbox and hitting the rest of the row run the same handler. Mark the row with `aria-selected` and set `appearance="brand"` to fill it, then feed `checked` back from your own state. A header selection cell accepts `checked="mixed"` for the partial state, and `type="radio"` swaps the checkbox for a radio button when only one row can be selected.

```svelte
<script>
	let selected = $state([items[0].file]);

	const allSelected = $derived(selected.length === items.length);
	const someSelected = $derived(selected.length > 0 && !allSelected);

	const toggleRow = (file) => {
		selected = selected.includes(file) ? selected.filter((f) => f !== file) : [...selected, file];
	};
</script>

<Table aria-label="Table with multiselect">
	<TableHeader>
		<TableRow>
			<TableSelectionCell
				checked={allSelected ? true : someSelected ? 'mixed' : false}
				checkboxProps={{ 'aria-label': 'Select all rows' }}
				onclick={() => (selected = allSelected ? [] : items.map((item) => item.file))}
			/>
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each items as item (item.file)}
			{@const isSelected = selected.includes(item.file)}
			<TableRow
				aria-selected={isSelected}
				appearance={isSelected ? 'brand' : 'none'}
				onclick={() => toggleRow(item.file)}
			>
				<TableSelectionCell checked={isSelected} checkboxProps={{ 'aria-label': 'Select row' }} />
				<TableCell>{item.file}</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

### Single Selection

Set `type="radio"` on the selection cell when only one row can be selected at a time. Give every indicator the same `name` so the browser groups them, and use `invisible` on the header cell to keep the column aligned without offering a "select all".

```svelte
<script>
	let picked = $state(items[0].file);
</script>

<Table aria-label="Table with single select">
	<TableHeader>
		<TableRow>
			<TableSelectionCell type="radio" invisible />
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each items as item (item.file)}
			{@const isPicked = picked === item.file}
			<TableRow aria-selected={isPicked} appearance={isPicked ? 'brand' : 'none'} onclick={() => (picked = item.file)}>
				<TableSelectionCell type="radio" checked={isPicked} radioProps={{ name: 'file', 'aria-label': 'Select row' }} />
				<TableCell>{item.file}</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

### Subtle Selection

`subtle` keeps the indicator out of sight until the row is hovered, holds the focus, or is checked. It calms a dense table without losing the affordance. `invisible` is the sibling knob: it hides the indicator while it still takes up the same space, which keeps a row without a selection aligned with the rest.

```svelte
<TableRow aria-selected={isSelected} appearance={isSelected ? 'brand' : 'none'} onclick={() => toggleSubtle(item.file)}>
	<TableSelectionCell subtle checked={isSelected} checkboxProps={{ 'aria-label': 'Select row' }} />
	<TableCell>{item.file}</TableCell>
</TableRow>
```

### Cell Layout

`TableCellLayout` gives a cell the standard Fluent arrangement: `media` for an icon, an avatar or any other visual element, the children as the main content, and `description` for a second line below it. `appearance="primary"` enlarges the media and bolds the main content, which suits the first column of a table. `truncate` clips the content with an ellipsis instead of letting it wrap.

```svelte
<TableCell>
	<TableCellLayout media={DocumentRegular} description="7h ago" appearance="primary" truncate>
		Meeting notes
	</TableCellLayout>
</TableCell>
```

### Cell Actions

`TableCellActions` pins content to the end of a cell and reveals it while the row is hovered or holds the focus. It is usually a row of buttons, and `visible` keeps them on screen at all times. Give every action an accessible name: the row it belongs to is not announced with it.

```svelte
<TableCell>
	<TableCellLayout media={item.icon}>{item.file}</TableCellLayout>
	<TableCellActions>
		<Button appearance="subtle" shape="circular" aria-label="Edit {item.file}">
			<EditRegular />
		</Button>
		<Button appearance="subtle" shape="circular" aria-label="More actions for {item.file}">
			<MoreHorizontalRegular />
		</Button>
	</TableCellActions>
</TableCell>
```

### Keyboard Navigation

`enableTabspot` gives the table a single tab stop and moves the focus between cells with the arrow keys, with `Home`, `End`, `PageUp` and `PageDown` jumping further. It also switches the table over to the `role="grid"` pattern that navigation requires: the root reports `grid` and every data cell reports `gridcell`. There is no separate DataGrid component here, this prop is the whole opt-in. It needs the `FluentUISvelte` provider around the table, which is what starts the focus engine.

A cell decides how the cursor treats it with `focusMode`:

- `'cell'` (the default) makes the cell a stop of its own.
- `'group'` is for a cell with focusable content. The content is held out of the tab order, `Enter` steps into it, and `Escape` steps back out to the cell. Without it every button in every row would be its own tab stop, which is what a single tab stop exists to avoid.
- `'none'` skips the cell: the cursor passes over it rather than landing on it.

```svelte
<Table enableTabspot aria-label="Table with keyboard navigation">
	<TableHeader>
		<TableRow>
			<TableHeaderCell>File</TableHeaderCell>
			<TableHeaderCell>Actions</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each items as item (item.file)}
			<TableRow>
				<TableCell>{item.file}</TableCell>

				<!-- Enter steps into the cell to reach the buttons, Escape steps back out. -->
				<TableCell focusMode="group">
					<TableCellActions visible>
						<Button appearance="subtle" shape="circular" aria-label="Edit {item.file}">
							<EditRegular />
						</Button>
					</TableCellActions>
				</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

### Resizable Columns

`resizableColumns` gives every header cell a handle that drags its column wider or narrower, and pins the table to a fixed layout so the width sticks. A single column opts in or out with its own `resizable`.

- `columnSizing` sets a floor per column, by column position. Without one a column stops at 40px.
- `columnWidths` is the width of each column in pixels, by position. Bind it to read the widths back or to restore them later; leave it alone and the table keeps them itself.
- `onColumnResize` reports every change as `{ index, width }`.

The handle is a [WAI window splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/): it takes the focus and answers the left and right arrows, so the columns are reachable without a pointer. Name it with `resizeLabel` on the header cell — attributes you put on the cell reach the cell, never the handle inside it, so that prop is the only way in. It falls back to `"Resize column"`, which is worth replacing both to translate it and to say which column it resizes. Under `enableTabspot` a resizable header cell defaults to `focusMode="group"`, so `Enter` steps in to reach the handle and `Escape` steps back out.

```svelte
<script>
	// Bind only if you want to read the widths back, or restore them later.
	let columnWidths = $state([200, 180, 160]);
</script>

<Table
	resizableColumns
	bind:columnWidths
	columnSizing={[{ minWidth: 120 }, { minWidth: 100 }, { minWidth: 100 }]}
	onColumnResize={(e, { index, width }) => console.log(index, width)}
	aria-label="Table with resizable columns"
>
	<TableHeader>
		<TableRow>
			<TableHeaderCell>File</TableHeaderCell>
			<TableHeaderCell>Author</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		{#each items as item (item.file)}
			<TableRow>
				<TableCell>{item.file}</TableCell>
				<TableCell>{item.author}</TableCell>
			</TableRow>
		{/each}
	</TableBody>
</Table>
```

A fixed table sizes to the sum of its columns, so wrap it in a container with `overflow-x: auto` when the columns can grow past the space you have. Pair the cells with `<TableCellLayout truncate>` so a narrowed column clips its text instead of pushing it out.

### No Row Borders

`noRowBorders` drops the line that separates one row from the next, for a table that sits inside a card or another surface that already frames it.

```svelte
<Table noRowBorders aria-label="Table without row borders">
	<TableHeader>
		<TableRow>
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		<TableRow>
			<TableCell>Meeting notes</TableCell>
		</TableRow>
	</TableBody>
</Table>
```

### Non Native Elements

`noNativeElements` renders every part as a `div` and lays the rows out with flexbox instead of `display: table`. The ARIA roles that a native table provides implicitly are written out, so the semantics stay the same. Use it when the strict table layout gets in the way — virtualized rows and sticky headers are the usual reasons. A single part can still be overridden through its own `as` prop.

```svelte
<Table noNativeElements aria-label="Table rendered with divs">
	<TableHeader>
		<TableRow>
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody>
		<TableRow>
			<TableCell>Meeting notes</TableCell>
		</TableRow>
	</TableBody>
</Table>
```

### Virtualization

The table renders whatever you put inside it, so any virtualization library works. A semantic `table` is laid out by the browser in a single pass and fights a windowed list, so pair it with `noNativeElements`. Only a window of rows exists in the DOM, so report the real size of the data set with `aria-rowcount` on the table and `aria-rowindex` on each row — the header row is index 1, so the data starts at 2.

```svelte
<script>
	import SvelteVirtualList from '@humanspeak/svelte-virtual-list';

	const rows = Array.from({ length: 2000 }, (_, i) => ({ id: i, file: `Document ${i + 1}` }));

	// The virtualizer names its viewport a region, which a rowgroup cannot hold between itself and its rows.
	const presentational = (node) => {
		const region = node.querySelector('[role="region"]');
		region?.setAttribute('role', 'none');
		// A name or a tab stop would keep the role. The rows are reached with the arrow keys of the table.
		region?.removeAttribute('aria-label');
		region?.removeAttribute('tabindex');
	};
</script>

<Table noNativeElements style="min-width: 520px;" aria-label="Virtualized table" aria-rowcount={rows.length + 1}>
	<TableHeader>
		<TableRow aria-rowindex={1}>
			<TableHeaderCell>File</TableHeaderCell>
		</TableRow>
	</TableHeader>
	<TableBody style="height: 320px;" {@attach presentational}>
		<SvelteVirtualList items={rows} defaultEstimatedItemHeight={44}>
			{#snippet renderItem(row, index)}
				<TableRow aria-rowindex={index + 2}>
					<TableCell>{row.file}</TableCell>
				</TableRow>
			{/snippet}
		</SvelteVirtualList>
	</TableBody>
</Table>
```

`enableTabspot` does not follow the rows out of the rendered window on its own: the arrow keys stop at the edge of the slice the list has rendered. Wiring the two together needs a virtualization adapter, the way `TreeView` does with its `virtualizer` prop.

## Accessibility

- Always include a `TableHeader` row.
- When the table is preceded by a heading, point `aria-labelledby` at the id of that heading. When it has no visible label, give it an `aria-label`.
- Set a `min-width` so the table still reads at high zoom levels and on small screens.
- Do not override the `role` of the table parts. Keyboard navigation is the one case where the roles change, and `enableTabspot` handles it for you: it applies the [`role="grid"` pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) the navigation requires.

## Component Props (Table)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableProps -->

| Name                      | Type                                                         | Default    | Description                                                                                                                                                                          |
| ------------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `as`                      | `'table'` &#124; `'div'`                                     | `'table'`  | The HTML element to render the table as. Defaults to a `div` when `noNativeElements` is set.                                                                                         |
| `ref` _bindable_          | `HTMLTableElement` &#124; `HTMLDivElement`                   |            | The DOM reference of the table element.                                                                                                                                              |
| `size`                    | `'extra-small'` &#124; `'small'` &#124; `'medium'`           | `'medium'` | Affects the sizes of all table subcomponents.                                                                                                                                        |
| `noNativeElements`        | `boolean`                                                    | `false`    | Renders every table part as a `div` instead of a semantic table element. The layout switches from `display: table` to `display: flex`, which virtualization and sticky headers need. |
| `sortable`                | `boolean`                                                    | `false`    | Turns every header cell into a sort button. Individual cells can still opt in on their own.                                                                                          |
| `noRowBorders`            | `boolean`                                                    | `false`    | Drops the line that separates one row from the next.                                                                                                                                 |
| `enableTabspot`           | `boolean`                                                    | `false`    | Moves the focus between cells with the arrow keys, through a single tab stop. It also switches the table over to the `role="grid"` pattern, which that navigation requires.          |
| `virtualizer`             | `TableVirtualizer`                                           |            | Lets the arrow keys reach rows a windowed list has not rendered. Only read when `enableTabspot` is set, and the rows need an `aria-rowindex` for it to find them again.              |
| `resizableColumns`        | `boolean`                                                    | `false`    | Gives every header cell a handle that drags its column wider or narrower. It also pins the table to a fixed layout, so a column keeps the width it was given.                        |
| `columnWidths` _bindable_ | `number[]`                                                   |            | The width of each column in pixels, by column position. Columns left out keep their own size.                                                                                        |
| `columnSizing`            | `ColumnSizing[]`                                             |            | Per column limits, by column position.                                                                                                                                               |
| `onColumnResize`          | `(e: Event, data: { index: number; width: number }) => void` |            | Called whenever a column is dragged or nudged to a new width.                                                                                                                        |
| HTML Attributes           |                                                              |            |                                                                                                                                                                                      |

<!-- /props:TableProps -->

## Component Props (TableHeader)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableHeaderProps -->

| Name             | Type                                              | Default   | Description                                                                    |
| ---------------- | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
| `as`             | `'thead'` &#124; `'div'`                          | `'thead'` | The HTML element to render the header as. Inherited from the table by default. |
| `ref` _bindable_ | `HTMLTableSectionElement` &#124; `HTMLDivElement` |           | The DOM reference of the header element.                                       |
| HTML Attributes  |                                                   |           |                                                                                |

<!-- /props:TableHeaderProps -->

## Component Props (TableHeaderCell)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableHeaderCellProps -->

| Name             | Type                                           | Default           | Description                                                                                                                                                                                                                                                                                                                                                           |
| ---------------- | ---------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`             | `'th'` &#124; `'div'`                          | `'th'`            | The HTML element to render the header cell as. Inherited from the table by default.                                                                                                                                                                                                                                                                                   |
| `ref` _bindable_ | `HTMLTableCellElement` &#124; `HTMLDivElement` |                   | The DOM reference of the header cell element.                                                                                                                                                                                                                                                                                                                         |
| `sortable`       | `boolean`                                      |                   | Whether the column is sortable. Inherited from the table by default.                                                                                                                                                                                                                                                                                                  |
| `sortDirection`  | `'ascending'` &#124; `'descending'`            |                   | The direction the column is currently sorted in. Also sets `aria-sort`.                                                                                                                                                                                                                                                                                               |
| `sortIcon`       | `Snippet` &#124; `Component`                   |                   | The indicator rendered next to the label of a sortable column.                                                                                                                                                                                                                                                                                                        |
| `aside`          | `Snippet` &#124; `Component`                   |                   | Content placed after the label, outside the sort button.                                                                                                                                                                                                                                                                                                              |
| `focusMode`      | `'cell'` &#124; `'group'` &#124; `'none'`      | `'cell'`          | How the arrow keys treat the cell. `'group'` holds the focusable content of the cell out of the tab order until `Enter` steps in, and `Escape` steps back out. `'none'` skips the cell altogether. Only read when the table sets `enableTabspot`. A resizable header cell defaults to `'group'`, so the arrows reach its handle instead of leaving the column behind. |
| `resizable`      | `boolean`                                      |                   | Whether the column can be resized. Inherited from the table by default.                                                                                                                                                                                                                                                                                               |
| `resizeLabel`    | `string`                                       | `'Resize column'` | The accessible name of the resize handle. Give it a translated, and ideally per column, string — the attributes of the cell reach the cell, never the handle inside it.                                                                                                                                                                                               |
| HTML Attributes  |                                                |                   |                                                                                                                                                                                                                                                                                                                                                                       |

<!-- /props:TableHeaderCellProps -->

## Component Props (TableBody)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableBodyProps -->

| Name             | Type                                              | Default   | Description                                                                  |
| ---------------- | ------------------------------------------------- | --------- | ---------------------------------------------------------------------------- |
| `as`             | `'tbody'` &#124; `'div'`                          | `'tbody'` | The HTML element to render the body as. Inherited from the table by default. |
| `ref` _bindable_ | `HTMLTableSectionElement` &#124; `HTMLDivElement` |           | The DOM reference of the body element.                                       |
| HTML Attributes  |                                                   |           |                                                                              |

<!-- /props:TableBodyProps -->

## Component Props (TableRow)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableRowProps -->

| Name             | Type                                          | Default  | Description                                                                 |
| ---------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `as`             | `'tr'` &#124; `'div'`                         | `'tr'`   | The HTML element to render the row as. Inherited from the table by default. |
| `ref` _bindable_ | `HTMLTableRowElement` &#124; `HTMLDivElement` |          | The DOM reference of the row element.                                       |
| `appearance`     | `'none'` &#124; `'brand'` &#124; `'neutral'`  | `'none'` | How the row is filled. Intended to mark a selected row.                     |
| HTML Attributes  |                                               |          |                                                                             |

<!-- /props:TableRowProps -->

## Component Props (TableCell)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableCellProps -->

| Name             | Type                                           | Default  | Description                                                                                                                                                                                                                                       |
| ---------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`             | `'td'` &#124; `'div'`                          | `'td'`   | The HTML element to render the cell as. Inherited from the table by default.                                                                                                                                                                      |
| `ref` _bindable_ | `HTMLTableCellElement` &#124; `HTMLDivElement` |          | The DOM reference of the cell element.                                                                                                                                                                                                            |
| `focusMode`      | `'cell'` &#124; `'group'` &#124; `'none'`      | `'cell'` | How the arrow keys treat the cell. `'group'` holds the focusable content of the cell out of the tab order until `Enter` steps in, and `Escape` steps back out. `'none'` skips the cell altogether. Only read when the table sets `enableTabspot`. |
| HTML Attributes  |                                                |          |                                                                                                                                                                                                                                                   |

<!-- /props:TableCellProps -->

## Component Props (TableSelectionCell)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableSelectionCellProps -->

| Name             | Type                                           | Default      | Description                                                                    |
| ---------------- | ---------------------------------------------- | ------------ | ------------------------------------------------------------------------------ |
| `as`             | `'td'` &#124; `'div'`                          | `'td'`       | The HTML element to render the cell as. Inherited from the table by default.   |
| `ref` _bindable_ | `HTMLTableCellElement` &#124; `HTMLDivElement` |              | The DOM reference of the cell element.                                         |
| `type`           | `'checkbox'` &#124; `'radio'`                  | `'checkbox'` | A table can have two kinds of selection modes.                                 |
| `checked`        | `boolean` &#124; `'mixed'`                     | `false`      | Whether the row is selected. `'mixed'` renders the indeterminate state.        |
| `subtle`         | `boolean`                                      | `false`      | Only shows the indicator when it is checked, or the row is hovered or focused. |
| `invisible`      | `boolean`                                      | `false`      | Hides the indicator while it keeps taking up the same space.                   |
| `checkboxProps`  | `CheckboxProps`                                |              | The props to spread on the checkbox rendered when `type` is `'checkbox'`.      |
| `radioProps`     | `RadioButtonProps`                             |              | The props to spread on the radio button rendered when `type` is `'radio'`.     |
| HTML Attributes  |                                                |              |                                                                                |

<!-- /props:TableSelectionCellProps -->

## Component Props (TableCellLayout)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableCellLayoutProps -->

| Name             | Type                           | Default | Description                                                                    |
| ---------------- | ------------------------------ | ------- | ------------------------------------------------------------------------------ |
| `ref` _bindable_ | `HTMLDivElement` &#124; `null` |         | The DOM reference of the layout element.                                       |
| `media`          | `Snippet` &#124; `Component`   |         | An icon, an avatar or any other visual element placed before the main content. |
| `description`    | `string`                       |         | A second line of text that describes or complements the main content.          |
| `appearance`     | `'primary'`                    |         | Emphasizes the cell by enlarging the media and bolding the main content.       |
| `truncate`       | `boolean`                      |         | Clips the content with an ellipsis instead of letting it wrap.                 |
| HTML Attributes  |                                |         |                                                                                |

<!-- /props:TableCellLayoutProps -->

## Component Props (TableCellActions)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TableCellActionsProps -->

| Name             | Type                           | Default | Description                                                                          |
| ---------------- | ------------------------------ | ------- | ------------------------------------------------------------------------------------ |
| `ref` _bindable_ | `HTMLDivElement` &#124; `null` |         | The DOM reference of the actions element.                                            |
| `visible`        | `boolean`                      |         | Keeps the actions on screen instead of waiting for the row to be hovered or focused. |
| HTML Attributes  |                                |         |                                                                                      |

<!-- /props:TableCellActionsProps -->

---

# Tag

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A tag is a visual representation of an attribute, person or asset. It can be dismissed, and with `interactive` it becomes an interaction tag that has a primary action of its own. A `TagGroup` holds several tags, gives them a shared size, appearance and disabled state, and handles their selection and keyboard navigation.

## Usage

```svelte
<script>
	import { Tag, TagGroup } from 'fluentui-svelte';
	import CalendarMonthRegular from 'fluentui-icons-svelte/CalendarMonthRegular.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>
```

## Tag API

- A plain tag is a static `span`. With `dismissible` it is a single `button`: click, Enter, Space, Delete and Backspace dismiss it.
- With `interactive` the tag is a `div` holding a primary `button` (icon or media, primary and secondary text) that carries `onclick`, followed, when the tag is `dismissible`, by a separate dismiss `button`.
- The tag never removes itself: `onDismiss` only reports the `value`, the consumer owns the data.
- Do not use `media` together with `icon` on one tag.
- Use `interactive` only for a tag that has a primary action, and a plain tag for one that does not.

## Examples

### Appearance

A tag can have a `filled`, `outline` or `brand` appearance. The default is `filled`.

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

### Disabled

A tag can show that it cannot be interacted with. Every part of it is blocked, the dismiss control included.

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

### Dismiss

A dismissible tag shows a dismiss icon and becomes focusable. The tag only reports the dismissal through `onDismiss`, so remove it from your data. Ensure that focus is properly managed when all tags have been dismissed.

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

### Accessible name

Tell screen readers about the dismiss action. Either let the dismiss icon name the button, with `dismissLabel` (`'Dismiss'` by default), or name the tag itself with `aria-label` or `aria-labelledby`, and the dismiss icon is hidden from assistive technologies.

```svelte
<!-- 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>
```

### Interactive (primary action)

An interactive tag has a primary action (`onclick`) and, when it is dismissible, a secondary one that dismisses it. The dismiss button is named after both buttons, "Primary text Dismiss", through `aria-labelledby`. Use `primaryButtonAttributes` and `dismissButtonAttributes` to reach the buttons: a custom `id` on the primary button is followed by the dismiss button, and `aria-label` together with `aria-labelledby: undefined` gives the dismiss button a name that stands on its own.

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

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

### Icon

A tag can render a custom icon.

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

### Media

A tag can render media, for example an Avatar. Do not use it together with `icon`.

The media snippet receives the tag's current `shape`; forward it to `Avatar`. A media component receives the same value as a prop. Shape changes are reactive, and snippets that do not accept arguments still work.

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

### Secondary text

A tag can have a second line of text, given as a string or a snippet.

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

### Selected

`selected` paints the tag as selected. Inside a `TagGroup`, an interactive tag takes its selected state from the `selectedValues` of the group instead.

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

### Shape

A tag can be `circular`, `rounded` or `square`. The default is `circular`.

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

### Size

A tag supports `medium`, `small` and `extra-small` sizes. The default is `medium`.

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

## Component Props (Tag)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TagProps -->

| Name                      | Type                                                            | Default          | Description                                                                                                                                                                                                                                |
| ------------------------- | --------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appearance`              | `PillButtonAppearance`                                          | `'filled'`       | The tag can have a filled, outlined or brand appearance. Falls back to the `appearance` of the `TagGroup` it is in.                                                                                                                        |
| `size`                    | `'extra-small'` &#124; `'small'` &#124; `'medium'`              | `'medium'`       | The tag comes in three sizes. Falls back to the `size` of the `TagGroup` it is in.                                                                                                                                                         |
| `shape`                   | `'circular'` &#124; `'rounded'` &#124; `'square'`               | `'circular'`     | The tag can have a circular, rounded or square shape. Falls back to the `shape` of its `TagGroup`.                                                                                                                                         |
| `disabled`                | `boolean`                                                       | `false`          | Shows that the tag cannot be interacted with. A tag inside a disabled `TagGroup` is disabled too.                                                                                                                                          |
| `selected`                | `boolean`                                                       | `false`          | Paints the tag as selected. Inside a `TagGroup` an interactive tag takes its selected state from the `selectedValues` of the group instead.                                                                                                |
| `dismissible`             | `boolean`                                                       | `false`          | Shows a dismiss icon and lets the tag be dismissed. Falls back to the `dismissible` of the `TagGroup` it is in. A tag that is not interactive becomes a single button: activating it, or pressing Delete or Backspace on it, dismisses it. |
| `interactive`             | `boolean`                                                       | `false`          | Renders the tag as an interaction tag: a primary button that carries the action, followed, when the tag is dismissible, by a separate dismiss button. Use it for a tag that has a primary action, and a plain tag for one that does not.   |
| `value`                   | `string`                                                        |                  | Identifies the tag inside a `TagGroup`. It is what `onDismiss` and `onTagSelect` report. Falls back to a generated id.                                                                                                                     |
| `icon`                    | `Snippet` &#124; `Component`                                    |                  | An icon rendered before the text. Do not use it together with `media`.                                                                                                                                                                     |
| `media`                   | `Snippet` &#124; `Component`                                    |                  | A visual element rendered before the text, usually an `Avatar`. Receives the tag's current `shape`; forward it to the media component. Do not use it together with `icon`.                                                                 |
| `secondaryText`           | `string` &#124; `Snippet`                                       |                  | A second line of text that describes or complements the main text.                                                                                                                                                                         |
| `dismissIcon`             | `Snippet` &#124; `Component`                                    | `DismissRegular` | The icon of the dismiss control.                                                                                                                                                                                                           |
| `dismissLabel`            | `string`                                                        | `'Dismiss'`      | The accessible name of the dismiss control. When the tag is named through `aria-label` or `aria-labelledby` instead, the dismiss icon is hidden from assistive technologies.                                                               |
| `onDismiss`               | `(e: MouseEvent` &#124; `KeyboardEvent, value: string) => void` |                  | Called when the tag is dismissed. The consumer owns the data: the tag does not remove itself.                                                                                                                                              |
| `onclick`                 | `(e: MouseEvent) => void`                                       |                  | Called when the tag is activated. On an interactive tag it is the click of the primary button.                                                                                                                                             |
| `onkeydown`               | `(e: KeyboardEvent) => void`                                    |                  | Called when a key is pressed on the tag.                                                                                                                                                                                                   |
| `primaryButtonAttributes` | `HTMLButtonAttributes`                                          |                  | Attributes for the primary button of an interactive tag, for example `aria-haspopup`. If you give it a custom `id`, the dismiss button is named after it.                                                                                  |
| `dismissButtonAttributes` | `HTMLButtonAttributes`                                          |                  | Attributes for the dismiss button of an interactive tag. Use `aria-label` together with `aria-labelledby: undefined` to give the button a name that stands on its own.                                                                     |
| `children`                | `Snippet`                                                       |                  | The primary text of the tag.                                                                                                                                                                                                               |
| `ref` _bindable_          | `HTMLElement` &#124; `null`                                     |                  | The DOM reference of the tag element.                                                                                                                                                                                                      |
| HTML Attributes           |                                                                 |                  |                                                                                                                                                                                                                                            |

<!-- /props:TagProps -->

## TagGroup API

A tag group is a container for several tags. It gives its `size`, `appearance`, `disabled` and `dismissible` to the tags that do not set their own (a tag is disabled when either the tag or the group is), keeps the values of the selected interactive tags in `selectedValues`, and lets the arrow keys move focus between the tags, up and down included when the group wraps into several rows. Its default role is `toolbar`. When none of the tags is actionable, use `role="list"` on the group and `role="listitem"` on each tag.

### Usage

```svelte
<!-- 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>
```

### Disabled

A disabled group disables the whole collection of tags.

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

### Dismiss

A group can make its tags dismissible and reports every dismissal through `onDismiss`, with the `value` of the tag. The group does not remove the tag: do it in your data. Focus moves to a neighboring tag when one is dismissed, so the keyboard stays in the group; ensure that focus is properly managed when all tags have been dismissed.

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

### Select

Activating the primary button of an interactive tag toggles its `value` in `selectedValues`, and `onTagSelect` reports it. Remove a dismissed value from `selectedValues` yourself.

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

### Sizes

A group can set the default size of all its tags. It supports `medium`, `small` and `extra-small`. The default is `medium`.

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

## Component Props (TagGroup)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TagGroupProps -->

| Name                        | Type                                                                      | Default     | Description                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `shape`                     | `'circular'` &#124; `'rounded'` &#124; `'square'`                         |             | The shape given to tags that do not set their own.                                                             |
| `size`                      | `'extra-small'` &#124; `'small'` &#124; `'medium'`                        | `'medium'`  | The size given to the tags of the group that do not set their own.                                             |
| `appearance`                | `PillButtonAppearance`                                                    |             | The appearance given to the tags of the group that do not set their own.                                       |
| `disabled`                  | `boolean`                                                                 | `false`     | Disables every tag of the group.                                                                               |
| `dismissible`               | `boolean`                                                                 |             | Makes the tags of the group that do not set their own dismissible.                                             |
| `selectedValues` _bindable_ | `string[]`                                                                | `[]`        | The values of the selected interactive tags.                                                                   |
| `onTagSelect`               | `(e: MouseEvent, data: { value: string; selected: boolean }) => void`     |             | Called when an interactive tag of the group is activated, with the value it toggles.                           |
| `onDismiss`                 | `(e: MouseEvent` &#124; `KeyboardEvent, data: { value: string }) => void` |             | Called when a tag of the group is dismissed. The consumer owns the data: the group does not remove the tag.    |
| `role`                      | `HTMLAttributes<HTMLDivElement>['role']`                                  | `'toolbar'` | The role of the group. Use `list` together with `role="listitem"` on each tag when none of them is actionable. |
| `children`                  | `Snippet`                                                                 |             | The tags of the group.                                                                                         |
| `ref` _bindable_            | `HTMLDivElement` &#124; `null`                                            |             | The DOM reference of the group element.                                                                        |
| HTML Attributes             |                                                                           |             |                                                                                                                |

<!-- /props:TagGroupProps -->

---

# TagPicker

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

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. It is made of `TagPicker`, `TagPickerOption` and `TagPickerOptionGroup`.

## Usage

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

## TagPicker API

- `selectedOptions` holds the values of the chosen options. It is bindable, and every value shows as a tag.
- Selecting an option adds a tag and clears the text. The option is not offered again until its tag is removed.
- The options are filtered by what is typed in the input: a case-insensitive substring of the `text` of the option (its `value` when there is no `text`). The first match is highlighted.
- A multiple picker keeps the list open after each choice. With `single` a new choice replaces the tag and closes the list.
- Give the input an accessible name with `aria-label="..."`, and the group of tags one with `tagGroupProps`.
- Pressing Backspace in an empty input removes the last tag. Tell your users about it.
- A tag shows the `text` of its option, and keeps it once the option leaves the screen. This holds for a tag preselected through `selectedOptions` too, as long as the options are children of the TagPicker. A value that no option has is shown as it is, and so is every value during server-side rendering. To control what a tag says, render the tags yourself with the `tag` snippet.
- Do not use an interactive `Tag` inside a TagPicker.
- Keys: ArrowDown and ArrowUp open the list and move through the options, Enter chooses the option under the cursor, Escape and Tab close the list, Home and End move the caret of the input.

## Examples

### Default

The `tag` snippet renders the tag of a chosen option, here with an `Avatar` as its media. Render a `Tag` with the given `value`.

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

{#snippet tag({ value, text })}
	{#snippet media()}
		<Avatar aria-hidden="true" name={text} size={16} color="colorful" />
	{/snippet}
	<Tag {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="square" name={option} size={20} color="colorful" />
			{option}
		</TagPickerOption>
	{/each}
</TagPicker>
```

### Button

Make the input read only with `inputAttributes={{ readonly: true }}` to use the TagPicker as a button that opens the list.

```svelte
<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.

```svelte
<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`.

```svelte
<script>
	import ArrowDownFilled from 'fluentui-icons-svelte/ArrowDownFilled.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, and the first match is highlighted so that Enter chooses it. `notFoundText` is shown when no option is left.

```svelte
<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.

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

### No popover

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.

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

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

```svelte
{#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.

```svelte
<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.

```svelte
{#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.

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

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props (TagPicker)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TagPickerProps -->

| Name                                                                                                                                     | Type                                               | Default                  | Description                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shape`                                                                                                                                  | `'circular'` &#124; `'rounded'` &#124; `'square'`  | `'rounded'`              | Shape of the field and the default shape of its selected tags.                                                                                                                                    |
| `wrapperRef` _bindable_                                                                                                                  | `HTMLDivElement` &#124; `null`                     |                          | The DOM reference of the wrapper element.                                                                                                                                                         |
| `ref` _bindable_                                                                                                                         | `HTMLSelectElement` &#124; `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` &#124; `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'` &#124; `'large'` &#124; `'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` &#124; `Component` &#124; `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'` &#124; `'multiple'` &#124; `'size'` &#124; `'disabled'` &#124; `'children'>>` |                                                    |                          |                                                                                                                                                                                                   |

<!-- /props:TagPickerProps -->

## Component Props (TagPickerOption)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TagPickerOptionProps -->

| Name                                                                     | Type                          | Default | 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` &#124; `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` |                               |         |                                                                                                                      |

<!-- /props:TagPickerOptionProps -->

## Component Props (TagPickerOptionGroup)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TagPickerOptionGroupProps -->

| Name                                                  | Type                             | Default | Description                                      |
| ----------------------------------------------------- | -------------------------------- | ------- | ------------------------------------------------ |
| `label`                                               | `string`                         |         | The label of the group.                          |
| `ref` _bindable_                                      | `HTMLUListElement` &#124; `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` &#124; `null`    |         | The DOM reference of the wrapper element.        |
| `HTMLAttributes<HTMLUListElement>` without `children` |                                  |         |                                                  |

<!-- /props:TagPickerOptionGroupProps -->

---

# TextBox

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The TextBox control lets a user type text into an app. It's typically used to capture a single line of text, but can be configured to capture multiple lines of text. The text displays on the screen in a simple, uniform, plaintext format.

## Usage

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

<TextBox type="text" placeholder="Type here..." />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Type

The `type` prop specifies the type of input element. It can be set to various types such as `text`, `search`, `email`, `url`, `tel`, `password`, or `number`. This determines the behavior and validation of the input.

```svelte
<TextBox type="text" placeholder="Text" />
<TextBox type="search" placeholder="Search" />
<TextBox type="password" placeholder="Password" />
<TextBox type="number" placeholder="Number" />
```

### Size

The `size` prop sets the height, the font size and the horizontal padding of the input. It can be set to `small`, `medium` or `large`. The default is `medium`.

```svelte
<TextBox size="small" placeholder="Small" />
<TextBox size="medium" placeholder="Medium" />
<TextBox size="large" placeholder="Large" />
```

### Content Before and After

`contentBefore` and `contentAfter` render content inside the wrapper, before and after the input. They accept a string, a snippet or a component such as an icon.

```svelte
<script>
	import MailRegular from 'fluentui-icons-svelte/MailRegular.svelte';
</script>

<TextBox contentBefore="https://" placeholder="Website" />
<TextBox contentAfter=".com" placeholder="Domain" />
<TextBox contentBefore="$" contentAfter=".00" type="number" placeholder="Price" />
<TextBox contentBefore={MailRegular} placeholder="Email" />
```

### Input Element

The `ref` prop allows you to bind a reference to the underlying HTML input element (`bind:ref`). This can be useful for direct DOM manipulations or accessing native input properties. The wrapper element can be bound via `wrapperRef`.

### Readonly

The `readonly` prop makes the input field read-only, preventing users from modifying its value. This is useful for displaying information that should not be edited.

```svelte
<TextBox readonly value="Read-only value" />
```

### Placeholder

The `placeholder` prop sets the placeholder text for the input field, providing a hint to users about what to enter.

### Hide Buttons

The `hideActionButtons` prop allows you to hide the extra action buttons in the input, such as clear or submit buttons. This can be useful for a cleaner UI when those actions are not needed.

```svelte
<TextBox type="search" hideActionButtons placeholder="No action buttons" />
```

### Query Submitted

The `querySubmitted` event is triggered when a query is submitted, such as when the user presses Enter in a search input. This allows you to handle the submission of the input value.

### Text Changed

The `textChanged` event is triggered whenever the content of the text box changes. This can be used to react to user input in real-time, such as validating input or updating other parts of the UI.

### On Clear

The `onClear` event is triggered when the input is cleared, allowing you to handle any necessary actions when the user removes the input value.

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TextBoxProps -->

| Name                                 | Type                                                                   | Default            | Description                                                                                                                                      |
| ------------------------------------ | ---------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `shape`                              | `'circular'` &#124; `'rounded'` &#124; `'square'`                      | `'rounded'`        | Shape of the input surface, including its border and focus indicator.                                                                            |
| `type`                               | [`TextBoxTypes`](https://fluentui-svelte.dev/docs/types/#textboxtypes) | `'text'`           | The type of the input element.                                                                                                                   |
| `value` _bindable_                   | `string` &#124; `number`                                               |                    | The current value of the input.                                                                                                                  |
| `wrapperRef` _bindable_              | `HTMLDivElement` &#124; `null`                                         |                    | The DOM reference of the wrapper element.                                                                                                        |
| `ref` _bindable_                     | `HTMLInputElement` &#124; `null`                                       |                    | The DOM reference of the input element.                                                                                                          |
| `placeholder`                        | `string`                                                               | `'Fluent TextBox'` | The placeholder text for the input.                                                                                                              |
| `hideActionButtons`                  | `boolean`                                                              |                    | Whether to hide the extra action buttons in the input.                                                                                           |
| `justify`                            | `boolean`                                                              |                    | Make the input fill the full width of the container.                                                                                             |
| `contentBefore`                      | `string` &#124; `Snippet` &#124; `Component`                           |                    | Content rendered before the input, inside the wrapper.                                                                                           |
| `contentAfter`                       | `string` &#124; `Snippet` &#124; `Component`                           |                    | Content rendered after the input, inside the wrapper.                                                                                            |
| `size`                               | `'small'` &#124; `'medium'` &#124; `'large'`                           | `'medium'`         | The size of the input element.                                                                                                                   |
| `textChanged`                        | `(e: Event & unknown, text: string) => void`                           |                    | Occurs when content changes in the text box.                                                                                                     |
| `querySubmitted`                     | `(e: MouseEvent` &#124; `KeyboardEvent, query: string) => void`        |                    | The QuerySubmitted event occurs when: 1. The input type is 'search'. 2. While the focus is in the text box, press Enter or click the query icon. |
| `onClear`                            | `(e: MouseEvent) => void`                                              |                    | Occurs when the clear button is clicked.                                                                                                         |
| `children`                           | `Snippet`                                                              |                    | The children elements to render inside the input.                                                                                                |
| `wrapperAttributes`                  | `HTMLAttributes`                                                       |                    | The attributes to spread on the wrapper element.                                                                                                 |
| `HTMLInputAttributes` without `size` |                                                                        |                    |                                                                                                                                                  |

<!-- /props:TextBoxProps -->

---

# TextArea

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

Textarea allows the user to enter and edit multiline text.

## Usage

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

<TextArea placeholder="Type your message here..." />
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

## Examples

### Placeholder

The `placeholder` prop sets the placeholder text for the textarea, providing a hint to users about what to enter.

```svelte
<TextArea placeholder="Type your message here..." />
```

### Resize

The `resize` prop controls whether the textarea can be resized by the user. It can be set to `none`, `both`, `horizontal`, or `vertical`. This allows you to control the resizing behavior of the textarea.

```svelte
<TextArea resize="none" placeholder="No resize" />
<TextArea resize="vertical" placeholder="Vertical resize" />
<TextArea resize="both" placeholder="Resize both" />
```

### On Change

The `onChange` event is triggered whenever the content of the textarea changes. This can be used to react to user input in real-time, such as validating input or updating other parts of the UI.

```svelte
<TextArea onChange={(e) => console.log(e)} placeholder="Type..." />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TextAreaProps -->

| Name                             | Type                                                               | Default      | Description                                                           |
| -------------------------------- | ------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------- |
| `shape`                          | `Exclude<Shapes, 'circular'>`                                      | `'rounded'`  | Shape of the input surface, including its border and focus indicator. |
| `value` _bindable_               | `string`                                                           | `''`         | The current value of the textarea.                                    |
| `ref` _bindable_                 | `HTMLTextAreaElement` &#124; `null`                                |              | The DOM reference of the textarea element.                            |
| `placeholder`                    | `string`                                                           |              | The placeholder text for the textarea.                                |
| `resize`                         | `'none'` &#124; `'both'` &#124; `'horizontal'` &#124; `'vertical'` | `'vertical'` | Configures the resize behavior of the textarea.                       |
| `disabled`                       | `boolean`                                                          | `false`      | Disables the user interaction.                                        |
| `wrapperAttributes`              | `HTMLAttributes`                                                   |              | The attributes to spread on the wrapper element.                      |
| `wrapperRef` _bindable_          | `HTMLDivElement` &#124; `null`                                     |              | The DOM reference of the wrapper element.                             |
| `SvelteHTMLElements['textarea']` |                                                                    |              |                                                                       |

<!-- /props:TextAreaProps -->

---

# Time Picker

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

An input for selecting a time from carousel-style hour, minute, and second columns, in 12- or 24-hour format.

## Usage

```svelte
<script>
	import { TimePicker } from 'fluentui-svelte';

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

<TimePicker bind:value format={12} />
```

## Examples

### Clock Format

Use the `format` prop to choose between a 24-hour clock (`24`) and a 12-hour clock with an AM/PM column (`12`).

```svelte
<TimePicker format={24} />
<TimePicker format={12} />
```

### Hiding Columns

Use `hideHours`, `hideMinutes`, or `hideSeconds` to hide individual columns. By default the seconds column is shown.

```svelte
<TimePicker format={24} hideSeconds />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TimePickerProps -->

| Name                                         | Type                                   | Default                                                                   | Description                                                                                                                                |
| -------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `value` _bindable_                           | `string`                               | `''`                                                                      | Selected time as 24h `HH:mm` or `HH:mm:ss` (matches `<input type="time">`).                                                                |
| `format`                                     | `12` &#124; `24`                       | `24`                                                                      | Clock format: `24` (00-23) or `12` (01-12 with an AM/PM column).                                                                           |
| `open` _bindable_                            | `boolean`                              | `false`                                                                   | Controls the open state of the picker.                                                                                                     |
| `hideHours`                                  | `boolean`                              | `false`                                                                   | Removes the hour column.                                                                                                                   |
| `hideMinutes`                                | `boolean`                              | `false`                                                                   | Removes the minute column.                                                                                                                 |
| `hideSeconds`                                | `boolean`                              | `false`                                                                   | Removes the second column.                                                                                                                 |
| `ref` _bindable_                             | `HTMLInputElement` &#124; `null`       |                                                                           | The DOM reference of the native time input that holds the value. The other attributes of the picker are applied to it.                     |
| `buttonRef` _bindable_                       | `HTMLButtonElement` &#124; `null`      |                                                                           | The DOM reference of the button that opens the picker.                                                                                     |
| `buttonAttributes`                           | `HTMLButtonAttributes`                 |                                                                           | The attributes to spread on the button that opens the picker.                                                                              |
| `wrapperRef` _bindable_                      | `HTMLDivElement` &#124; `null`         |                                                                           | The DOM reference of the element wrapping the button and the native input.                                                                 |
| `wrapperAttributes`                          | `HTMLAttributes`                       |                                                                           | The attributes to spread on the wrapper element.                                                                                           |
| `popupLabel`                                 | `string`                               | `'Choose a time'`                                                         | The accessible name of the popup, which is announced as a dialog.                                                                          |
| `columnLabels`                               | `{ hour, minute, second, … (4 keys) }` | `{ hour: 'Hour', minute: 'Minute', second: 'Second', meridiem: 'AM/PM' }` | The names of the hour, minute, second and AM/PM columns: shown on the trigger while there is no time, and given to the lists of the popup. |
| `NativeFieldAttributes<HTMLInputAttributes>` |                                        |                                                                           |                                                                                                                                            |

<!-- /props:TimePickerProps -->

---

# TitleBar

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A title bar is the top bar of an app shell, laid out like the one of a Windows 11 app: the identity of the app and its navigation at the start, a search that grows and shrinks at the center, and the person picture and window controls at the end. It paints no background of its own, since it sits on the component that renders the window.

To create a title bar, you will need to use the following components:

- `TitleBar`: The root component. It lays the three areas out, keeps the search between its width limits and collapses it when asked.
- `TitleBarLeftControls`: The controls at the start of the bar: a back button, a global navigation button, and the icon, the name and the release tag of the app.
- `TitleBarRightControls`: The controls at the end of the bar: custom menus, the person picture, and the minimize, maximize and close buttons of the window.

## Usage

Compose the bar from its three areas through the `leftControls`, `search` and `rightControls` snippets. Every area is optional. `TitleBarLeftControls` and `TitleBarRightControls` follow the settings of the bar when they are rendered inside a `TitleBar`, and also work on their own. The window buttons only report the press, since minimizing, maximizing and closing the window is up to the host of your app.

```svelte
<script>
	import { TitleBar, TitleBarLeftControls, TitleBarRightControls } from 'fluentui-svelte';
	import AppsRegular from 'fluentui-icons-svelte/AppsRegular.svelte';
	import { getCurrentWindow } from '@tauri-apps/api/window';

	const appWindow = getCurrentWindow();
	let maximized = $state(false);
	appWindow.isMaximized().then((value) => (maximized = value));
</script>

<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls back globalNav appIcon={AppsRegular} appName="FluentUI App" releaseTag="PREVIEW" />
	{/snippet}
	{#snippet rightControls()}
		<TitleBarRightControls
			{maximized}
			personPic={{ name: 'Ada Lovelace' }}
			onMinimize={() => appWindow.minimize()}
			onWindowToggle={async () => {
				await appWindow.toggleMaximize();
				maximized = await appWindow.isMaximized();
			}}
			onClose={() => appWindow.close()}
		/>
	{/snippet}
</TitleBar>
```

## Examples

### Left Controls

`back` and `globalNav` show a button each and report the press through `onBack` and `onGlobalNav`. Inside an AppWindow with a SideNav, the global navigation button expands and collapses it, follows its state and takes the place of its hamburger (call `preventDefault()` in `onGlobalNav` to opt out of the toggle). Elsewhere, set `globalNavExpanded` while the navigation is open, or pass a snippet to `globalNav` to draw the button yourself.

```svelte
<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls
			back
			globalNav
			globalNavExpanded={navExpanded}
			onBack={() => history.back()}
			onGlobalNav={() => (navExpanded = !navExpanded)}
			appIcon={AppsRegular}
			appName="FluentUI App"
		/>
	{/snippet}
</TitleBar>
```

### App Icon

`appIcon` takes the URL of an image, a Fluent icon component, or a snippet that draws a custom SVG. With `appName` it is decorative and the name of the app identifies it. Without `appName` it has `role="img"` and `appIconLabel` names it.

```svelte
<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls appIcon="/logo.png" appName="Image URL" />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls appIcon={AppsRegular} appName="Fluent icon" />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls appName="Custom SVG">
			{#snippet appIcon(props)}
				<svg {...props} viewBox="0 0 16 16"><circle cx="8" cy="8" r="7" fill="currentColor" /></svg>
			{/snippet}
		</TitleBarLeftControls>
	{/snippet}
</TitleBar>
```

### Release Tag

`releaseTag` marks the release status of the app, such as PREVIEW or BETA, in a badge next to its name. It takes a string or a snippet.

```svelte
<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls appIcon={AppsRegular} appName="FluentUI App" releaseTag="PREVIEW" />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls appIcon={AppsRegular} appName="FluentUI App" releaseTag="BETA" />
	{/snippet}
</TitleBar>
```

### Search

The `search` snippet sits at the center of the bar and takes up the width the bar gives it, growing and shrinking with the window. A bar with a search is `tall` by default, which leaves the search room to breathe.

```svelte
<TitleBar searchMinWidth={120}>
	{#snippet leftControls()}
		<TitleBarLeftControls appIcon={AppsRegular} appName="FluentUI App" />
	{/snippet}
	{#snippet search()}
		<AutoSuggestBox placeholder="Search" aria-label="Search">
			<AutoSuggestBoxOption index={0} value="Documents">Documents</AutoSuggestBoxOption>
			<AutoSuggestBoxOption index={1} value="Pictures">Pictures</AutoSuggestBoxOption>
		</AutoSuggestBox>
	{/snippet}
	{#snippet rightControls()}
		<TitleBarRightControls />
	{/snippet}
</TitleBar>
```

### Search Width

`searchMinWidth` and `searchMaxWidth` set how far the search shrinks and grows. Numbers are pixel values converted to rem using the current root font size, with a 16px fallback during SSR. For example, 200 becomes 10rem at a 20px root and still renders as 200px. A string is any CSS length.

```svelte
<TitleBar searchMinWidth={100} searchMaxWidth={180}>...</TitleBar>
<TitleBar searchMinWidth="30%" searchMaxWidth="60%">...</TitleBar>
```

### Collapsed Search

`searchCollapsed` manually folds the search into a button; resizing does not collapse it automatically. Pressing the button expands the search and moves the focus into the first available control. Bind it to follow the state. Leave enough room for the expanded search and the side controls, or lower `searchMinWidth`. Long app names are truncated, but navigation and window buttons still need room.

```svelte
<script>
	let collapsed = $state(false);
</script>

<TitleBar searchMinWidth={120} bind:searchCollapsed={collapsed}>
	{#snippet search()}
		<AutoSuggestBox placeholder="Search" aria-label="Search" />
	{/snippet}
	...
</TitleBar>
```

### Window Controls

`hideMinimize`, `hideWindowToggle` and `hideClose` each take a window button out of the bar. `onMinimize`, `onWindowToggle` and `onClose` report the press.

```svelte
<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls hideMinimize />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls hideWindowToggle />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls hideClose />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls hideMinimize hideWindowToggle />
	{/snippet}
</TitleBar>
```

### Maximized

While `maximized` is set, the maximize button becomes a restore button, with the icon and the label that go with it.

```svelte
<script>
	let maximized = $state(false);
	appWindow.isMaximized().then((value) => (maximized = value));
</script>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls {maximized} onWindowToggle={() => (maximized = !maximized)} />
	{/snippet}
</TitleBar>
```

### Person Picture

`personPic` takes the props of an `Avatar`, such as its `image`, drawn at 24 pixels unless you set a size. Add `onPersonPicClick` to turn the picture into a button, such as the one that opens an account.

```svelte
<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls personPic={{ name: 'Ada Lovelace', image: { src: 'https://placehold.co/120x120/jpeg' } }} />
	{/snippet}
</TitleBar>

<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls
			personPic={{ name: 'Grace Hopper', image: { src: 'https://placehold.co/120x120/jpeg' }, size: 28 }}
			onPersonPicClick={() => openAccount()}
		/>
	{/snippet}
</TitleBar>
```

### Custom Menu

The `customMenu` snippet places your own actions before the person picture, such as a settings menu.

```svelte
<TitleBar>
	{#snippet rightControls()}
		<TitleBarRightControls personPic={{ name: 'Ada Lovelace', image: { src: 'https://placehold.co/120x120/jpeg' } }}>
			{#snippet customMenu()}
				<Menu>
					<MenuTrigger>
						{#snippet children({ state, menuTriggerProps })}
							<Button bind:ref={state.ref} {...menuTriggerProps} appearance="subtle" aria-label="Settings">
								<SettingsRegular width="1rem" height="1rem" />
							</Button>
						{/snippet}
					</MenuTrigger>
					<MenuPopover>
						<MenuList>
							<MenuItem>Preferences</MenuItem>
							<MenuItem>Keyboard shortcuts</MenuItem>
						</MenuList>
					</MenuPopover>
				</Menu>
			{/snippet}
		</TitleBarRightControls>
	{/snippet}
</TitleBar>
```

### Labels

The accessible names of the buttons default to English. Pass `backLabel`, `globalNavLabel`, `searchLabel`, `minimizeLabel`, `maximizeLabel`, `restoreLabel` and `closeLabel` to translate them.

```svelte
<TitleBar>
	{#snippet leftControls()}
		<TitleBarLeftControls back globalNav backLabel="Atrás" globalNavLabel="Menú de navegación" />
	{/snippet}
	{#snippet rightControls()}
		<TitleBarRightControls
			minimizeLabel="Minimizar"
			maximizeLabel="Maximizar"
			restoreLabel="Restaurar"
			closeLabel="Cerrar"
		/>
	{/snippet}
</TitleBar>
```

### Tab Order

The buttons of the bar are in the tab order by default. Set `tabbable={false}` only when a desktop host provides an alternative keyboard route to these actions. The content you place in the snippets keeps its own tab order.

```svelte
<TitleBar tabbable>
	{#snippet leftControls()}
		<TitleBarLeftControls back globalNav appName="FluentUI App" />
	{/snippet}
	{#snippet rightControls()}
		<TitleBarRightControls />
	{/snippet}
</TitleBar>
```

### Drag Region

`dragRegionProps` is spread on the bar, its start and end areas, and the app identity, so a host that moves the window can tell where to grab the bar. Use `data-tauri-drag-region` for Tauri, or a pointer handler for any other host.

```svelte
<TitleBar dragRegionProps={{ 'data-tauri-drag-region': true }}>...</TitleBar>

<TitleBar dragRegionProps={{ onpointerdown: (e) => e.target === e.currentTarget && appWindow.startDragging() }}>
	...
</TitleBar>
```

## Component Props (TitleBar)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TitleBarProps -->

| Name                                             | Type                        | Default    | Description                                                                                                                                                                                                                                                                  |
| ------------------------------------------------ | --------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                 | `HTMLElement` &#124; `null` |            | The DOM reference of the title bar element.                                                                                                                                                                                                                                  |
| `leftControls`                                   | `Snippet`                   |            | The controls at the start of the bar: back, navigation, and the identity of the app. Render a `TitleBarLeftControls` here.                                                                                                                                                   |
| `search`                                         | `Snippet`                   |            | The search at the center of the bar, which grows and shrinks with the window between `searchMinWidth` and `searchMaxWidth`.                                                                                                                                                  |
| `rightControls`                                  | `Snippet`                   |            | The controls at the end of the bar: custom menus, the person picture, and the window buttons. Render a `TitleBarRightControls` here.                                                                                                                                         |
| `tall`                                           | `boolean`                   |            | Uses the tall bar, which leaves a search room to breathe. It is on by default when `search` is provided.                                                                                                                                                                     |
| `searchMinWidth`                                 | `number` &#124; `string`    | `200`      | The narrowest the search gets while the window shrinks. A number is in pixels, converted to rem using the current root font size, with a 16px fallback during SSR. A string is any CSS length.                                                                               |
| `searchMaxWidth`                                 | `number` &#124; `string`    | `480`      | The widest the search gets while the window grows. A number is in pixels, converted to rem using the current root font size, with a 16px fallback during SSR. A string is any CSS length.                                                                                    |
| `searchCollapsed` _bindable_                     | `boolean`                   | `false`    | Manually collapses the search into a button; it does not collapse automatically on resize. Pressing the button expands the search again and moves the focus into the first available control. The host must leave enough room for the expanded search and the side controls. |
| `searchLabel`                                    | `string`                    | `'Search'` | The accessible name of the button that stands in for a collapsed search.                                                                                                                                                                                                     |
| `tabbable`                                       | `boolean`                   | `true`     | Lets the Tab key reach the buttons of the bar. Set to false only when the desktop host provides an alternative keyboard route to these actions. The content you render in the snippets is not affected.                                                                      |
| `dragRegionProps`                                | `HTMLAttributes`            |            | The attributes that make the bar draggable for the host that moves the window, such as `data-tauri-drag-region` for Tauri. They are spread on the bar, its start and end areas, and the app identity.                                                                        |
| `HTMLAttributes<HTMLElement>` without `children` |                             |            |                                                                                                                                                                                                                                                                              |

<!-- /props:TitleBarProps -->

## Component Props (TitleBarLeftControls)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TitleBarLeftControlsProps -->

| Name                                                | Type                                         | Default             | Description                                                                                                                                                                   |
| --------------------------------------------------- | -------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLDivElement` &#124; `null`               |                     | The DOM reference of the controls element.                                                                                                                                    |
| `back`                                              | `boolean`                                    | `false`             | Shows the back button.                                                                                                                                                        |
| `backDisabled`                                      | `boolean`                                    | `false`             | Disables the back button, for when there is nowhere to go back to.                                                                                                            |
| `onBack`                                            | `MouseEventHandler<HTMLButtonElement>`       |                     | Called when the back button is pressed.                                                                                                                                       |
| `backLabel`                                         | `string`                                     | `'Back'`            | The accessible name of the back button.                                                                                                                                       |
| `globalNav`                                         | `boolean` &#124; `Snippet`                   | `false`             | Shows the global navigation button, or replaces it with the snippet you provide.                                                                                              |
| `globalNavExpanded`                                 | `boolean`                                    | `false`             | Whether the navigation the global navigation button controls is expanded. Inside an AppWindow with a SideNav, it follows the SideNav and the button expands and collapses it. |
| `onGlobalNav`                                       | `MouseEventHandler<HTMLButtonElement>`       |                     | Called when the global navigation button is pressed. Call `preventDefault()` to keep it from toggling the SideNav of the window.                                              |
| `globalNavLabel`                                    | `string`                                     | `'Navigation menu'` | The accessible name of the global navigation button.                                                                                                                          |
| `appIcon`                                           | `string` &#124; `Snippet` &#124; `Component` |                     | The icon of the app: the URL of an image, an icon component, or a snippet that draws a custom SVG.                                                                            |
| `appIconLabel`                                      | `string`                                     | `'Application'`     | The accessible name of the app icon when appName is absent. Set it to the app's name for an icon-only identity.                                                               |
| `appName`                                           | `string`                                     |                     | The name of the app.                                                                                                                                                          |
| `releaseTag`                                        | `string` &#124; `Snippet`                    |                     | The release status of the app, such as `PREVIEW` or `BETA`.                                                                                                                   |
| `children`                                          | `Snippet`                                    |                     | More content after the release tag, such as a subtitle.                                                                                                                       |
| `HTMLAttributes<HTMLDivElement>` without `children` |                                              |                     |                                                                                                                                                                               |

<!-- /props:TitleBarLeftControlsProps -->

## Component Props (TitleBarRightControls)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TitleBarRightControlsProps -->

| Name                                                | Type                                   | Default      | Description                                                                                                                                                          |
| --------------------------------------------------- | -------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_                                    | `HTMLDivElement` &#124; `null`         |              | The DOM reference of the controls element.                                                                                                                           |
| `hideMinimize`                                      | `boolean`                              | `false`      | Hides the minimize button.                                                                                                                                           |
| `hideWindowToggle`                                  | `boolean`                              | `false`      | Hides the maximize and restore button.                                                                                                                               |
| `hideClose`                                         | `boolean`                              | `false`      | Hides the close button.                                                                                                                                              |
| `maximized`                                         | `boolean`                              | `false`      | Whether the window is maximized, which turns the maximize button into a restore button. Inherits AppWindow's maximized state when omitted, or false when standalone. |
| `onMinimize`                                        | `MouseEventHandler<HTMLButtonElement>` |              | Called when the minimize button is pressed.                                                                                                                          |
| `onWindowToggle`                                    | `MouseEventHandler<HTMLButtonElement>` |              | Called when the maximize or restore button is pressed.                                                                                                               |
| `onClose`                                           | `MouseEventHandler<HTMLButtonElement>` |              | Called when the close button is pressed.                                                                                                                             |
| `minimizeLabel`                                     | `string`                               | `'Minimize'` | The accessible name of the minimize button.                                                                                                                          |
| `maximizeLabel`                                     | `string`                               | `'Maximize'` | The accessible name of the maximize button.                                                                                                                          |
| `restoreLabel`                                      | `string`                               | `'Restore'`  | The accessible name of the restore button.                                                                                                                           |
| `closeLabel`                                        | `string`                               | `'Close'`    | The accessible name of the close button.                                                                                                                             |
| `personPic`                                         | `AvatarProps`                          |              | The props of the `Avatar` that shows the person. Its size is 24 unless you set one.                                                                                  |
| `onPersonPicClick`                                  | `MouseEventHandler<HTMLButtonElement>` |              | Called when the person picture is pressed, which turns it into a button.                                                                                             |
| `customMenu`                                        | `Snippet`                              |              | The custom menus or actions placed before the person picture.                                                                                                        |
| `HTMLAttributes<HTMLDivElement>` without `children` |                                        |              |                                                                                                                                                                      |

<!-- /props:TitleBarRightControlsProps -->

---

# Toggle Switch

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A toggle switch represents a physical switch that allows someone to choose between two mutually exclusive options. For example, 'On/Off' and 'Show/Hide'. Choosing an option should produce an immediate result.

## Usage

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

<ToggleSwitch aria-label="Notifications" />
<ToggleSwitch label="Toggle me" />
<ToggleSwitch label="I'm disabled" disabled />
```

## Examples

### States

A toggle switch can be labeled, checked, or disabled.

```svelte
<ToggleSwitch label="Off" />
<ToggleSwitch label="On" checked />
<ToggleSwitch label="Disabled" disabled />
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:ToggleSwitchProps -->

| Name                         | Type                             | Default | Description                                                                         |
| ---------------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `checked` _bindable_         | `boolean` &#124; `null`          |         | Whether the switch is on.                                                           |
| `ref` _bindable_             | `HTMLInputElement` &#124; `null` |         | The DOM reference of the input element.                                             |
| `label`                      | `string`                         |         | The label displayed next to the input element. Inside a `Label`, it is not rendered |
| `wrapperAttributes`          | `HTMLAttributes`                 |         | The attributes to spread on the wrapper element.                                    |
| `wrapperRef` _bindable_      | `HTMLDivElement` &#124; `null`   |         | The DOM reference of the wrapper element.                                           |
| Element Attributes (`input`) |                                  |         |                                                                                     |

<!-- /props:ToggleSwitchProps -->

---

# Tooltip

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

A tooltip displays additional information about another component. The information is displayed above and near the target component.

## Usage

```svelte
<script>
	import { Tooltip, Button } from 'fluentui-svelte';
</script>

<Tooltip content="Tooltip content" relationship="description" withArrow>
	{#snippet children(attrs)}
		<Button {...attrs}>Hover over me</Button>
	{/snippet}
</Tooltip>
```

## Component API

A brief explanation of the props that really need explaining. You can see the rest of the props in the Component Props table below.

### Content

The content prop specifies the content to be displayed in the tooltip when the user hovers over the target element. This can be a string, a Svelte component, or a Snippet.

### Position

The positionConfig prop allows you to specify your own custom position using Floating UI's position configuration. This gives you more control over the placement of the tooltip, allowing you to define custom offsets, middleware, and more.

### With Arrow

The withArrow prop is a boolean that, when set to true, adds an arrow to the tooltip pointing towards the target element. This can help visually connect the tooltip to the element it is describing.

```svelte
<Tooltip content="Tooltip with arrow" relationship="description" withArrow>
	{#snippet children(attrs)}
		<Button {...attrs}>With arrow</Button>
	{/snippet}
</Tooltip>
```

### Delay

The openDelay and hideDelay props allow you to specify a delay, in milliseconds, before the tooltip is shown or hidden after the user hovers over the target element. This can help prevent the tooltip from appearing or disappearing too quickly.

```svelte
<Tooltip content="Delayed tooltip" openDelay={500} hideDelay={200}>
	{#snippet children(attrs)}
		<Button {...attrs}>Delayed</Button>
	{/snippet}
</Tooltip>
```

### onVisibleChange

The onVisibleChange prop is a callback function that is called whenever the visibility of the tooltip changes. This allows you to programmatically respond to the tooltip being shown or hidden.

### relationship

The relationship prop allows you to specify the relationship between the tooltip and the target element. This can be used for accessibility purposes, such as indicating that the tooltip is a description of the target element.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TooltipProps -->

| Name                                                | Type                                                     | Default            | Description                                                                                              |
| --------------------------------------------------- | -------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |
| `content`                                           | `string` &#124; `Snippet` &#124; `Component`             | `'I am a tooltip'` | The content to display in the tooltip.                                                                   |
| `class`                                             | `string`                                                 |                    | The class to apply to the tooltip.                                                                       |
| `ref` _bindable_                                    | `HTMLElement` &#124; `null`                              |                    | The DOM reference of the tooltip element.                                                                |
| `target`                                            | `HTMLElement`                                            |                    | The element the tooltip is anchored to. Falls back to the rendered children.                             |
| `open` _bindable_                                   | `boolean`                                                | `false`            | Controls the open state of the tooltip.                                                                  |
| `withArrow`                                         | `boolean`                                                | `false`            | Whether the tooltip has an arrow pointing at its target.                                                 |
| `positionConfig`                                    | `ComputePositionConfig`                                  |                    | The position configuration handed over to floating-ui.                                                   |
| `openDelay`                                         | `number`                                                 | `100`              | The delay in milliseconds before the tooltip is shown.                                                   |
| `hideDelay`                                         | `number`                                                 | `300`              | The delay in milliseconds before the tooltip is hidden.                                                  |
| `onVisibleChange`                                   | `(visible: boolean) => void`                             |                    | Callback function that is called when the visibility of the tooltip changes.                             |
| `relationship`                                      | `'label'` &#124; `'description'` &#124; `'inaccessible'` | `'label'`          | The relationship of the tooltip to its target, which decides how it is announced.                        |
| `placement`                                         | `Placement`                                              |                    | Where the tooltip is placed relative to its target.                                                      |
| `id`                                                | `string`                                                 |                    | The id of the tooltip element, referenced by the target. Falls back to a generated id.                   |
| `preventClose` _bindable_                           | `boolean`                                                | `false`            | Keeps the tooltip open until it is closed by hand.                                                       |
| `animationFrame`                                    | `boolean`                                                | `false`            | Repositions the tooltip on every animation frame, for a target that keeps moving.                        |
| `children`                                          | `Snippet`                                                |                    | The target of the tooltip. It receives the ARIA attributes and the attachment to spread on your element. |
| `HTMLAttributes<HTMLDivElement>` without `children` |                                                          |                    |                                                                                                          |

<!-- /props:TooltipProps -->

---

# TopNav

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

TopNav gives a single selection from a row of items, with a bar that marks the selected one. Each item carries a short label and often an icon.

The bar belongs to the strip rather than to any one item: when the selection moves it travels to the item that took it, staying on screen the whole way instead of disappearing from one and reappearing under the next.

The strip owns the selection and nothing else. What an item opens is rendered by you, wherever it belongs on the page, so an item can open a panel underneath it, swap a region somewhere else, or drive a route.

To create a top nav, you will need to use the following components:

- `TopNav`: The root component that creates the context every item reads: which item is selected, the appearance, the size and the axis. It renders the `tablist` and the bar that travels across it.
- `TopNavItem`: A single item of the strip. It reports its own selection and can carry an icon.

## Usage

A top nav expects a `value` on every item and a `selectedValue` to match it against. Bind `selectedValue` to follow the selection, and render whatever the selected item opens yourself.

```svelte
<script>
	import { TopNav, TopNavItem } from 'fluentui-svelte';

	let selectedValue = $state('arrivals');
</script>

<TopNav bind:selectedValue aria-label="Flights">
	<TopNavItem id="tab-arrivals" value="arrivals">Arrivals</TopNavItem>
	<TopNavItem id="tab-departures" value="departures">Departures</TopNavItem>
</TopNav>

{#if selectedValue === 'arrivals'}
	<div role="tabpanel" aria-labelledby="tab-arrivals">Everything landing in the next hour.</div>
{:else}
	<div role="tabpanel" aria-labelledby="tab-departures">Everything leaving in the next hour.</div>
{/if}
```

## Examples

### Appearance

`appearance` decides how the strip is painted. `transparent` has no background of its own and `subtle` fills an item while it is engaged; both mark the selection with the travelling bar. The two circular appearances trade that bar for a pill: `subtle-circular` outlines the selected item and `filled-circular` fills it.

```svelte
<TopNav appearance="transparent">...</TopNav>
<TopNav appearance="subtle">...</TopNav>
<TopNav appearance="subtle-circular">...</TopNav>
<TopNav appearance="filled-circular">...</TopNav>
```

### Size

`size` sets the padding, the type and the thickness of the bar for every item at once.

```svelte
<TopNav size="small">...</TopNav>
<TopNav size="medium">...</TopNav>
<TopNav size="large">...</TopNav>
```

### Vertical

`vertical` stacks the items in a column and moves the bar to their leading edge, where it travels up and down instead of across. The arrow keys follow the same turn.

```svelte
<TopNav bind:selectedValue vertical>
	<TopNavItem value="tab1">First Tab</TopNavItem>
	<TopNavItem value="tab2">Second Tab</TopNavItem>
</TopNav>
```

### Icon

`icon` takes a snippet or a component and renders it before the label.

```svelte
<script>
	import { TopNav, TopNavItem } from 'fluentui-svelte';
	import AirplaneRegular from 'fluentui-icons-svelte/AirplaneRegular.svelte';
	import AirplaneTakeOffRegular from 'fluentui-icons-svelte/AirplaneTakeOffRegular.svelte';
</script>

<TopNav bind:selectedValue>
	<TopNavItem value="arrivals" icon={AirplaneRegular}>Arrivals</TopNavItem>
	<TopNavItem value="departures" icon={AirplaneTakeOffRegular}>Departures</TopNavItem>
</TopNav>
```

### As an Anchor

`as="a"` renders the item as an anchor and takes the attributes of one, `href` among them, so the item has a real URL to open in a new tab or copy. It still reports as a `tab`, which is what a strip of tabs over one page should be; if the items are navigation between pages rather than tabs, a `nav` of plain links is the better shape.

```svelte
<TopNav bind:selectedValue>
	<TopNavItem as="a" href="#arrivals" value="arrivals">Arrivals</TopNavItem>
	<TopNavItem as="a" href="#departures" value="departures">Departures</TopNavItem>
</TopNav>
```

### Disabled

`disabled` on the strip disables every item at once, and a single item can be disabled on its own. The arrow keys pass over a disabled item rather than landing on it.

```svelte
<TopNav disabled>...</TopNav>

<TopNav>
	<TopNavItem value="tab1">First Tab</TopNavItem>
	<TopNavItem value="tab2" disabled>Second Tab</TopNavItem>
</TopNav>
```

### Select on Focus

`selectTabOnFocus` selects an item as soon as the focus reaches it, so the arrow keys move the selection rather than only the focus. Use it when what an item opens is already on the page; leave it off when opening one costs a request.

```svelte
<TopNav bind:selectedValue selectTabOnFocus>
	<TopNavItem value="tab1">First Tab</TopNavItem>
	<TopNavItem value="tab2">Second Tab</TopNavItem>
</TopNav>
```

### Reserved Space

A selected item sets its label in semibold, which is wider than the same label at rest. `reserveSelectedTabSpace` is on by default and holds that width from the start, so selecting an item never shoves the ones beside it along. Turning it off lets the items size to what they are showing, and the row shifts as the selection moves.

```svelte
<TopNav bind:selectedValue reserveSelectedTabSpace={false}>
	<TopNavItem value="tab1">First Tab</TopNavItem>
	<TopNavItem value="tab2">Second Tab</TopNavItem>
</TopNav>
```

## Component Props (TopNav)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TopNavProps -->

| Name                       | Type                                                                           | Default         | Description                                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_           | `HTMLDivElement` &#124; `null`                                                 |                 | The DOM reference of the strip.                                                                                                                                                     |
| `selectedValue` _bindable_ | `string`                                                                       |                 | The value of the selected item.                                                                                                                                                     |
| `onTabSelect`              | `(event: Event, value: string) => void`                                        |                 | Fired when an item is selected.                                                                                                                                                     |
| `appearance`               | [`TopNavAppearance`](https://fluentui-svelte.dev/docs/types/#topnavappearance) | `'transparent'` | How the strip is painted: `transparent` has no background of its own, `subtle` fills an item while it is engaged, and the two circular appearances trade the moving bar for a pill. |
| `size`                     | `'small'` &#124; `'medium'` &#124; `'large'`                                   | `'medium'`      | The size of every item of the strip.                                                                                                                                                |
| `vertical`                 | `boolean`                                                                      | `false`         | Arranges the items in a column, with the bar down their leading edge.                                                                                                               |
| `disabled`                 | `boolean`                                                                      | `false`         | Disables the user interaction on every item.                                                                                                                                        |
| `selectTabOnFocus`         | `boolean`                                                                      | `false`         | Selects an item as soon as the focus reaches it, rather than waiting to be asked.                                                                                                   |
| `reserveSelectedTabSpace`  | `boolean`                                                                      | `true`          | A selected item sets its label in semibold, which is wider than the same label at rest. This holds that width from the start, so selecting an item never shifts the ones beside it. |
| `disableTabspot`           | `boolean`                                                                      | `false`         | Opts the strip out of the tabspot focus management, to wire your own.                                                                                                               |
| Element Attributes (`div`) |                                                                                |                 |                                                                                                                                                                                     |

<!-- /props:TopNavProps -->

## Component Props (TopNavItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TopNavItemProps -->

| Name             | Type                          | Default    | Description                                                                                                                        |
| ---------------- | ----------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `ref` _bindable_ | `TopNavItemElementDOMType[T]` |            | The DOM reference of the item.                                                                                                     |
| `as`             | `'button'` &#124; `'a'`       | `'button'` | The DOM element to render. An anchor takes the attributes of one, `href` among them, and is what an item that navigates should be. |
| `value`          | `string`                      |            | The value that identifies the item. Defaults to a generated id.                                                                    |
| `icon`           | `Snippet` &#124; `Component`  |            | The icon to display before the label.                                                                                              |
| `disabled`       | `boolean`                     |            | Disables the user interaction.                                                                                                     |
| HTML Attributes  |                               |            |                                                                                                                                    |

<!-- /props:TopNavItemProps -->

## Keyboard Navigation

The strip is a single tab stop. The arrows walk the items along the axis they are laid out on, `Home` and `End` jump to the ends, and `Enter` and `Space` select the focused item — or `selectTabOnFocus` selects it on arrival. `disableTabspot` hands the focus management back to you.

## Accessibility

The strip renders a `tablist` and every item a `tab`, so give it a name through `aria-label`. Since you render what an item opens, give that element a `tabpanel` role and point its `aria-labelledby` at the `id` of its item. An item with an icon and no label needs an `aria-label` of its own.

---

# Tree View

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Tree View displays hierarchical data in a nested list where each item can be expanded, checked or selected. Items are composed with the TreeViewItem and TreeViewItemContent components — the tree does not accept a data prop.

## Usage

```svelte
<script>
	import { TreeView, TreeViewItem, TreeViewItemContent } from 'fluentui-svelte';
</script>

<TreeView selectionMode="multiple">
	<TreeViewItem id="fruits" type="branch">
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="apple">
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
			<TreeViewItem id="banana" disabled>
				<TreeViewItemContent>Banana</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
	<TreeViewItem id="vegetables">
		<TreeViewItemContent>Vegetables</TreeViewItemContent>
	</TreeViewItem>
</TreeView>
```

Nesting a TreeView inside a TreeViewItem of type='branch' creates a subtree. Use openItems / checkedItems on the root TreeView (bindable) to control open and checked state programmatically.

## Examples

### Checkable Items

Set `selectionMode` to `"multiple" | "single"` to render checkboxes on selectable items.

```svelte
<TreeView selectionMode="multiple">
	<TreeViewItem id="fruits" type="branch">
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="apple">
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
</TreeView>
```

### Single selection

Set `selectionMode` to `single` so checking an item unchecks the previous one, and branches no longer cascade to their children.

```svelte
<script>
	let checked = $state([]);
</script>

<TreeView selectionMode="single" bind:checkedItems={checked}>
	<TreeViewItem id="fruits" type="branch" open>
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="apple">
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
			<TreeViewItem id="banana">
				<TreeViewItemContent>Banana</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
	<TreeViewItem id="vegetables">
		<TreeViewItemContent>Vegetables</TreeViewItemContent>
	</TreeViewItem>
</TreeView>

<p>Checked: {checked.join(', ')}</p>
```

### Icons

Use `iconBefore` and `iconAfter` to render icons around the label. Every item reserves the space of the expand chevron, so checkboxes and icons stay aligned between branches and leaves.

```svelte
<script>
	import { TreeView, TreeViewItem, TreeViewItemContent } from 'fluentui-svelte';
	import FolderRegular from 'fluentui-icons-svelte/FolderRegular.svelte';
	import DocumentRegular from 'fluentui-icons-svelte/DocumentRegular.svelte';
	import ImageRegular from 'fluentui-icons-svelte/ImageRegular.svelte';
	import StarRegular from 'fluentui-icons-svelte/StarRegular.svelte';
	import LockClosedRegular from 'fluentui-icons-svelte/LockClosedRegular.svelte';
</script>

{#snippet folder()}<FolderRegular width="1.25rem" />{/snippet}
{#snippet document()}<DocumentRegular width="1.25rem" />{/snippet}
{#snippet image()}<ImageRegular width="1.25rem" />{/snippet}
{#snippet star()}<StarRegular width="1rem" />{/snippet}
{#snippet lock()}<LockClosedRegular width="1rem" />{/snippet}

<TreeView selectionMode="multiple">
	<TreeViewItem id="documents" type="branch" open>
		<TreeViewItemContent iconBefore={folder}>Documents</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="report">
				<TreeViewItemContent iconBefore={document} iconAfter={star}>Report</TreeViewItemContent>
			</TreeViewItem>
			<TreeViewItem id="photo">
				<TreeViewItemContent iconBefore={image}>Photo</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
	<TreeViewItem id="notes">
		<TreeViewItemContent iconBefore={document} iconAfter={lock}>Notes</TreeViewItemContent>
	</TreeViewItem>
</TreeView>
```

### Aside and actions

`aside` is pinned to the end of the row. `actions` comes after it and is revealed when the row is hovered or focused.

```svelte
<script>
	import { TreeView, TreeViewItem, TreeViewItemContent, Button } from 'fluentui-svelte';
	import DocumentRegular from 'fluentui-icons-svelte/DocumentRegular.svelte';
	import MoreHorizontalRegular from 'fluentui-icons-svelte/MoreHorizontalRegular.svelte';
</script>

{#snippet document()}<DocumentRegular width="1.25rem" />{/snippet}
{#snippet fileSize()}<span>2 KB</span>{/snippet}
{#snippet more()}
	<Button appearance="subtle" onclick={(e) => e.stopPropagation()} aria-label="More actions"
		><MoreHorizontalRegular width="1rem" /></Button
	>
{/snippet}

<TreeView>
	<TreeViewItem id="report">
		<TreeViewItemContent iconBefore={document} aside={fileSize} actions={more}>Report</TreeViewItemContent>
	</TreeViewItem>
	<TreeViewItem id="annual-summary">
		<TreeViewItemContent iconBefore={document} aside={fileSize} actions={more}>Annual summary</TreeViewItemContent>
	</TreeViewItem>
</TreeView>
```

### Sizes

Set `size` to `small`, `medium` or `large` on the root `TreeView`.

```svelte
<TreeView size="small">...</TreeView>
<TreeView size="medium">...</TreeView>
<TreeView size="large">...</TreeView>
```

### Disabled items

A disabled item can't be opened or checked, and it is skipped when its parent checks its children, which leaves the parent in its mixed state.

```svelte
<TreeView selectionMode="multiple">
	<TreeViewItem id="fruits" type="branch" open>
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="apple">
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
			<TreeViewItem id="banana" disabled>
				<TreeViewItemContent>Banana</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
</TreeView>
```

### Controlling Open and Checked State

Use the bindable `openItems` and `checkedItems` props on the root `TreeView` to control state programmatically.

```svelte
<script>
	let openItems = $state(['fruits']);
	let checkedItems = $state([]);
</script>

<TreeView bind:openItems bind:checkedItems selectionMode="multiple">
	<TreeViewItem id="fruits" type="branch">
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem id="apple">
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
</TreeView>

<p>Open: {openItems.join(', ')}</p>
<p>Checked: {checkedItems.join(', ')}</p>
```

### Events

`onCheckedChange` and `onOpenChange` on the TreeView receive the resulting ids. The same props on a TreeViewItem receive the item and its new state, including the children a branch cascades to.

```svelte
<script>
	let treeEvent = $state('');
	let itemEvent = $state('');
</script>

<TreeView
	selectionMode="multiple"
	onCheckedChange={(e, checkedItems) => (treeEvent = 'Checked: ' + checkedItems.join(', '))}
	onOpenChange={(e, openItems) => (treeEvent = 'Open: ' + openItems.join(', '))}
>
	<TreeViewItem
		id="fruits"
		type="branch"
		onOpenChange={(e, { id, open }) => (itemEvent = id + (open ? ' opened' : ' closed'))}
	>
		<TreeViewItemContent>Fruits</TreeViewItemContent>
		<TreeView>
			<TreeViewItem
				id="apple"
				onCheckedChange={(e, { id, checked }) => (itemEvent = id + (checked ? ' checked' : ' unchecked'))}
			>
				<TreeViewItemContent>Apple</TreeViewItemContent>
			</TreeViewItem>
		</TreeView>
	</TreeViewItem>
</TreeView>

<p>Tree: {treeEvent}</p>
<p>Item: {itemEvent}</p>
```

## Component Props (TreeView)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TreeViewProps -->

| Name                                                | Type                                         | Default      | Description                                                                          |
| --------------------------------------------------- | -------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
| `ref` _bindable_                                    | `HTMLUListElement` &#124; `null`             |              | The DOM reference of the tree element.                                               |
| `size`                                              | `'small'` &#124; `'medium'` &#124; `'large'` | `'medium'`   | The size of every item in the tree.                                                  |
| `navigationMode`                                    | `'tree'` &#124; `'treegrid'`                 | `'tree'`     | Whether the tree takes a single tab stop, or every row is reachable on its own.      |
| `onOpenChange`                                      | `(e: Event, openItems: string[]) => void`    |              | Called whenever a branch opens or closes.                                            |
| `selectionMode`                                     | `'single'` &#124; `'multiple'`               | `'multiple'` | How many items can be checked at a time.                                             |
| `onCheckedChange`                                   | `(e: Event, checkedItems: string[]) => void` |              | Called whenever an item is checked or unchecked.                                     |
| `virtualizer`                                       | `TreeViewVirtualizer`                        |              | Bridge to a windowing library. Only the rendered slice of items lives in the DOM.    |
| `openItems` _bindable_                              | `string[]` &#124; `SvelteSet<string>`        |              | The ids of the open branches. A `SvelteSet` is required when a `virtualizer` is set. |
| `checkedItems` _bindable_                           | `string[]` &#124; `SvelteSet<string>`        |              | The ids of the checked items. A `SvelteSet` is required when a `virtualizer` is set. |
| `children`                                          | `Snippet`                                    |              | The items of the tree.                                                               |
| `TreeViewVirtualProps` &#124; `TreeViewStaticProps` |                                              |              |                                                                                      |
| Element Attributes (`ul`)                           |                                              |              |                                                                                      |

<!-- /props:TreeViewProps -->

## Component Props (TreeViewItem)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TreeViewItemProps -->

| Name                      | Type                                                         | Default  | Description                                                                            |
| ------------------------- | ------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------- |
| `id`                      | `string`                                                     |          | The id of the item, used by the tree to track its state. Falls back to a generated id. |
| `type`                    | `'item'` &#124; `'branch'`                                   | `'item'` | Whether the item holds children, and can therefore be opened.                          |
| `ref`                     | `HTMLLIElement` &#124; `null`                                |          | The DOM reference of the item element.                                                 |
| `value`                   | `string` &#124; `number`                                     | `id`     | The value reported by the tree events. Falls back to the id of the item.               |
| `text`                    | `string`                                                     |          | The label of the item, used by the type-ahead navigation.                              |
| `open`                    | `boolean`                                                    |          | Whether the branch is open.                                                            |
| `checked`                 | `boolean`                                                    |          | Whether the item is checked.                                                           |
| `indeterminate`           | `boolean`                                                    |          | Renders the checkbox in its mixed state, when only some children are checked.          |
| `disabled`                | `boolean`                                                    |          | Disables the user interaction.                                                         |
| `index`                   | `number`                                                     |          | The real index of the item in the data set. Required when the tree is virtualized.     |
| `onOpenChange`            | `(e: Event, data: { id: string; open: boolean }) => void`    |          | Called when this branch opens or closes.                                               |
| `onCheckedChange`         | `(e: Event, data: { id: string; checked: boolean }) => void` |          | Called when this item is checked or unchecked.                                         |
| Element Attributes (`li`) |                                                              |          |                                                                                        |

<!-- /props:TreeViewItemProps -->

## Component Props (TreeViewItemContent)

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:TreeViewItemLayoutProps -->

| Name                       | Type                           | Default | Description                                                           |
| -------------------------- | ------------------------------ | ------- | --------------------------------------------------------------------- |
| `ref`                      | `HTMLDivElement` &#124; `null` |         | The DOM reference of the layout element.                              |
| `expandIcon`               | `Snippet` &#124; `Component`   |         | Custom icon for the control that opens a branch.                      |
| `iconBefore`               | `Snippet` &#124; `Component`   |         | Content rendered before the label.                                    |
| `iconAfter`                | `Snippet` &#124; `Component`   |         | Content rendered after the label.                                     |
| `aside`                    | `Snippet` &#124; `Component`   |         | Content pinned to the end of the row.                                 |
| `actions`                  | `Snippet` &#124; `Component`   |         | Content pinned to the end of the row, revealed on hover and on focus. |
| Element Attributes (`div`) |                                |         |                                                                       |

<!-- /props:TreeViewItemLayoutProps -->