---
url: 'https://flux-ui.dev/guide/introduction/what-is-flux.md'
---
# What is Flux

Flux is a Vue component library designed to simplify the creation of beautiful and functional interfaces for Vue applications. With a collection of pre-built components, Flux enables developers to seamlessly integrate these elements into their projects, significantly reducing the time and effort required to develop a polished user interface.

One of the primary benefits of using Flux is its ability to maintain design consistency across the entire application. By leveraging these pre-designed components, developers can ensure a cohesive and intuitive user experience throughout the application's pages. Additionally, Flux is highly customizable, allowing developers to tailor components to meet specific requirements.

For developers seeking to enhance the quality and efficiency of their Vue application development, Flux is an exceptional choice. Whether you are an experienced developer or just beginning your journey, Flux provides the tools to create visually appealing and functional interfaces that end users will admire.

In short, Flux is a practical Vue component library that aids in building top-tier interfaces for Vue applications. Its pre-built, adaptable components ensure a consistent and intuitive user interface, while also streamlining the development process to help teams deliver high-quality applications faster.

---

---
url: 'https://flux-ui.dev/guide/introduction/installation/manual.md'
---
# Installation

To start using Flux in your Vue application, you'll need to add it to your project. This section provides step-by-step instructions on how to install Flux, ensuring you can quickly integrate its components into your development workflow.

## Plain installation

::: tip
This is the most recommended way to use Flux. Use this form of installation if you don't need to customize the style of Flux or if you simply need to use the components without the source code.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/components
```

```shell [PNPM]
pnpm install @flux-ui/components
```

```shell [Yarn]
yarn add @flux-ui/components
```

```shell [NPM]
npm install @flux-ui/components
```

:::

::: tip Date and calendar components
Components such as the [Date picker](../../../components/date-picker) and [Calendar](../../../components/calendar) rely on [luxon](https://moment.github.io/luxon/). Most package managers install it automatically as a peer dependency; add it explicitly with `bun add luxon` if yours does not.
:::

### Step 2

Once the installation is completed, you need to add the following to your `main.ts` file.

```ts [main.ts]
import '@flux-ui/components/style.css'
```

### Step 3

For setting up icons, please refer to [Font Awesome](../font-awesome).

### Step 4

Wrap your application in `<FluxRoot>` once, at the top level, and import the components you want to use:

```vue [App.vue]
<template>
    <FluxRoot> <!-- [!code focus:7] -->
        <FluxPane>
            <FluxSecondaryButton
                href="https://flux-ui.dev"
                label="Button"/>
        </FluxPane>
    </FluxRoot>
</template>

<script
    lang="ts"
    setup>
    import { FluxPane, FluxRoot, FluxSecondaryButton } from '@flux-ui/components'; // [!code focus]
</script>
```

::: tip FluxRoot
`<FluxRoot>` is the mounting point for [tooltips](../../../components/tooltip), [overlays](../../../components/overlay), [slide-overs](../../../components/slide-over), [snackbars](../../../components/attention/snackbar) and the programmatic [`showAlert`](../../../components/attention/alert), [`showConfirm`](../../../components/attention/confirm) and [`showPrompt`](../../../components/attention/prompt). Add it once around your app; without it these features silently render nothing.
:::

## Vite-preset installation

::: tip
Only use this form of installation if you need more control of Flux and need the Flux source code injected into your own project.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [PNPM]
pnpm install @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [Yarn]
yarn add @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [NPM]
npm install @flux-ui/components sass-embedded @basmilius/vite-preset
```

:::

### Step 2

Once the installation is completed, you need to configure your Vite config file to use Flux.

::: tip
For more information on the vite-preset package, please refer to [@basmilius/vite-preset](https://github.com/basmilius/packages/tree/main/packages/vite-preset)
:::

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { flux, preset } from '@basmilius/vite-preset'

export default defineConfig({
    plugins: [
        vue(),
        preset(),
        flux()
    ]
});
```

### Step 3

For setting up icons, please refer to [Font Awesome](../font-awesome).

### Step 4

Wrap your application in `<FluxRoot>` once, at the top level, and import the components you want to use:

```vue [App.vue]
<template>
    <FluxRoot> <!-- [!code focus:7] -->
        <FluxPane>
            <FluxSecondaryButton
                href="https://flux-ui.dev"
                label="Button"/>
        </FluxPane>
    </FluxRoot>
</template>

<script
    lang="ts"
    setup>
    import { FluxPane, FluxRoot, FluxSecondaryButton } from '@flux-ui/components'; // [!code focus]
</script>
```

---

---
url: 'https://flux-ui.dev/guide/introduction/installation/vue-router.md'
---
# Vue Router

Flux is built to work hand-in-hand with [Vue Router](https://router.vuejs.org). All components that accept a `to` prop (such as `FluxLink`, `FluxPressable`, `FluxPrimaryLinkButton`, `FluxSecondaryLinkButton`, `FluxMenuItem` and `FluxMenuCollapsible`) forward it directly to a `<RouterLink>`. The same applies to the menu and navigation components inside `@flux-ui/application`.

This guide walks you through installing Vue Router and integrating it with Flux.

## Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add vue-router
```

```shell [PNPM]
pnpm install vue-router
```

```shell [Yarn]
yarn add vue-router
```

```shell [NPM]
npm install vue-router
```

:::

## Step 2

Create a `router.ts` file in your `src` directory and configure your routes:

```ts [router.ts]
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
    {
        path: '/',
        name: 'home',
        component: () => import('./views/Home.vue')
    },
    {
        path: '/about',
        name: 'about',
        component: () => import('./views/About.vue')
    }
];

export const router = createRouter({
    history: createWebHistory(),
    routes
});
```

## Step 3

Register the router in your `main.ts` file:

```ts [main.ts]
import { createApp } from 'vue';
import { router } from './router';
import App from './App.vue';

import '@flux-ui/components/style.css';

createApp(App)
    .use(router) // [!code focus]
    .mount('#app');
```

## Step 4

Add a `<RouterView/>` to your root component, wrapped in a single `<FluxRoot>`. When using `@flux-ui/application`, place the `<RouterView/>` inside the content slot of the layout:

```vue [App.vue]
<template>
    <FluxRoot> <!-- [!code focus] -->
        <FluxApplication>
            <template #menu>
                <FluxApplicationMenu>
                    <!-- Menu items. -->
                </FluxApplicationMenu>
            </template>

            <FluxApplicationContent>
                <RouterView/>
            </FluxApplicationContent>
        </FluxApplication>
    </FluxRoot> <!-- [!code focus] -->
</template>

<script
    lang="ts"
    setup>
    import { FluxApplication, FluxApplicationContent, FluxApplicationMenu } from '@flux-ui/application';
    import { FluxRoot } from '@flux-ui/components'; // [!code focus]
</script>
```

::: tip FluxRoot
`<FluxApplication>` does not include a [`<FluxRoot>`](../../../components/root), so add one at the top yourself. It is the mounting point for tooltips, overlays, slide-overs, snackbars and the programmatic alerts, confirms and prompts; without it those features silently render nothing.
:::

## Linking to routes

Every Flux component that accepts a `to` prop hands it off to Vue Router's `<RouterLink>`, so you can pass either a path string or a route location object.

```vue [Navigation.vue]
<template>
    <FluxFlex
        direction="vertical"
        :gap="18">
        <FluxLink
            type="route"
            label="Home"
            :to="{name: 'home'}"/>

        <FluxSecondaryButton
            label="About"
            :to="{name: 'about'}"/>

        <FluxMenuItem
            icon="gear"
            label="Settings"
            :to="{name: 'settings'}"/>
    </FluxFlex>
</template>

<script
    lang="ts"
    setup>
    import { FluxFlex, FluxLink, FluxMenuItem, FluxSecondaryButton } from '@flux-ui/components';
</script>
```

## Animating route transitions

Flux ships with a [Route transition](../../../components/transitions/route) that animates entering and leaving views. Wrap your `<RouterView/>` in a `<FluxRouteTransition>` to enable it:

```vue [App.vue]
<template>
    <FluxApplicationContent>
        <RouterView v-slot="{Component}"> <!-- [!code focus:5] -->
            <FluxRouteTransition>
                <component :is="Component"/>
            </FluxRouteTransition>
        </RouterView>
    </FluxApplicationContent>
</template>

<script
    lang="ts"
    setup>
    import { FluxApplicationContent } from '@flux-ui/application';
    import { FluxRouteTransition } from '@flux-ui/components';
</script>
```

## Named views

`@flux-ui/application` uses [named views](https://router.vuejs.org/guide/essentials/named-views.html) to render a context-specific menu next to each route. Add a `menu` named component to any route record that should expose its own menu:

```ts [router.ts]
const routes: RouteRecordRaw[] = [
    {
        path: '/projects/:id',
        components: {
            default: () => import('./views/ProjectOverview.vue'),
            menu: () => import('./views/ProjectMenu.vue') // [!code focus]
        }
    }
];
```

The matched menu components are then rendered through `<FluxApplicationMenuContextStack>`, so each level of a nested route tree can contribute its own menu.

---

---
url: 'https://flux-ui.dev/guide/introduction/installation/nuxt.md'
---
# Nuxt

Flux works out of the box with [Nuxt](https://nuxt.com). The components are SSR-safe and gate any browser-only logic behind a runtime check, so you can render Flux on the server and hydrate it on the client without extra configuration.

This guide walks you through installing Flux in a Nuxt project.

## Plain installation

::: tip
This is the most recommended way to use Flux. Use this form of installation if you don't need to customize the style of Flux or if you simply need to use the components without the source code.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/components
```

```shell [PNPM]
pnpm install @flux-ui/components
```

```shell [Yarn]
yarn add @flux-ui/components
```

```shell [NPM]
npm install @flux-ui/components
```

:::

### Step 2

Add the Flux stylesheet to your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
    css: [
        '@flux-ui/components/style.css' // [!code focus]
    ]
});
```

### Step 3

Register Font Awesome icons through a client-side Nuxt plugin. Create `plugins/flux.client.ts`:

```ts [plugins/flux.client.ts]
import { fluxRegisterIcons } from '@flux-ui/components';
import { faRocket, faUser } from '@fortawesome/pro-regular-svg-icons';

export default defineNuxtPlugin(() => {
    fluxRegisterIcons([
        faRocket,
        faUser
    ]);
});
```

For more information about icon usage, please refer to [Font Awesome](../font-awesome).

### Step 4

Use the components in your pages and layouts as you would in any Vue application:

```vue [app.vue]
<template>
    <FluxPane> <!-- [!code focus:5] -->
        <FluxSecondaryButton
            href="https://flux-ui.dev"
            label="Button"/>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxPane, FluxSecondaryButton } from '@flux-ui/components'; // [!code focus]
</script>
```

## Vite-preset installation

::: tip
Only use this form of installation if you need more control of Flux and need the Flux source code injected into your own project.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [PNPM]
pnpm install @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [Yarn]
yarn add @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [NPM]
npm install @flux-ui/components sass-embedded @basmilius/vite-preset
```

:::

### Step 2

Configure the Vite plugins through Nuxt's `vite` option:

::: tip
For more information on the vite-preset package, please refer to [@basmilius/vite-preset](https://github.com/basmilius/packages/tree/main/packages/vite-preset).
:::

```ts [nuxt.config.ts]
import { flux, preset } from '@basmilius/vite-preset';

export default defineNuxtConfig({
    css: [
        '@flux-ui/components/style.css'
    ],
    vite: {
        plugins: [
            preset(),
            flux()
        ]
    }
});
```

### Step 3

For setting up icons, follow step 3 of the plain installation.

### Step 4

Import the components you want to use as shown in step 4 of the plain installation.

## Nuxt-specific notes

### Auto-imports

Nuxt does not auto-import components from external packages by default. Either import them explicitly in each `<script setup>` block, or register them globally through a plugin:

```ts [plugins/flux.ts]
import * as FluxComponents from '@flux-ui/components';

export default defineNuxtPlugin((nuxtApp) => {
    for (const [name, component] of Object.entries(FluxComponents)) {
        if (name.startsWith('Flux')) {
            nuxtApp.vueApp.component(name, component);
        }
    }
});
```

### `<FluxRoot>` placement

Place `<FluxRoot>` in your top-level `app.vue` so [tooltips](../../../components/tooltip), [overlays](../../../components/overlay), [slide-overs](../../../components/slide-over), [snackbars](../../../components/attention/snackbar) and the programmatic [`showAlert`](../../../components/attention/alert), [`showConfirm`](../../../components/attention/confirm) and [`showPrompt`](../../../components/attention/prompt) have a mounting point on every page. Without it these features silently render nothing:

```vue [app.vue]
<template>
    <FluxRoot>
        <NuxtPage/>
    </FluxRoot>
</template>

<script
    lang="ts"
    setup>
    import { FluxRoot } from '@flux-ui/components';
</script>
```

---

---
url: 'https://flux-ui.dev/guide/introduction/translations.md'
---

# Translations

Flux uses a set of built-in strings throughout its components, all of which can be translated. Flux integrates with [vue-i18n](https://vue-i18n.intlify.dev/){target="\_blank"} and uses its translate function, so you can localize these strings alongside the rest of your application.

## Strings

## Pre-translated strings

Here are the official translations for the strings used by Flux. If you have additional translations, feel free to contribute by creating a pull request on GitHub. :)

### English

::: code-group

```yaml [en.yaml]
flux:
  back: "Back"
  cancel: "Cancel"
  close: "Close"
  collapseGroup: "Collapse group"
  collapseRow: "Collapse row"
  expandGroup: "Expand group"
  expandRow: "Expand row"
  comingSoon: "Coming soon"
  continue: "Continue"
  createOption: 'Create "{value}"'
  customPeriod: "Custom period"
  delete: "Delete"
  done: "Done"
  filter: "Filter"
  filterRemove: "Remove filter"
  filterReset: "Reset filters"
  justNow: "Just now"
  max: "Max"
  min: "Min"
  nSelected: "{n} selected"
  ok: "Ok"
  optional: "Optional"
  preview: "Preview"
  previewClose: "Close preview"
  displayingOf: "{from}–{to} of {total}"
  showN: "Show {n}"
  skip: "Skip"
  next: "Next"
  noItems: "There are no items (left)."
  pagination: "Pagination"
  paginationNavigateTitle: "Navigate"
  paginationNavigateMessage: "Please provide the desired page number you wish to navigate to."
  paginationNavigatePage: "Page"
  previous: "Previous"
  search: "Search..."
  sort: "Sort"
  sortAscending: "Ascending"
  sortDescending: "Descending"
  sortRemove: "Remove sorting"
  submenu: "Submenu"
  today: "Today"
  selectMonth: "Select month"
  selectYear: "Select year"
  selectDate: "Select date"
  previousMonth: "Previous month"
  nextMonth: "Next month"
  previousYears: "Previous years"
  nextYears: "Next years"
  allDay: "All day"
  andNMore: "{n} more"
  grabbedAnnounce: "Item grabbed. Use arrow keys to move, Enter to drop, Escape to cancel."
  releasedAnnounce: "Item released."
  goToPage: "Go to page {page}"
  pinDigit: "Digit {index} of {total}"
  dropFilesOrClick: "Drop files here or click to upload"
  colorSaturationBrightness: "Color saturation and brightness"
  customColor: "Custom color"
  hue: "Hue"
  opacity: "Opacity"
  lowerBound: "Lower bound"
  upperBound: "Upper bound"
  galleryPlaceholderButton: "Pick image"
  galleryPlaceholderMessage: "Drop an image here or click the button to upload..."
  galleryPlaceholderTitle: "Gallery"
  timezoneEurope: "Europe"
  timezoneAmerica: "America"
  timezoneUs: "United States"
  timezoneAustralia: "Australia"
  timezoneCanada: "Canada"
  timezoneMexico: "Mexico"
  timezoneAfrica: "Africa"
  timezoneAntarctica: "Antarctica"
  timezoneArctic: "Arctic"
  timezoneAsia: "Asia"
  timezoneAtlantic: "Atlantic"
  timezoneBrazil: "Brazil"
  timezoneChile: "Chile"
  timezoneEtc: "ETC"
  timezoneOther: "Other"
  timezoneIndian: "Indian"
  timezonePacific: "Pacific"
```

```json [en.json]
{
  "flux": {
    "back": "Back",
    "cancel": "Cancel",
    "close": "Close",
    "collapseGroup": "Collapse group",
    "collapseRow": "Collapse row",
    "expandGroup": "Expand group",
    "expandRow": "Expand row",
    "comingSoon": "Coming soon",
    "continue": "Continue",
    "createOption": "Create \"{value}\"",
    "customPeriod": "Custom period",
    "delete": "Delete",
    "done": "Done",
    "filter": "Filter",
    "filterRemove": "Remove filter",
    "filterReset": "Reset filters",
    "justNow": "Just now",
    "max": "Max",
    "min": "Min",
    "nSelected": "{n} selected",
    "ok": "Ok",
    "optional": "Optional",
    "preview": "Preview",
    "previewClose": "Close preview",
    "displayingOf": "{from}–{to} of {total}",
    "showN": "Show {n}",
    "skip": "Skip",
    "next": "Next",
    "noItems": "There are no items (left).",
    "pagination": "Pagination",
    "paginationNavigateTitle": "Navigate",
    "paginationNavigateMessage": "Please provide the desired page number you wish to navigate to.",
    "paginationNavigatePage": "Page",
    "previous": "Previous",
    "search": "Search...",
    "sort": "Sort",
    "sortAscending": "Ascending",
    "sortDescending": "Descending",
    "sortRemove": "Remove sorting",
    "submenu": "Submenu",
    "today": "Today",
    "selectMonth": "Select month",
    "selectYear": "Select year",
    "selectDate": "Select date",
    "previousMonth": "Previous month",
    "nextMonth": "Next month",
    "previousYears": "Previous years",
    "nextYears": "Next years",
    "allDay": "All day",
    "andNMore": "{n} more",
    "grabbedAnnounce": "Item grabbed. Use arrow keys to move, Enter to drop, Escape to cancel.",
    "releasedAnnounce": "Item released.",
    "goToPage": "Go to page {page}",
    "pinDigit": "Digit {index} of {total}",
    "dropFilesOrClick": "Drop files here or click to upload",
    "colorSaturationBrightness": "Color saturation and brightness",
    "customColor": "Custom color",
    "hue": "Hue",
    "opacity": "Opacity",
    "lowerBound": "Lower bound",
    "upperBound": "Upper bound",
    "galleryPlaceholderButton": "Pick image",
    "galleryPlaceholderMessage": "Drop an image here or click the button to upload...",
    "galleryPlaceholderTitle": "Gallery",
    "timezoneEurope": "Europe",
    "timezoneAmerica": "America",
    "timezoneUs": "United States",
    "timezoneAustralia": "Australia",
    "timezoneCanada": "Canada",
    "timezoneMexico": "Mexico",
    "timezoneAfrica": "Africa",
    "timezoneAntarctica": "Antarctica",
    "timezoneArctic": "Arctic",
    "timezoneAsia": "Asia",
    "timezoneAtlantic": "Atlantic",
    "timezoneBrazil": "Brazil",
    "timezoneChile": "Chile",
    "timezoneEtc": "ETC",
    "timezoneOther": "Other",
    "timezoneIndian": "Indian",
    "timezonePacific": "Pacific"
  }
}
```

:::

### Dutch - Nederlands

::: code-group

```yaml [nl.yaml]
flux:
  back: "Terug"
  cancel: "Annuleren"
  close: "Sluiten"
  collapseGroup: "Groep inklappen"
  collapseRow: "Rij inklappen"
  expandGroup: "Groep uitklappen"
  expandRow: "Rij uitklappen"
  comingSoon: "Binnenkort"
  continue: "Verder"
  createOption: 'Maak "{value}" aan'
  customPeriod: "Aangepaste periode"
  delete: "Verwijderen"
  done: "Klaar"
  filter: "Filter"
  filterRemove: "Verwijder filter"
  filterReset: "Verwijder alle filters"
  justNow: "Zojuist"
  max: "Maximaal"
  min: "Minimaal"
  nSelected: "{n} geselecteerd"
  ok: "Oké"
  optional: "Optioneel"
  preview: "Voorbeeld"
  previewClose: "Voorbeeld sluiten"
  displayingOf: "{from}–{to} van {total}"
  showN: "Toon {n}"
  skip: "Overslaan"
  next: "Volgende"
  noItems: "Geen resultaten gevonden"
  pagination: "Paginatie"
  paginationNavigateTitle: "Navigeer"
  paginationNavigateMessage: "Naar welke pagina wil je toe navigeren?"
  paginationNavigatePage: "Pagina"
  previous: "Vorige"
  search: "Zoeken..."
  sort: "Sorteer"
  sortAscending: "Oplopend"
  sortDescending: "Aflopend"
  sortRemove: "Verwijder"
  submenu: "Submenu"
  today: "Vandaag"
  selectMonth: "Selecteer maand"
  selectYear: "Selecteer jaar"
  selectDate: "Selecteer datum"
  previousMonth: "Vorige maand"
  nextMonth: "Volgende maand"
  previousYears: "Vorige jaren"
  nextYears: "Volgende jaren"
  allDay: "Hele dag"
  andNMore: "nog {n}"
  grabbedAnnounce: "Item vastgepakt. Gebruik de pijltjestoetsen om te verplaatsen, Enter om los te laten, Escape om te annuleren."
  releasedAnnounce: "Item losgelaten."
  goToPage: "Ga naar pagina {page}"
  pinDigit: "Cijfer {index} van {total}"
  dropFilesOrClick: "Sleep bestanden hierheen of klik om te uploaden"
  colorSaturationBrightness: "Kleurverzadiging en helderheid"
  customColor: "Aangepaste kleur"
  hue: "Tint"
  opacity: "Dekking"
  lowerBound: "Ondergrens"
  upperBound: "Bovengrens"
  galleryPlaceholderButton: "Selecteer afbeeldingen"
  galleryPlaceholderMessage: "Laat hier afbeeldingen vallen om ze te uploaden of klik op de knop om te selecteren."
  galleryPlaceholderTitle: "Afbeeldingen"
  timezoneEurope: "Europa"
  timezoneAmerica: "Amerika"
  timezoneUs: "Verenigde Staten"
  timezoneAustralia: "Australië"
  timezoneCanada: "Canada"
  timezoneMexico: "Mexico"
  timezoneAfrica: "Afrika"
  timezoneAntarctica: "Antarctica"
  timezoneArctic: "Arctisch"
  timezoneAsia: "Azië"
  timezoneAtlantic: "Atlantisch"
  timezoneBrazil: "Brazilië"
  timezoneChile: "Chili"
  timezoneEtc: "ETC"
  timezoneOther: "Overig"
  timezoneIndian: "Indisch"
  timezonePacific: "Pacifisch"
```

```json [nl.json]
{
  "flux": {
    "back": "Terug",
    "cancel": "Annuleren",
    "close": "Sluiten",
    "collapseGroup": "Groep inklappen",
    "collapseRow": "Rij inklappen",
    "expandGroup": "Groep uitklappen",
    "expandRow": "Rij uitklappen",
    "comingSoon": "Binnenkort",
    "continue": "Verder",
    "createOption": "Maak \"{value}\" aan",
    "customPeriod": "Aangepaste periode",
    "delete": "Verwijderen",
    "done": "Klaar",
    "filter": "Filter",
    "filterRemove": "Verwijder filter",
    "filterReset": "Verwijder alle filters",
    "justNow": "Zojuist",
    "max": "Maximaal",
    "min": "Minimaal",
    "nSelected": "{n} geselecteerd",
    "ok": "Oké",
    "optional": "Optioneel",
    "preview": "Voorbeeld",
    "previewClose": "Voorbeeld sluiten",
    "displayingOf": "{from}–{to} van {total}",
    "showN": "Toon {n}",
    "skip": "Overslaan",
    "next": "Volgende",
    "noItems": "Geen resultaten gevonden",
    "pagination": "Paginatie",
    "paginationNavigateTitle": "Navigeer",
    "paginationNavigateMessage": "Naar welke pagina wil je toe navigeren?",
    "paginationNavigatePage": "Pagina",
    "previous": "Vorige",
    "search": "Zoeken...",
    "sort": "Sorteer",
    "sortAscending": "Oplopend",
    "sortDescending": "Aflopend",
    "sortRemove": "Verwijder",
    "submenu": "Submenu",
    "today": "Vandaag",
    "selectMonth": "Selecteer maand",
    "selectYear": "Selecteer jaar",
    "selectDate": "Selecteer datum",
    "previousMonth": "Vorige maand",
    "nextMonth": "Volgende maand",
    "previousYears": "Vorige jaren",
    "nextYears": "Volgende jaren",
    "allDay": "Hele dag",
    "andNMore": "nog {n}",
    "grabbedAnnounce": "Item vastgepakt. Gebruik de pijltjestoetsen om te verplaatsen, Enter om los te laten, Escape om te annuleren.",
    "releasedAnnounce": "Item losgelaten.",
    "goToPage": "Ga naar pagina {page}",
    "pinDigit": "Cijfer {index} van {total}",
    "dropFilesOrClick": "Sleep bestanden hierheen of klik om te uploaden",
    "colorSaturationBrightness": "Kleurverzadiging en helderheid",
    "customColor": "Aangepaste kleur",
    "hue": "Tint",
    "opacity": "Dekking",
    "lowerBound": "Ondergrens",
    "upperBound": "Bovengrens",
    "galleryPlaceholderButton": "Selecteer afbeeldingen",
    "galleryPlaceholderMessage": "Laat hier afbeeldingen vallen om ze te uploaden of klik op de knop om te selecteren.",
    "galleryPlaceholderTitle": "Afbeeldingen",
    "timezoneEurope": "Europa",
    "timezoneAmerica": "Amerika",
    "timezoneUs": "Verenigde Staten",
    "timezoneAustralia": "Australië",
    "timezoneCanada": "Canada",
    "timezoneMexico": "Mexico",
    "timezoneAfrica": "Afrika",
    "timezoneAntarctica": "Antarctica",
    "timezoneArctic": "Arctisch",
    "timezoneAsia": "Azië",
    "timezoneAtlantic": "Atlantisch",
    "timezoneBrazil": "Brazilië",
    "timezoneChile": "Chili",
    "timezoneEtc": "ETC",
    "timezoneOther": "Overig",
    "timezoneIndian": "Indisch",
    "timezonePacific": "Pacifisch"
  }
}
```

:::

### French - Français

::: code-group

```yaml [fr.yaml]
flux:
  back: "Retour"
  cancel: "Annuler"
  close: "Fermer"
  collapseGroup: "Réduire le groupe"
  collapseRow: "Réduire la ligne"
  expandGroup: "Développer le groupe"
  expandRow: "Développer la ligne"
  comingSoon: "Bientôt disponible"
  continue: "Continuer"
  createOption: 'Créer "{value}"'
  customPeriod: "Période personnalisée"
  delete: "Supprimer"
  done: "Terminé"
  filter: "Filtrer"
  filterRemove: "Supprimer le filtre"
  filterReset: "Réinitialiser les filtres"
  justNow: "À l'instant"
  max: "Max"
  min: "Min"
  nSelected: "{n} sélectionné(s)"
  ok: "OK"
  optional: "Optionnel"
  preview: "Aperçu"
  previewClose: "Fermer l'aperçu"
  displayingOf: "{from}–{to} sur {total}"
  showN: "Afficher {n}"
  skip: "Passer"
  next: "Suivant"
  noItems: "Aucun élément disponible."
  pagination: "Pagination"
  paginationNavigateTitle: "Naviguer"
  paginationNavigateMessage: "Veuillez indiquer le numéro de page souhaité."
  paginationNavigatePage: "Page"
  previous: "Précédent"
  search: "Recherche..."
  sort: "Trier"
  sortAscending: "Ascendant"
  sortDescending: "Descendant"
  sortRemove: "Supprimer le tri"
  submenu: "Sous-menu"
  today: "Aujourd'hui"
  selectMonth: "Sélectionner le mois"
  selectYear: "Sélectionner l'année"
  selectDate: "Sélectionner la date"
  previousMonth: "Mois précédent"
  nextMonth: "Mois suivant"
  previousYears: "Années précédentes"
  nextYears: "Années suivantes"
  allDay: "Toute la journée"
  andNMore: "{n} de plus"
  grabbedAnnounce: "Élément saisi. Utilisez les touches fléchées pour déplacer, Entrée pour déposer, Échap pour annuler."
  releasedAnnounce: "Élément relâché."
  goToPage: "Aller à la page {page}"
  pinDigit: "Chiffre {index} sur {total}"
  dropFilesOrClick: "Déposez des fichiers ici ou cliquez pour téléverser"
  colorSaturationBrightness: "Saturation et luminosité de la couleur"
  customColor: "Couleur personnalisée"
  hue: "Teinte"
  opacity: "Opacité"
  lowerBound: "Borne inférieure"
  upperBound: "Borne supérieure"
  galleryPlaceholderButton: "Choisir une image"
  galleryPlaceholderMessage: "Déposez une image ici ou cliquez sur le bouton pour télécharger..."
  galleryPlaceholderTitle: "Galerie"
  timezoneEurope: "Europe"
  timezoneAmerica: "Amérique"
  timezoneUs: "États-Unis"
  timezoneAustralia: "Australie"
  timezoneCanada: "Canada"
  timezoneMexico: "Mexique"
  timezoneAfrica: "Afrique"
  timezoneAntarctica: "Antarctique"
  timezoneArctic: "Arctique"
  timezoneAsia: "Asie"
  timezoneAtlantic: "Atlantique"
  timezoneBrazil: "Brésil"
  timezoneChile: "Chili"
  timezoneEtc: "ETC"
  timezoneOther: "Autre"
  timezoneIndian: "Indien"
  timezonePacific: "Pacifique"
```

```json [fr.json]
{
  "flux": {
    "back": "Retour",
    "cancel": "Annuler",
    "close": "Fermer",
    "collapseGroup": "Réduire le groupe",
    "collapseRow": "Réduire la ligne",
    "expandGroup": "Développer le groupe",
    "expandRow": "Développer la ligne",
    "comingSoon": "Bientôt disponible",
    "continue": "Continuer",
    "createOption": "Créer \"{value}\"",
    "customPeriod": "Période personnalisée",
    "delete": "Supprimer",
    "done": "Terminé",
    "filter": "Filtrer",
    "filterRemove": "Supprimer le filtre",
    "filterReset": "Réinitialiser les filtres",
    "justNow": "À l'instant",
    "max": "Max",
    "min": "Min",
    "nSelected": "{n} sélectionné(s)",
    "ok": "OK",
    "optional": "Optionnel",
    "preview": "Aperçu",
    "previewClose": "Fermer l'aperçu",
    "displayingOf": "{from}–{to} sur {total}",
    "showN": "Afficher {n}",
    "skip": "Passer",
    "next": "Suivant",
    "noItems": "Aucun élément disponible.",
    "pagination": "Pagination",
    "paginationNavigateTitle": "Naviguer",
    "paginationNavigateMessage": "Veuillez indiquer le numéro de page souhaité.",
    "paginationNavigatePage": "Page",
    "previous": "Précédent",
    "search": "Recherche...",
    "sort": "Trier",
    "sortAscending": "Ascendant",
    "sortDescending": "Descendant",
    "sortRemove": "Supprimer le tri",
    "submenu": "Sous-menu",
    "today": "Aujourd'hui",
    "selectMonth": "Sélectionner le mois",
    "selectYear": "Sélectionner l'année",
    "selectDate": "Sélectionner la date",
    "previousMonth": "Mois précédent",
    "nextMonth": "Mois suivant",
    "previousYears": "Années précédentes",
    "nextYears": "Années suivantes",
    "allDay": "Toute la journée",
    "andNMore": "{n} de plus",
    "grabbedAnnounce": "Élément saisi. Utilisez les touches fléchées pour déplacer, Entrée pour déposer, Échap pour annuler.",
    "releasedAnnounce": "Élément relâché.",
    "goToPage": "Aller à la page {page}",
    "pinDigit": "Chiffre {index} sur {total}",
    "dropFilesOrClick": "Déposez des fichiers ici ou cliquez pour téléverser",
    "colorSaturationBrightness": "Saturation et luminosité de la couleur",
    "customColor": "Couleur personnalisée",
    "hue": "Teinte",
    "opacity": "Opacité",
    "lowerBound": "Borne inférieure",
    "upperBound": "Borne supérieure",
    "galleryPlaceholderButton": "Choisir une image",
    "galleryPlaceholderMessage": "Déposez une image ici ou cliquez sur le bouton pour télécharger...",
    "galleryPlaceholderTitle": "Galerie",
    "timezoneEurope": "Europe",
    "timezoneAmerica": "Amérique",
    "timezoneUs": "États-Unis",
    "timezoneAustralia": "Australie",
    "timezoneCanada": "Canada",
    "timezoneMexico": "Mexique",
    "timezoneAfrica": "Afrique",
    "timezoneAntarctica": "Antarctique",
    "timezoneArctic": "Arctique",
    "timezoneAsia": "Asie",
    "timezoneAtlantic": "Atlantique",
    "timezoneBrazil": "Brésil",
    "timezoneChile": "Chili",
    "timezoneEtc": "ETC",
    "timezoneOther": "Autre",
    "timezoneIndian": "Indien",
    "timezonePacific": "Pacifique"
  }
}
```

:::

---

---
url: 'https://flux-ui.dev/guide/introduction/colors.md'
---
# Colors

Flux ships a color palette of six colors: **gray**, **primary**, **danger**, **info**, **success**, and **warning**. Each color is available in 12 shades, from 25 to 950, so you can make fine-grained design choices.

## Gray

## Primary

## Danger

## Info

## Success

## Warning

---

---
url: 'https://flux-ui.dev/guide/introduction/design-tokens.md'
---
# Design tokens

Flux exposes its visual language as CSS custom properties. Use them to theme your application, build new components that fit in seamlessly, or override individual values for a single element. All tokens are defined on `:root` and adjust automatically when [Dark mode](./dark-mode) is active.

For the color palette tokens (`--gray-*`, `--primary-*`, `--danger-*`, `--info-*`, `--success-*`, `--warning-*`) see [Colors](./colors).

## Surface

Semantic tokens for backgrounds, borders and disabled states. These are the tokens you should reach for first when styling new UI. They automatically follow the active theme.

## Foreground

Tokens for text and iconography.

## Overlay

Used by `FluxOverlay`, `FluxSlideOver`, `FluxFlyout` and other dialog-like components. Dark mode uses solid black with alpha to keep dimming effects readable.

## Shadow

A scale of seven shadow levels. Each level uses a slightly different opacity in dark mode so elevations remain visible against the darker surface.

## Radius

## Typography

### Text scale

Every size is paired with a line-height, and the two are always set together. The pairing is what keeps line boxes on the 3px grid: a font-size on its own would derive its line box from a ratio and land on fractional pixels.

Headings sit outside this scale and carry their own pair: `h1` is 27/42, `h2` is 21/33. The remaining levels line up with the scale, so `h3` is `xlarge`, `h4` is `large`, `h5` is `default` and `h6` is `small`.

::: tip Changing the base size
`--font-size-default` also sets the root font-size, so it is the basis for every `rem` in your own code. Override it on `:root` to rescale the interface, and override `--line-height-default` along with it to keep the rhythm on the grid.
:::

## Motion

The motion tokens drive every Flux transition. Use them when you build custom animations so timings stay consistent with the rest of the system.

## Overriding tokens

All tokens are regular CSS custom properties, so you can override them at any level: globally, on a single component, or even inline.

```scss
:root {
    --radius: 8px;            /* Square off the entire UI. */
    --primary-600: #0070f3;   /* Replace the primary accent. */
}

.my-card {
    --surface: var(--primary-50);
    --surface-stroke: var(--primary-200);
}
```

Because semantic tokens reference palette tokens (e.g. `--surface: var(--gray-25)`), changing a single palette token cascades through every component that uses it.

---

---
url: 'https://flux-ui.dev/guide/introduction/typography.md'
---

# Typography

Flux ships a consistent typographic system covering font families, sizes, weights, and spacing. This page documents how typography works in Flux and how to apply it to text throughout your application.

Outside of any container, Flux applies only light element defaults: heading sizes and weights, link styling and a monospace font for code. Rich prose, with vertical rhythm, decorated blockquotes, list markers and styled tables, lives inside the [Prose](/components/prose) component. Every example below is wrapped in `FluxProse`.

::: tip
Flux uses the [Inter Variable](https://rsms.me/inter/) font family by default, you will need to include the font in your application for it to work.
:::

## The text scale

Text comes in six steps, and each step pairs a font-size with a line-height. Always set the two together: a font-size on its own derives its line box from a ratio, which lands on fractional pixels at every size except the default and drifts off the 3px grid.

```css
.my-label {
    font-size: var(--font-size-small);
    line-height: var(--line-height-small);
}
```

Pick a step by role rather than by measuring the design:

* **2xsmall** (12/18) for fine print, such as meta rows and counters.
* **xsmall** (13/18) for compact labels that sit inline in body text, like a badge.
* **small** (14/21) for interface text: tables, menus, tooltips.
* **default** (15/24) for body text. This is inherited, so you rarely set it.
* **large** (16/24) for a prominent single line, such as a pane caption.
* **xlarge** (18/27) for titles that sit below heading level.

Deviate from a pair only when an element has to line up with a line box it does not own. A checkbox label is the canonical case: the box is 21px, so its label takes `default` at a 21px line-height instead of its own 24px, or the two stop aligning.

Anything with a fixed height should set its own step rather than inherit one. A button is 42px tall whatever you put around it, so its label stays 15px even inside a 14px table cell. Text that should adapt to its surroundings, such as a badge sitting inline in a sentence, is the exception that inherits.

See [Design tokens](/guide/introduction/design-tokens#text-scale) for the full table.

## Examples

::: example Headings
example=../../code/guide/introduction/typography/headings.vue
:::

::: example Paragraph
example=../../code/guide/introduction/typography/paragraph.vue
:::

::: example Lists
example=../../code/guide/introduction/typography/lists.vue
:::

::: example Image
example=../../code/guide/introduction/typography/image.vue
:::

::: example Blockquote
example=../../code/guide/introduction/typography/blockquote.vue
:::

## Using Inter Variable font

If you desire to use the **Inter Variable** font, you need to override the `--font-sans` css variable. To achieve this, you'll need to add the following to your application.

```css [app.css]
:root {
    --font-sans: inter-variable, sans-serif;
}
```

---

---
url: 'https://flux-ui.dev/guide/introduction/dark-mode.md'
---
# Dark mode

Flux includes full support for both light and dark mode, with a color system that adapts to each. Toggle dark mode by setting the `dark` attribute on the document element, as shown below.

## Functional API

::: code-group

```ts [theme.ts]
import { useRemembered } from '@flux-ui/internals'

const darkMode = useRemembered("dark-mode", false);

function toggleMode(): void {
    darkMode.value = !darkMode.value;

    if (darkMode.value) {
        document.documentElement.setAttribute("dark", "dark");
    } else {
        document.documentElement.removeAttribute("dark");
    }
}
```

```vue [App.vue]
<template>
    <!-- Your content here -->
</template>

<script 
    lang="ts"
    setup>
    import { onMounted } from 'vue'
    import { useRemembered } from '@flux-ui/internals'
    
    const darkMode = useRemembered("dark-mode", false);
    
    onMounted(() => {
        if (darkMode.value) {
            document.documentElement.setAttribute("dark", "dark");
        }
    });
</script>
```

:::

---

---
url: 'https://flux-ui.dev/guide/introduction/font-awesome.md'
---

# Font Awesome

Flux uses [Font Awesome](https://fontawesome.com) as its icon library, giving you access to a large collection of icons for your UI. Icons must be registered before use.

## Register icons

Icons must be registered before use so they are available throughout your application. Import the icons you need from [Font Awesome](https://fontawesome.com) and register them with the `configureIcons` function.

::: code-group

```ts [icons.ts]
export {
    faCircleCheck,
    faCircleExclamation
} from '@fortawesome/pro-regular-svg-icons';
```

```ts [register.ts]
import { configureIcons } from '@flux-ui/components';
import * as icons from './icons.ts';

configureIcons({icons});
```

```vue [Page.vue]
<template>
    <FluxIcon
        name="circle-check"
        :size="24"/>
</template>

<script
    lang="ts"
    setup>
    import { FluxIcon } from '@flux-ui/components';
</script>
```

:::

> The standalone `fluxRegisterIcons(icons)` function still works but is deprecated in favor of `configureIcons({icons})`.

## Using the icon font

Instead of registering SVG icons, you can render icons with a Font Awesome webfont. Load the font yourself, bind its `font-family` to the style class Flux emits, then switch Flux to font mode with `configureIcons`. Icons keep being used the same way through the `name` prop.

In font mode `<FluxIcon name="user"/>` renders the icon name as the element's text and relies on the font's ligatures to turn it into the glyph:

```html
<i class="fa-regular">user</i>
```

::: code-group

```ts [main.ts]
import { configureIcons } from '@flux-ui/components';

configureIcons({
    renderMode: 'font',
    defaultStyle: 'regular'
});
```

```css [fonts.css]
@font-face {
    font-family: font-awesome;
    src: url(...);
}

/* Bind the style class Flux emits to the loaded font. */
.fa-regular {
    font-family: font-awesome;
    font-weight: 400;
}
```

```vue [Page.vue]
<template>
    <FluxIcon name="circle-check"/>
</template>

<script
    lang="ts"
    setup>
    import { FluxIcon } from '@flux-ui/components';
</script>
```

:::

Because Font Awesome glyphs draw with `currentColor`, the `color` and `size` props behave exactly as they do in SVG mode. The internal Flux icons were designed against the `regular` family, so `defaultStyle: 'regular'` matches the default SVG look most closely.

### Choosing the style

Flux emits one style class per icon (`fa-solid`, `fa-regular`, `fa-light`, `fa-thin`, `fa-duotone`, `fa-brands`) that you bind to a `font-family`. `FluxIconName` only carries the name, so the style is resolved in this order:

1. The `icon-style` prop on the icon.
2. A per-name entry in `styleOverrides`.
3. The global `defaultStyle`.
4. `solid` as a fallback.

```ts
configureIcons({
    renderMode: 'font',
    defaultStyle: 'light',
    styleOverrides: {
        github: 'brands'
    }
});
```

```vue
<FluxIcon name="github" icon-style="brands"/>
```

### Duotone

Font Awesome draws a duotone icon as two stacked layers, so in `duotone` mode Flux renders the primary shape over a dimmed secondary one, both from a single `color`. Bind `.fa-duotone` to the duotone font like any other style; tune the secondary tone with the `--fa-secondary-opacity` custom property (default `.2`, matching the SVG rendering).

### Notes

* Font mode does not register any SVG data, so chart icons in `@flux-ui/statistics` still require SVG registration through `configureIcons({icons})`.
* The font must provide ligatures for the icon names; otherwise the bare name stays visible as text.

## Required icons

Below is a list of all the icons that Flux uses throughout the library.

```ts [icons.ts]
export {
    faAngleDown,
    faAngleLeft,
    faAngleRight,
    faAnglesUpDown,
    faArrowDown19,
    faArrowDownAZ,
    faArrowDownShortWide,
    faArrowUp91,
    faArrowUpAZ,
    faArrowUpArrowDown,
    faArrowUpWideShort,
    faCalendar,
    faCheck,
    faChevronDown,
    faChevronRight,
    faChevronUp,
    faCircleCheck,
    faCircleExclamation,
    faCircleInfo,
    faCircleXmark,
    faCloud,
    faEllipsis,
    faEllipsisH,
    faEye,
    faEyeSlash,
    faFilter,
    faMagnifyingGlass,
    faMinus,
    faPlus,
    faRotateLeft,
    faSlashForward,
    faSlidersSimple,
    faStar,
    faTrash,
    faUser,
    faXmark
} from '@fortawesome/pro-regular-svg-icons';
```

---

---
url: 'https://flux-ui.dev/guide/composables/useBreakpoints.md'
---
# useBreakpoints

This composable tracks the current viewport breakpoint and provides reactive boolean refs for each breakpoint size.

## Usage

```ts
import { useBreakpoints } from '@flux-ui/components';

const { currentBreakpoint, xs, sm, md, lg, xl } = useBreakpoints();

// Use in a computed or watcher
if (md.value) {
    console.log('Viewport is at least medium');
}
```

## Example

Switch a stack from horizontal to vertical depending on the active breakpoint. Resize the preview to see it in action.

::: example Responsive layout || A card layout that switches direction at the `md` breakpoint.
example=../../code/guide/composables/useBreakpoints/responsive-layout.vue
:::

## Breakpoints

### xs (0px)

Targets the smallest viewports. Active when the viewport width is 0px or more.

### sm (640px)

Targets small viewports such as large phones in landscape mode. Active when the viewport width is 640px or more.

### md (768px)

Targets medium viewports such as tablets in portrait mode. Active when the viewport width is 768px or more.

### lg (1024px)

Targets large viewports such as tablets in landscape mode and small desktops. Active when the viewport width is 1024px or more.

### xl (1280px)

Targets extra-large viewports such as full-size desktop screens. Active when the viewport width is 1280px or more.

## Type declarations

```ts
type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

declare function useBreakpoints(): {
    readonly currentBreakpoint: Ref<Breakpoint | null>;
    readonly xs: Ref<boolean>;
    readonly sm: Ref<boolean>;
    readonly md: Ref<boolean>;
    readonly lg: Ref<boolean>;
    readonly xl: Ref<boolean>;
};
```

---

---
url: 'https://flux-ui.dev/guide/composables/useDisabled.md'
---
# useDisabled

This composable merges a component's local disabled state with any inherited disabled state from a parent [Disabled](../../components/disabled) component. Returns `true` if either the component itself or any parent in the tree is disabled.

## Usage

```ts
import { useDisabled } from '@flux-ui/components';
import { toRef } from 'vue';

const { disabled: componentDisabled } = defineProps<{
    disabled?: boolean;
}>();

const disabled = useDisabled(toRef(() => componentDisabled));
```

## Type declarations

```ts
import type { ComputedRef, Ref } from 'vue';

declare function useDisabled(
    componentDisabled: Ref<boolean>
): ComputedRef<boolean>;
```

## Example

Toggle a parent [Disabled](../../components/disabled) component to disable an entire group of inputs and actions at once. Each Flux component reads the inherited disabled state through `useDisabled` internally, so you don't need to forward the prop manually.

::: example Inherited disabled || A toggle that disables a group of inputs and buttons via a wrapping `FluxDisabled`.
example=../../code/guide/composables/useDisabled/inherited.vue
:::

## Used by

* [Button](../../components/button/)
* [Form](../../components/form/)
  * [Input](../../components/form/input/)
  * [Select](../../components/form/select/)

---

---
url: 'https://flux-ui.dev/guide/composables/useDisabledInjection.md'
---
# useDisabledInjection

This composable retrieves the disabled state from a parent [Disabled](../../components/disabled) component via Vue's dependency injection. Returns `false` when no parent provides a disabled state.

## Usage

```ts
import { useDisabledInjection } from '@flux-ui/components';

const isTreeDisabled = useDisabledInjection();
```

## Type declarations

```ts
import type { Ref } from 'vue';

declare function useDisabledInjection(): Ref<boolean>;
```

## Used by

* [useDisabled](./useDisabled)

---

---
url: 'https://flux-ui.dev/guide/composables/useExpandableGroupInjection.md'
---
# useExpandableGroupInjection

This composable provides access to the [Expandable group](../../components/expandable/group) context. It allows child expandable items to register with the group and respond to group-level actions like closing all items.

## Usage

```ts
import { useExpandableGroupInjection } from '@flux-ui/components';

const { closeAll, register, unregister } = useExpandableGroupInjection();
```

## Type declarations

```ts
declare function useExpandableGroupInjection(): {
    closeAll(): void;
    register(uid: number, instance: object): void;
    unregister(uid: number): void;
};
```

## Used by

* [Expandable](../../components/expandable/)

---

---
url: 'https://flux-ui.dev/guide/composables/useFilterInjection.md'
---
# useFilterInjection

This composable provides access to the [Filter](../../components/filter/) context. It is used by filter sub-components to interact with the parent filter's state and actions.

## Usage

```ts
import { useFilterInjection } from '@flux-ui/components';

const { state, back, reset, getValue, hasValue, setValue } = useFilterInjection();
```

## Type declarations

```ts
import type { Ref } from 'vue';

declare function useFilterInjection(): {
    readonly state: Ref<object>;
    back(): void;
    reset(): void;
    getValue(): unknown;
    hasValue(): boolean;
    setValue(value: unknown): void;
};
```

## Used by

* [Filter](../../components/filter/)
  * [Date](../../components/filter/date)
  * [Option](../../components/filter/option)
  * [Options](../../components/filter/options)
  * [Range](../../components/filter/range)

---

---
url: 'https://flux-ui.dev/guide/composables/useFlyoutInjection.md'
---
# useFlyoutInjection

This composable provides access to the [Flyout](../../components/flyout) state. It allows child components to react to the flyout's open, opening and closing states.

## Usage

```ts
import { useFlyoutInjection } from '@flux-ui/components';

const { isClosing, isOpen, isOpening } = useFlyoutInjection();
```

## Type declarations

```ts
import type { Ref } from 'vue';

declare function useFlyoutInjection(): {
    readonly isClosing: Ref<boolean>;
    readonly isOpen: Ref<boolean>;
    readonly isOpening: Ref<boolean>;
};
```

## Used by

* [Flyout](../../components/flyout)
* [Menu](../../components/menu/)

---

---
url: 'https://flux-ui.dev/guide/composables/useFormFieldInjection.md'
---
# useFormFieldInjection

This composable provides access to the [Form field](../../components/form/field/) context. It supplies a unique ID that can be used for `for`/`id` attribute pairing between labels and inputs.

## Usage

```ts
import { useFormFieldInjection } from '@flux-ui/components';

const { id } = useFormFieldInjection();
```

## Type declarations

```ts
declare function useFormFieldInjection(): {
    readonly id: string;
};
```

## Used by

* [Form](../../components/form/)
  * [Input](../../components/form/input/)
  * [Select](../../components/form/select/)
  * [Text area](../../components/form/text-area)

---

---
url: 'https://flux-ui.dev/guide/composables/useTableInjection.md'
---
# useTableInjection

This composable provides access to the [Table](../../components/table/) layout context. It exposes the pinned column state and lets custom column headers register themselves so the table can compute its `grid-template-columns`.

## Usage

```ts
import { useTableInjection } from '@flux-ui/components';

const { pinnedEdges, pinnedOffsets, registerColumn } = useTableInjection();
```

## Type declarations

```ts
declare function useTableInjection(): {
    readonly pinnedEdges: Ref<{ readonly end: number; readonly start: number; }>;
    readonly pinnedOffsets: Ref<Map<number, number>>;

    registerColumn(element: Readonly<Ref<HTMLElement | null>>, column: Readonly<Ref<FluxTableColumnDef>>): () => void;
};
```

* `pinnedEdges`: the column index of the last start-pinned column and the first end-pinned column (`-1` when there is none). Used to render the scroll shadow on the outermost pinned column.
* `pinnedOffsets`: the sticky offset in pixels for each pinned column, keyed by column index.
* `registerColumn`: registers a column definition (sizing and pinning) for the table's `grid-template-columns`. Returns an unregister function.

## Used by

* [Table](../../components/table/)
  * [Row](../../components/table/row)
  * [Cell](../../components/table/cell)
  * [Header](../../components/table/header)

---

---
url: 'https://flux-ui.dev/guide/composables/useTooltipInjection.md'
---
# useTooltipInjection

This composable provides access to the [Tooltip](../../components/tooltip) provider context. It exposes a `calculate` method that triggers tooltip position recalculation.

## Usage

```ts
import { useTooltipInjection } from '@flux-ui/components';

const { calculate } = useTooltipInjection();

// Trigger position recalculation
calculate();
```

## Type declarations

```ts
declare function useTooltipInjection(): {
    calculate(): void;
};
```

## Used by

* [Tooltip](../../components/tooltip)

---

---
url: 'https://flux-ui.dev/guide/api/useFluxStore.md'
---
# useFluxStore

Provides access to the centralized Flux store that manages dialogs, snackbars and tooltips. This composable is primarily used internally by Flux components, but can be useful for advanced use cases.

## Usage

```ts
import { useFluxStore } from '@flux-ui/components';

const store = useFluxStore();

// Check if any dialogs are open
if (store.inertMain.value) {
    console.log('A dialog is currently blocking the main content.');
}
```

## Type declarations

```ts
import type { ComputedRef } from 'vue';

declare function useFluxStore(): FluxStore;

interface FluxStore {
    readonly alerts: FluxAlertObject[];
    readonly confirms: FluxConfirmObject[];
    readonly prompts: FluxPromptObject[];
    readonly snackbars: FluxSnackbarObject[];
    readonly tooltips: FluxTooltipObject[];

    readonly dialogs: number[];
    readonly dialogCount: number;
    readonly inertMain: ComputedRef<boolean>;
    readonly tooltip: ComputedRef<FluxTooltipObject | null>;

    addAlert(spec: Omit<FluxAlertObject, 'id'>): number;
    addConfirm(spec: Omit<FluxConfirmObject, 'id'>): number;
    addPrompt(spec: Omit<FluxPromptObject, 'id'>): number;
    addSnackbar(spec: Omit<FluxSnackbarObject, 'id'>): number;
    addTooltip(spec: Omit<FluxTooltipObject, 'id'>): number;

    removeAlert(id: number): void;
    removeConfirm(id: number): void;
    removePrompt(id: number): void;
    removeSnackbar(id: number): void;
    removeTooltip(id: number): void;

    updateSnackbar(id: number, spec: Partial<FluxSnackbarObject>): void;
    updateTooltip(id: number, spec: Partial<FluxTooltipObject>): void;

    registerDialog(): FluxDialogRegistration;

    showAlert(spec: Omit<FluxAlertObject, 'id' | 'onClose'>): Promise<void>;
    showConfirm(spec: Omit<FluxConfirmObject, 'id' | 'onCancel' | 'onConfirm'>): Promise<boolean>;
    showPrompt(spec: Omit<FluxPromptObject, 'id' | 'onCancel' | 'onConfirm'>): Promise<string | false>;
    showSnackbar(spec: Omit<FluxSnackbarObject, 'id'> & { duration?: number }): Promise<void>;
    showSnackbarSync(spec: Omit<FluxSnackbarObject, 'id'> & { duration?: number }): void;
}

interface FluxDialogRegistration {
    readonly id: number;

    getPosition(): number;
    isCurrent(): boolean;
    unregister(): void;
}
```

::: tip
For showing dialogs and snackbars, prefer using the dedicated functions [showAlert](../../components/attention/alert), [showConfirm](../../components/attention/confirm), [showPrompt](../../components/attention/prompt) and [showSnackbar](../../components/attention/snackbar) instead of interacting with the store directly.
:::

---

---
url: 'https://flux-ui.dev/guide/api/helpers.md'
---
# Helper functions

Utility helpers and type guards for working with Flux components.

## defineFilter

Macro for building a [Filter](../../components/filter) definition factory. Call it on the top level of `<script setup>` so `FluxFilter` and `FluxFilterBar` can build the runtime definition (label, icon, badge text, lifecycle, …) from your component's props.

::: warning Vite plugin required
`defineFilter()` is a compile-time macro implemented by `defineFilterMacro` from `@flux-ui/components/vite`. Add it to the `plugins` array of your Vite config in any project that defines its own filters. Without the plugin the call is left as a no-op and the filter will not register.
:::

```ts
import { defineFilter, useFilterInjection } from '@flux-ui/components';
import type { FluxFilterValue, FluxIconName } from '@flux-ui/types';

type Props = {
    readonly icon?: FluxIconName;
    readonly label: string;
    readonly name: string;
    readonly disabled?: boolean;
    readonly defaultValue?: FluxFilterValue;
};

defineFilter<Props>(p => ({
    type: 'toggle',
    name: p.name,
    label: p.label,
    icon: p.icon,
    disabled: p.disabled,
    defaultValue: p.defaultValue,
    async getValueLabel(value) {
        return value === true ? 'On' : value === false ? 'Off' : null;
    }
}));
```

The factory is invoked by `FluxFilterBase` on each filter VNode's props, so it must be a self-contained pure function: no references to local `<script setup>` variables. The `defineFilterMacro()` Vite plugin (from `@basmilius/vite-preset`) compiles the call into the appropriate `defineOptions({ __filterDefinitionFactory: ... })`.

## isFluxFilterOptionHeader

Checks whether a [Filter option](../../components/filter/option) row is a header (sub-section title) instead of a selectable item.

```ts
import { isFluxFilterOptionHeader } from '@flux-ui/components';

if (isFluxFilterOptionHeader(row)) {
    console.log('Header:', row.title);
}
```

## isFluxFilterOptionItem

Checks whether a [Filter option](../../components/filter/option) row is a selectable item with a value.

```ts
import { isFluxFilterOptionItem } from '@flux-ui/components';

if (isFluxFilterOptionItem(row)) {
    console.log('Selectable:', row.label, '→', row.value);
}
```

## isFluxFormSelectGroup

Checks if a given item is a [Form select](../../components/form/select/) group.

```ts
import { isFluxFormSelectGroup } from '@flux-ui/components';

if (isFluxFormSelectGroup(item)) {
    console.log('This is a group with children:', item.label);
}
```

## isFluxFormSelectOption

Checks if a given item is a [Form select](../../components/form/select/) option.

```ts
import { isFluxFormSelectOption } from '@flux-ui/components';

if (isFluxFormSelectOption(item)) {
    console.log('This is a selectable option with value:', item.value);
}
```

## Type declarations

```ts
declare function defineFilter<TProps, TValue extends FluxFilterValue = FluxFilterValue>(
    factory: (props: TProps) => FluxFilterDefinition<TValue>
): (props: TProps) => FluxFilterDefinition<TValue>;

declare function isFluxFilterOptionHeader(item: object): item is FluxFilterOptionHeader;

declare function isFluxFilterOptionItem(item: object): item is FluxFilterOptionItem;

declare function isFluxFormSelectGroup(item: unknown): item is FluxFormSelectGroup;

declare function isFluxFormSelectOption(item: unknown): item is FluxFormSelectOption;
```

---

---
url: 'https://flux-ui.dev/guide/api/types.md'
---
# Types

All public TypeScript types are exported from `@flux-ui/types`. This page lists the types you'll most commonly run into when consuming the components (the ones that show up in component props, slot bindings and store helpers).

```ts
import type { FluxColor, FluxIconName, FluxSize } from '@flux-ui/types';
```

## Common

### `FluxAlignment`

```ts
type FluxAlignment = 'start' | 'center' | 'end';
```

Used by layout components such as [Overflow bar](../../components/overflow-bar) and [Flex](../../components/layout/flex/).

### `FluxColor`

```ts
type FluxColor = 'gray' | 'primary' | 'danger' | 'info' | 'success' | 'warning';
```

The six semantic colors that drive everything from [Badge](../../components/badge) and [Notice](../../components/attention/notice) to [Avatar](../../components/avatar) status dots.

### `FluxDirection`

```ts
type FluxDirection = 'horizontal' | 'vertical';
```

### `FluxIconName`

```ts
type FluxIconName = string; // re-export of FontAwesome's IconName
```

Any Font Awesome icon name. The icon must be registered through [`fluxRegisterIcons`](./helpers) before it can be used.

### `FluxInputMask`

```ts
type FluxInputMask = 'bic' | 'iban' | 'vat';
```

The built-in masks for [Form input](../../components/form/input).

### `FluxInputType`

```ts
type FluxInputType =
    | 'color'
    | 'date'
    | 'datetime-local'
    | 'email'
    | 'file'
    | 'month'
    | 'number'
    | 'password'
    | 'search'
    | 'tel'
    | 'text'
    | 'time'
    | 'url'
    | 'week';
```

### `FluxPressableType`

```ts
type FluxPressableType = 'button' | 'link' | 'route' | 'none';
```

Determines how a pressable component renders: as a `<button>`, an `<a>` link, a Vue Router `<RouterLink>`, or as a non-interactive element.

### `FluxSize`

```ts
type FluxSize = 'small' | 'medium' | 'large';
```

### `FluxTo`

```ts
type FluxTo = {
    name?: string;
    path?: string;
    hash?: string;
    query?: Record<string, string | (string | null)[] | null | undefined>;
    params?: Record<string, string | number>;
    state?: Record<string, string | number | boolean>;
    append?: boolean;
    replace?: boolean;
};
```

The Vue Router location object accepted by every `to` prop. Forwarded directly to `<RouterLink>`.

### `FluxAutoCompleteType`

A union of every valid HTML `autocomplete` token (`name`, `email`, `cc-number`, `address-level2`, etc.) plus their grouped variants (`shipping email`, `billing tel`, …). Accepts arbitrary strings as a fallback.

### `FluxMaybePromise`

```ts
type FluxMaybePromise<T> = T | Promise<T>;
```

Used by APIs that accept either a synchronous or an asynchronous value.

## Forms

### `FluxFormInputBaseProps`

```ts
type FluxFormInputBaseProps = {
    readonly autoFocus?: boolean;
    readonly disabled?: boolean;
    readonly error?: string | null;
    readonly isLoading?: boolean;
    readonly isReadonly?: boolean;
    readonly isSecondary?: boolean;
    readonly name?: string;
    readonly placeholder?: string;
};
```

The shared shape of every form input component (`FluxFormInput`, `FluxFormSelect`, `FluxFormDateInput`, …). Reuse it when you build your own input wrappers.

### `FluxFormSelectEntry`

```ts
type FluxFormSelectGroup = {
    readonly icon?: FluxIconName;
    readonly label: string;
    readonly value?: never;
};

type FluxFormSelectOption = {
    readonly badge?: string;
    readonly command?: string;
    readonly commandIcon?: FluxIconName;
    readonly icon?: FluxIconName;
    readonly imageAlt?: string;
    readonly imageSrc?: string;
    readonly label: string;
    readonly selectable?: boolean;
    readonly value: string | number | null;
};

type FluxFormSelectEntry = FluxFormSelectGroup | FluxFormSelectOption;
```

The shape of items inside [Form select](../../components/form/select). Use [`isFluxFormSelectGroup`](./helpers) and [`isFluxFormSelectOption`](./helpers) to narrow at runtime.

### `FluxFormSelectValue`

```ts
type FluxFormSelectValueSingle = string | number | null;
type FluxFormSelectValue = FluxFormSelectValueSingle | FluxFormSelectValueSingle[];
```

### `FluxFormTreeViewSelectOption`

```ts
type FluxFormTreeViewSelectOption = {
    readonly id: string | number;
    readonly label: string;
    readonly icon?: FluxIconName;
    readonly selectable?: boolean;
    readonly children?: FluxFormTreeViewSelectOption[];
};
```

The shape of items inside [Tree view select](../../components/form/tree-view-select).

## Filters

### `FluxFilterState`

```ts
type FluxFilterValueSingle = DateTime | string | boolean | number | null;
type FluxFilterValue = FluxFilterValueSingle | FluxFilterValueSingle[];
type FluxFilterState<T extends Record<string, unknown> = Record<string, FluxFilterValue>> = T;
```

The current value of a [Filter](../../components/filter) keyed by filter `name`. Pass a generic to type the state shape for custom filter types.

### `FluxFilterDefinition`

```ts
type FluxFilterDefinition<TValue = FluxFilterValue> = {
    readonly type: string;
    readonly name: string;
    readonly label: string;
    readonly icon?: FluxIconName;
    readonly disabled?: boolean;
    readonly defaultValue?: TValue;
    getValueLabel(value: TValue): Promise<string | null>;
    onChange?(value: TValue): void;
    onClear?(): void;
};
```

The runtime metadata returned by a filter component's `__filterDefinitionFactory`. Built via [`defineFilter`](./helpers) inside `defineOptions`. `FluxFilterBase` calls the factory on each slot VNode to build the menu, badge labels and lifecycle hooks.

## Notify objects

The objects passed to the programmatic [Alert](../../components/attention/alert), [Confirm](../../components/attention/confirm), [Prompt](../../components/attention/prompt), [Snackbar](../../components/attention/snackbar) and tooltip APIs.

### `FluxAlertObject`

```ts
type FluxAlertObject = {
    readonly id: number;
    readonly icon?: FluxIconName;
    readonly title: string;
    readonly message: string;

    onClose(): void;
};
```

### `FluxConfirmObject`

```ts
type FluxConfirmObject = FluxAlertObject & {
    onCancel(): void;
    onConfirm(): void;
};
```

### `FluxPromptObject`

```ts
type FluxPromptObject = FluxAlertObject & {
    readonly fieldLabel: string;
    readonly fieldPlaceholder?: string;
    readonly fieldType?: FluxInputType;

    onCancel(): void;
    onConfirm(text: string): void;
};
```

### `FluxSnackbarObject`

```ts
type FluxSnackbarObject = {
    readonly id: number;
    readonly actions?: Record<string, string>;
    readonly color?: FluxColor;
    readonly icon?: FluxIconName;
    readonly isCloseable?: boolean;
    readonly isLoading?: boolean;
    readonly isRendered?: boolean;
    readonly message?: string;
    readonly progressIndeterminate?: boolean;
    readonly progressMax?: number;
    readonly progressMin?: number;
    readonly progressStatus?: string;
    readonly progressValue?: number;
    readonly subMessage?: string;
    readonly title?: string;

    onAction?(actionKey: string): void;
    onClose?(): void;
};
```

## Component-specific types

These types are exported from `@flux-ui/types` but are typically only referenced when you wrap or extend the corresponding component:

## Statistics

### `FluxStatisticsChange`

```ts
type FluxStatisticsChange = {
    readonly color?: FluxColor;
    readonly icon?: FluxIconName;
    readonly value: string;
};
```

The trend indicator passed to [`FluxStatisticsKpi`](../../statistics/components/kpi) and [`FluxStatisticsChange`](../../statistics/components/change).

---

---
url: 'https://flux-ui.dev/components.md'
---

# Components

Flux provides a wide range of pre-built components that serve various purposes in web development. These components are designed to be consistent and reusable, helping developers efficiently build and customize user interfaces. From basic elements like buttons and input fields to more complex structures like modals and data tables, Flux's component library covers many common needs in application development.

The components are grouped by what you reach for them to do, from everyday buttons and forms up to complete data displays, with the low-level primitives and utilities gathered near the end. Use the categories below to find your way around.

## Buttons & actions

Buttons and clickable triggers that let people perform an action.

## Indicators

Badges, tags and loading states that communicate status at a glance.

## Forms & input

Everything you need to capture and edit user input, from single fields to complete forms.

## Navigation

Wayfinding and view-switching, so people can move around and change what they see.

## Data display

Tables, lists and other structured ways to present data.

## Media & people

Avatars, personas and media so faces and imagery feel at home.

## Layout

Structure and align content into responsive, consistent layouts.

## Overlays & surfaces

Panels, overlays and floating surfaces that layer content above the page.

## Feedback

Alerts, notices, snackbars and tooltips that keep people informed about what is happening.

## Primitives

The low-level building blocks and app-level primitives that everything else builds on.

## Utilities

Behavioural helpers with no visual output of their own, from sharing a disabled state to rendering a dynamic view.

## Transitions

Ready-made transition components for animating content in and out.

---

---
url: 'https://flux-ui.dev/components/buttons-actions.md'
---

# Buttons & actions

The action components are the buttons and clickable triggers that let people perform an action, from primary and destructive buttons to chips, toolbars and inline actions.

---

---
url: 'https://flux-ui.dev/components/action.md'
---

# Action

Actions can be used to add functionality to components like data tables. They can navigate to another view or perform an in-page action, such as displaying a share overlay.

::: render
render=../code/components/action/preview.vue
:::

## Examples

::: example Basic || A simple action.
example=../code/components/action/basic.vue
:::

::: example Active || Use `is-active` to highlight the selected action, for example in a toolbar where one option is currently chosen.
example=../code/components/action/active.vue
:::

::: example Destructive || A destructive action can be used for destructive actions such as deleting something.
example=../code/components/action/destructive.vue
:::

::: example Loading || A loading state action can signify that something is loading, for instance, retrieving data after pressing on the action.
example=../code/components/action/loading.vue
:::

::: example Group || Having several actions can be grouped together.
example=../code/components/action/grouped.vue
:::

::: example Table || Actions are commonly placed in the last column of a data table to operate on a single row.
example=../code/components/action/table.vue
:::

## Used components

* [Icon](./icon)
* [Spinner](./spinner)

---

---
url: 'https://flux-ui.dev/components/action-bar.md'
---

# Action bar

The action bar is a toolbar commonly used alongside data tables. It can display a primary action, a search bar, and a filter button, with the filters shown in a flyout.

::: render
render=../code/components/action-bar/preview.vue
:::

## Examples

::: example Basic || A simple and basic action bar.
example=../code/components/action-bar/basic.vue
:::

::: example Datatable || Using an action bar with a datatable.
example=../code/components/action-bar/datatable.vue
:::

## Used components

* [Button](./button)
  * [Secondary](./button/secondary)
  * [Destructive](./button/destructive)
  * [Group](./button/group)
* [Flyout](./flyout)
* [Layout](./layout)
  * [Flex](./layout/flex/)
  * [Spacer](./layout/spacer)
* [Tooltip](./tooltip)

---

---
url: 'https://flux-ui.dev/components/action-pane.md'
---

# Action pane

An action pane highlights important actions or new features to the user.

::: render
render=../code/components/action-pane/preview.vue
:::

## Examples

::: example Plain || A simple action pane without any buttons.
example=../code/components/action-pane/plain.vue
:::

::: example Button || An action pane with buttons.
example=../code/components/action-pane/buttons.vue
:::

## Used components

* [Pane](./pane)
  * [Body](./pane/body)
* [Layout](./layout)
  * [Flex](./layout/flex/)

---

---
url: 'https://flux-ui.dev/components/button.md'
---

# Buttons

The button is a clickable element that triggers an action, such as starting a new process, modifying an existing one, or performing a specific task. Place primary buttons prominently and label them clearly so they are easy to find and use.

## Available buttons

* [Primary](./primary)
* [Secondary](./secondary)
* [Destructive](./destructive)
* [Publish](./publish)
* [Group](./group)
* [Split](./split)
* [Primary link](./primary-link)
* [Secondary link](./secondary-link)

---

---
url: 'https://flux-ui.dev/components/button/primary.md'
---

# Primary button

The primary button represents the main action on a page or within a component. It should be used sparingly to draw attention to the most important task a user can perform.

::: render
render=../../code/components/button/primary/preview.vue
:::

## Examples

::: warning
Overusing primary buttons can distract users, so use them sparingly in your interface.
:::

::: example Basic || A basic primary button with a label.
example=../../code/components/button/primary/basic.vue
:::

::: example Icon || A primary button with an icon at the start or the end.
example=../../code/components/button/primary/icon.vue
:::

::: example Sizes || The primary button is available in four sizes.
example=../../code/components/button/primary/sizes.vue
:::

::: example Active || Use is-active to keep the button in its pressed state, for example as a toggle.
example=../../code/components/button/primary/active.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/button/secondary.md'
---

# Secondary button

The secondary button is used for less prominent actions that support the main task. It offers a subtle visual contrast to the primary button while maintaining clear visibility and accessibility.

::: render
render=../../code/components/button/secondary/preview.vue
:::

## Examples

::: example Basic || A basic secondary button with a label.
example=../../code/components/button/secondary/basic.vue
:::

::: example Icon || A secondary button with an icon at the start or the end.
example=../../code/components/button/secondary/icon.vue
:::

::: example Sizes || The secondary button is available in four sizes.
example=../../code/components/button/secondary/sizes.vue
:::

::: example Active || Use is-active to keep the button in its pressed state, for example as a toggle.
example=../../code/components/button/secondary/active.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/button/destructive.md'
---

# Destructive button

The destructive button is reserved for actions that remove data or undo progress, such as deleting or resetting. It uses a distinct warning color, typically red, to communicate risk and encourage users to confirm their intent before proceeding.

::: render
render=../../code/components/button/destructive/preview.vue
:::

## Examples

::: example Basic || A basic destructive button with a label.
example=../../code/components/button/destructive/basic.vue
:::

::: example Icon || A destructive button with an icon at the start or the end.
example=../../code/components/button/destructive/icon.vue
:::

::: example Sizes || The destructive button is available in four sizes.
example=../../code/components/button/destructive/sizes.vue
:::

::: example Active || Use is-active to keep the button in its pressed state, for example as a toggle.
example=../../code/components/button/destructive/active.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/button/group.md'
---

# Button group

This component groups multiple buttons together. It modifies the border radius of the buttons and removes any gaps between them.

::: render
render=../../code/components/button/group/preview.vue
:::

## Examples

::: example Icons
example=../../code/components/button/group/icons.vue
:::

::: example Labels
example=../../code/components/button/group/labels.vue
:::

---

---
url: 'https://flux-ui.dev/components/button/split.md'
---

# Split button

The split button pairs one primary action with a menu of secondary actions. A common use case is a download button that offers additional download options.

The more button carries `aria-haspopup="menu"` and reflects the flyout state through `aria-expanded`. Setting `disabled` disables the more button and prevents the flyout from opening.

::: render
render=../../code/components/button/split/preview.vue
:::

## Examples

::: example Basic || A basic split button.
example=../../code/components/button/split/basic.vue
:::

::: example Save options || A primary save button with secondary save variants.
example=../../code/components/button/split/save-options.vue
:::

::: example Disabled || Set disabled to disable the more button and prevent the flyout from opening.
example=../../code/components/button/split/disabled.vue
:::

## Used components

* [Button](../button)
  * [Secondary](../button/secondary)
* [Flyout](../flyout)

---

---
url: 'https://flux-ui.dev/components/button/primary-link.md'
---

# Primary Link button

The primary link button represents call to action on a page or within a component. It should be used sparingly to draw attention to the most important task a user can perform.

::: render
render=../../code/components/button/primary-link/preview.vue
:::

## Examples

::: example Basic || A basic primary link button with a label.
example=../../code/components/button/primary-link/basic.vue
:::

::: example Icon || A primary link button with an icon at the start or the end.
example=../../code/components/button/primary-link/icon.vue
:::

::: example Sizes || The primary link button is available in four sizes.
example=../../code/components/button/primary-link/sizes.vue
:::

::: example Active || Use is-active to keep the button in its pressed state, for example as a toggle.
example=../../code/components/button/primary-link/active.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/button/secondary-link.md'
---

# Secondary Link button

The secondary link button is used for less prominent actions. It offers a subtle visual contrast to the primary link button while maintaining clear visibility and accessibility.

::: render
render=../../code/components/button/secondary-link/preview.vue
:::

## Examples

::: example Basic || A basic secondary link button with a label.
example=../../code/components/button/secondary-link/basic.vue
:::

::: example Icon || A secondary link button with an icon at the start or the end.
example=../../code/components/button/secondary-link/icon.vue
:::

::: example Sizes || The secondary link button is available in four sizes.
example=../../code/components/button/secondary-link/sizes.vue
:::

::: example Active || Use is-active to keep the button in its pressed state, for example as a toggle.
example=../../code/components/button/secondary-link/active.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/button/publish.md'
---

# Publish button

The publish button is a specialized primary action used to finalize or make content public. It signals a clear commitment, once pressed, changes are saved or content is shared.

::: render
render=../../code/components/button/publish/preview.vue
:::

## Examples

::: example Basic || A basic publish button.
example=../../code/components/button/publish/basic.vue
:::

::: example Sizes || The publish button is available in four sizes.
example=../../code/components/button/publish/sizes.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/chip.md'
---

# Chip

This component displays brief information with optional interactivity. It supports icons before and after the label and can function as either a static element or a selectable button with a selected state.

::: render
render=../code/components/chip/preview.vue
:::

## Examples

::: example List || Chips can be placed within stacks to create a list.
example=../code/components/chip/list.vue
:::

::: example Selectable || A chip that is selectable can be used in filters for example.
example=../code/components/chip/selectable.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/toolbar.md'
---

# Toolbar

The toolbar component is used for actions within a certain context. For example, when you have a stack of products, toolbars can be used to display actions for each product. A toolbar can have groups, buttons and separators within them.

The toolbar renders with `role="toolbar"` and manages a horizontal focus zone: its focusable controls are reachable with the arrow keys as a single tab stop. Provide an `aria-label` to give it a meaningful accessible name.

::: render
render=../../code/components/toolbar/preview.vue
:::

## Examples

::: example Basic || A basic toolbar.
example=../../code/components/toolbar/basic.vue
:::

::: example Standalone || A standalone text-formatting toolbar with multiple action groups.
example=../../code/components/toolbar/standalone.vue
:::

::: example In a pane || A flat toolbar placed between a pane header and its body acts as a context bar for the content below.
example=../../code/components/toolbar/in-pane.vue
:::

## Used components

* [Layout](../layout)
  * [Flex](../layout/flex/)

---

---
url: 'https://flux-ui.dev/components/toolbar/group.md'
---

# Toolbar group

The toolbar group component organizes multiple action elements within a toolbar, grouping them together into a clear and cohesive section. It helps maintain visual structure and makes related controls easier to recognize and use.

The group renders with `role="group"`. Provide an `aria-label` to give the grouped controls an accessible name.

::: render
render=../../code/components/toolbar/group/preview.vue
:::

::: tip
The toolbar group component basically serves as a horizontal [Flex](../layout/flex/).
:::

## Examples

::: example Basic || A basic toolbar.
example=../../code/components/toolbar/group/basic.vue
:::

## Used components

* [Layout](../layout)
  * [Flex](../layout/flex/)

---

---
url: 'https://flux-ui.dev/components/indicators.md'
---

# Indicators

The indicator components communicate state at a glance, from badges and tags to progress bars, spinners and loading placeholders.

---

---
url: 'https://flux-ui.dev/components/badge.md'
---

# Badge

The badge is a label for elements in the UI. Use it, for example, to show the status of an order or highlight important information.

::: render
render=../code/components/badge/preview.vue
:::

::: tip
Flux also has [Tags](./tag), which look similar to badges.
:::

## Examples

::: example Basic || A simple badge can deliver additional insights about an entity.
example=../code/components/badge/basic.vue
:::

::: example Colors || Badges come in six colors, so you can map them to the meaning that fits your context.
example=../code/components/badge/colors.vue
:::

::: example Colored || The colored variant fills the badge with a tinted background, making it stand out more.
example=../code/components/badge/colored.vue
:::

::: example Dot || A dot badge is useful for indicating statuses, for instance, the status of a server.
example=../code/components/badge/dot.vue
:::

::: example Icon || Including icons in badges can improve their clarity, for instance, indicating an app's release status.
example=../code/components/badge/icon.vue
:::

::: example Loading || A loading state badge can signify that a table row is processing, for instance, retrieving data.
example=../code/components/badge/loading.vue
:::

::: example Sizes || Badges are available in three sizes. The default size is medium.
example=../code/components/badge/size.vue
:::

::: example Statuses || Combining colors and icons makes states scannable at a glance, for instance, the payment status of an order.
example=../code/components/badge/status.vue
:::

::: example Deletable || Deletable badges work well for active filters that the user can remove again, for instance, in search results.
example=../code/components/badge/deletable.vue
:::

## Used components

* [Icon](./icon)
* [Spinner](./spinner)

---

---
url: 'https://flux-ui.dev/components/badge-group.md'
---

# Badge group

The badge group combines a badge with a message in a single pill. Place a badge in the start or end slot; it inherits the group's color and size automatically. Use it, for example, to announce a new feature or to link to release notes.

::: render
render=../code/components/badge-group/preview.vue
:::

::: tip
Use a [Badge](./badge) when a single label is enough.
:::

## Examples

::: example Basic || A badge group pairs a short badge with a supporting message.
example=../code/components/badge-group/basic.vue
:::

::: example Placement || The badge can be placed before or after the message using the start and end slots.
example=../code/components/badge-group/placement.vue
:::

::: example Icon || An icon at the end hints that the badge group is interactive, for instance, linking to release notes.
example=../code/components/badge-group/icon.vue
:::

::: example Sizes || Badge groups are available in three sizes. The default size is medium.
example=../code/components/badge-group/size.vue
:::

::: example System status || Badge groups can surface status updates, for instance, on a status page or in an admin dashboard.
example=../code/components/badge-group/status.vue
:::

::: example Job listings || A clickable badge group with a department badge forms a compact job listing.
example=../code/components/badge-group/vacancy.vue
:::

## Used components

* [Badge](./badge)
* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/placeholder.md'
---

# Placeholder

A placeholder is used for situations where the user should provide content, but it hasn't already. This component will display the steps the user has to take.

::: render
render=../code/components/placeholder/preview.vue
:::

## Examples

::: example Basic || A basic placeholder.
example=../code/components/placeholder/basic.vue
:::

::: example Clickable || A placeholder that can be clicked.
example=../code/components/placeholder/clickable.vue
:::

::: example Button || A placeholder with a custom button inside.
example=../code/components/placeholder/button.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/progress-bar.md'
---

# Progress bar

The progress bar is a visual indicator of a task's status and completion, useful for operations that take a noticeable amount of time.

::: render
render=../code/components/progress-bar/preview.vue
:::

::: tip Accessibility
The reported `aria-valuenow` is always clamped to the `min`/`max` range, so out-of-bounds values never confuse assistive technology. When `is-indeterminate` is set, `aria-valuenow` is omitted entirely so screen readers announce an in-progress state of unknown duration.
:::

## Examples

::: example Basic || A basic progress bar.
example=../code/components/progress-bar/basic.vue
:::

::: example Colors || Progress bars in each of the available colors.
example=../code/components/progress-bar/colors.vue
:::

::: example Status || A progress bar with a status message.
example=../code/components/progress-bar/status.vue
:::

::: example Indeterminate || A progress bar with an indeterminate state.
example=../code/components/progress-bar/indeterminate.vue
:::

::: example Complete || A progress bar that will complete itself.
example=../code/components/progress-bar/complete.vue
:::

::: example Snackbar || A progress bar inside a snackbar.
example=../code/components/progress-bar/snackbar.vue
:::

## Used components

* [Layout](./layout)
  * [Flex](./layout/flex/)

---

---
url: 'https://flux-ui.dev/components/skeleton.md'
---

# Skeleton

A skeleton is an animated placeholder that stands in for content while it is loading. It conveys the rough shape of the upcoming content and reduces the perceived loading time. Compose multiple skeletons to mirror the layout that will replace them. The shimmer animation is automatically replaced by a subtle pulse when the user prefers reduced motion.

::: render
render=../code/components/skeleton/preview.vue
:::

::: tip
For a static empty state with an icon and a message rather than a loading state, use a [Placeholder](./placeholder).
:::

## Examples

::: example Basic || A few lines of text being loaded.
example=../code/components/skeleton/basic.vue
:::

::: example Variants || All available skeleton shapes.
example=../code/components/skeleton/variants.vue
:::

::: example Card || A skeleton mirroring a media card layout.
example=../code/components/skeleton/card.vue
:::

::: example Table || A table renders skeleton rows through its `loading` slot while its data is loading.
example=../code/components/skeleton/table.vue
:::

---

---
url: 'https://flux-ui.dev/components/spinner.md'
---

# Spinner

The spinner indicates that a process is in progress. Use it to signal that the system is working, for example while loading data or performing a long calculation.

::: render
render=../code/components/spinner/preview.vue
:::

::: tip Accessibility
Without a `label` the spinner is purely decorative and hidden from assistive technology (`aria-hidden`). Provide a `label` to expose it as a live status (`role="status"`) so screen readers announce what is loading.
:::

## Examples

::: example Basic || A basic spinner.
example=../code/components/spinner/basic.vue
:::

::: example Colors || Use the `color` prop to match the spinner to its context.
example=../code/components/spinner/colors.vue
:::

---

---
url: 'https://flux-ui.dev/components/tag.md'
---

# Tag

The tag is a label for a specific element in the UI, for example to show the status of an order.

::: render
render=../code/components/tag/preview.vue
:::

## Examples

::: example Basic || A basic tag.
example=../code/components/tag/basic.vue
:::

::: example Dot || A tag with a colored dot.
example=../code/components/tag/dot.vue
:::

::: example Icon || A tag with an icon.
example=../code/components/tag/icon.vue
:::

::: example Loading || A tag with a loading state.
example=../code/components/tag/loading.vue
:::

## Used components

* [Icon](./icon)
* [Spinner](./spinner)

---

---
url: 'https://flux-ui.dev/components/forms.md'
---

# Forms & input

The form and input components capture and edit user input, from single fields and pickers to complete, validated forms.

---

---
url: 'https://flux-ui.dev/components/form/checkbox.md'
---

# Checkbox

A clean and functional input element that supports labels and multiple states, designed to enhance usability and accessibility in forms and interfaces.

::: render
render=../../../code/components/form/checkbox/preview.vue
:::

::: tip
To bind a set of checkboxes to a single array, use a [Checkbox group](./group). When you place more than one control in a single [Form field](../field/), set `as="group"` on the field so the label is rendered as a group label (`role="group"` + `aria-labelledby`) instead of a single `<label for>`.
:::

## Examples

::: example Basic || A simple and basic checkbox.
example=../../../code/components/form/checkbox/basic.vue
:::

::: example Indeterminate || A checkbox with an indeterminate state.
example=../../../code/components/form/checkbox/indeterminate.vue
:::

::: example Sub-label || A checkbox with a secondary line of text below the label.
example=../../../code/components/form/checkbox/sub-label.vue
:::

::: example Custom label || A checkbox that uses the label slot to render HTML inside its label.
example=../../../code/components/form/checkbox/custom-label.vue
:::

::: example Disabled || A disabled checkbox in both the checked and unchecked state.
example=../../../code/components/form/checkbox/disabled.vue
:::

::: example Invalid || A checkbox with an error message.
example=../../../code/components/form/checkbox/invalid.vue
:::

::: example Read-only || A read-only checkbox that cannot be toggled.
example=../../../code/components/form/checkbox/readonly.vue
:::

## Used components

* [Checkbox group](./group)
* [Icon](../../icon)

---

---
url: 'https://flux-ui.dev/components/form/checkbox/group.md'
---

# Checkbox group

A checkbox group binds a set of [checkboxes](./) to a single array through `v-model`. Each checkbox carries a `value`; checking it adds that value to the array, unchecking removes it.

::: render
render=../../../code/components/form/checkbox/group/preview.vue
:::

::: tip
Wrap the group in a [Form field](../field/) with `as="group"` to attach an accessible group label. Used standalone, pass an `aria-label` instead. When the surrounding field is `required`, the group automatically receives `aria-required`, and setting `error` exposes `aria-invalid` on the group container.
:::

## Examples

::: example Basic || A checkbox group inside a form field.
example=../../../code/components/form/checkbox/group/basic.vue
:::

::: example Inline || A checkbox group laid out horizontally.
example=../../../code/components/form/checkbox/group/inline.vue
:::

::: example Disabled item || A checkbox group with a single disabled option.
example=../../../code/components/form/checkbox/group/disabled.vue
:::

::: example Tile || Card-style options through [Checkbox tile](./tile), with an icon and description.
example=../../../code/components/form/checkbox/tile/stacked.vue
:::

::: example Mixed || Combine tiles with a regular checkbox for a less prominent option.
example=../../../code/components/form/checkbox/tile/mixed.vue
:::

::: example Connected || Join the tiles into a single block with is-connected.
example=../../../code/components/form/checkbox/tile/connected.vue
:::

## Used components

* [Checkbox](./)
* [Checkbox tile](./tile)

---

---
url: 'https://flux-ui.dev/components/form/checkbox/tile.md'
---

# Checkbox tile

A checkbox tile is a card-style [Checkbox](./) for prominent, multi-select choices. Each option carries an icon, a label and a short description. Place the tiles inside a [Checkbox group](./group); the group binds the selected values to an array.

::: render
render=../../../code/components/form/checkbox/tile/preview.vue
:::

::: tip
Tiles fill the group's width when stacked. Add `is-inline` to the [Checkbox group](./group) to lay them out in equal columns, best for two or three options. You can mix tiles and regular [Checkboxes](./) in the same group.
:::

## Examples

::: example Stacked || Card-style checkboxes stacked at full width.
example=../../../code/components/form/checkbox/tile/stacked.vue
:::

::: example Inline || Tiles laid out in equal columns with is-inline.
example=../../../code/components/form/checkbox/tile/inline.vue
:::

::: example Without description || Compact tiles with just an icon and label, no sub-label.
example=../../../code/components/form/checkbox/tile/without-description.vue
:::

::: example Account security || A real-world group with a description per option.
example=../../../code/components/form/checkbox/tile/security.vue
:::

## Used components

* [Checkbox group](./group)
* [Icon](../../icon)

---

---
url: 'https://flux-ui.dev/components/color/picker.md'
---

# Color picker

The color picker lets users select and adjust a color in HEX, RGB, HSV, or HSL. It offers a hue and saturation area, an optional alpha slider for transparency, and input fields for precise values.

::: render
render=../../code/components/color-picker/preview.vue
:::

## Examples

::: example Basic || A basic color picker that is shown directly.
example=../../code/components/color-picker/basic.vue
:::

::: example Flyout || A basic color picker that is shown directly.
example=../../code/components/color-picker/flyout.vue
:::

## Used components

* [Form](../form)
  * [Field](../form/field)
  * [Input](../form/input)
  * [Slider](../form/slider)
* [Pane](../pane)

---

---
url: 'https://flux-ui.dev/components/color/select.md'
---

# Color select

The color select lets users pick a color from a predefined set, or choose a custom color with the [Color picker](./picker) when `is-custom-allowed` is set.

::: render
render=../../code/components/color-select/preview.vue
:::

## Examples

::: example Simple || With this example, the user can select a color from a set of predefined colors.
example=../../code/components/color-select/simple.vue
:::

::: example Custom || In this example, the user can select a color from a predefined set of colors, or select a custom color.
example=../../code/components/color-select/custom.vue
:::

## Used components

* [Button](../button)
  * [Primary](../button/primary)
  * [Secondary](../button/secondary)
* Color
  * [Color picker](./picker)
* [Flyout](../flyout)
* [Icon](../icon)
* [Pane](../pane)

---

---
url: 'https://flux-ui.dev/components/form/column.md'
---

# Column

The column arranges fields in a vertical stack. It's useful when you want inputs to appear one above the other in a clear, linear flow. This layout helps guide the user downward through the form, making it easy to read and complete each field step-by-step.

::: render
render=../../code/components/form/column/preview.vue
:::

## Examples

::: example Basic || A basic form column.
example=../../code/components/form/column/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/combobox.md'
---

# Combobox

The Combobox component is a searchable select. With `is-creatable` enabled it also lets users add entries that are not in the list, by typing a value and pressing Enter or clicking the "Create" option. Created entries are tracked internally so they appear immediately as selected.

::: render
render=../../code/components/form/combobox/preview.vue
:::

::: tip
For a plain, option-bounded select without free-text entry, use [Select](./select/) instead.
:::

## Examples

::: example Basic || A searchable combobox bound to a list of options.
example=../../code/components/form/combobox/basic.vue
:::

::: example Creatable || A combobox that allows creating new entries.
example=../../code/components/form/combobox/creatable.vue
:::

::: example Multiple || A creatable combobox that allows multiple values.
example=../../code/components/form/combobox/multiple.vue
:::

## Used components

* [Select](./select/)

---

---
url: 'https://flux-ui.dev/components/form/date.md'
---

# Date

An input element designed for selecting dates, incorporating a dropdown interface with a calendar for ease of use. Provides support for configurable options such as minimum and maximum date ranges.

::: render
render=../../code/components/form/date/preview.vue
:::

## Examples

::: example Basic || A basic date input.
example=../../code/components/form/date/basic.vue
:::

::: example Limited || A date input with a minimal and maximum value.
example=../../code/components/form/date/limited.vue
:::

::: example Disabled || A disabled date input.
example=../../code/components/form/date/disabled.vue
:::

::: example Invalid || A date input with an error message.
example=../../code/components/form/date/invalid.vue
:::

## Used components

* [Flyout](../flyout)
* [Date picker](../date-picker)
* [Form](../form)
  * [Input](./input)
  * [Input group](./input/group)
* [Button](../button)
  * [Secondary](../button/secondary)

---

---
url: 'https://flux-ui.dev/components/date-picker.md'
---

# Date picker

The date picker enables seamless date selection with navigable views for months and years, a detailed date grid, smooth visual transitions, boundary validation, and a focus on accessibility for an intuitive user experience.

::: render
render=../code/components/date-picker/preview.vue
:::

## Examples

::: example Single || A single date can be selected here.
example=../code/components/date-picker/single.vue
:::

::: example Range || A date range can be selected here.
example=../code/components/date-picker/range.vue
:::

::: example Week || A week can be selected here.
example=../code/components/date-picker/week.vue
:::

::: example Month || A month can be selected here.
example=../code/components/date-picker/month.vue
:::

## Used components

* [Button](./button)
  * [Secondary](./button/secondary)

---

---
url: 'https://flux-ui.dev/components/form/date-range.md'
---

# Date range

A date range picker that allows users to select a start and end date. It displays a formatted label of the selected date range and opens a calendar flyout when clicked. The `v-model` value is a tuple of two Luxon `DateTime` objects or `null`.

::: render
render=../../code/components/form/date-range/preview.vue
:::

## Examples

::: example Range || Free selection of a start and end date. This is the default mode.
example=../../code/components/form/date-range/basic.vue
:::

::: example Week || Selects an entire week at once by setting `range-mode` to `week`.
example=../../code/components/form/date-range/week.vue
:::

::: example Month || Selects an entire month at once by setting `range-mode` to `month`.
example=../../code/components/form/date-range/month.vue
:::

## Used components

* [Button](../button)
  * [Secondary](../button/secondary)
* [Date picker](../date-picker)
* [Flyout](../flyout)
* [Form](.)
  * [Input group](./input/group)

---

---
url: 'https://flux-ui.dev/components/form/date-time.md'
---

# Date time

An input element designed for selecting dates and times, incorporating a dropdown interface with a calendar for ease of use. Provides support for configurable options such as minimum and maximum date ranges.

::: render
render=../../code/components/form/date-time/preview.vue
:::

::: info
When the field is still empty, picking a date or time starts from midnight rather than the current wall-clock time, so only the part you actually entered is applied. The complementary part defaults to `00:00` (or today's date) until you set it.
:::

## Examples

::: example Basic || A basic date time input.
example=../../code/components/form/date-time/basic.vue
:::

::: example Hour only || A date time input where the time is always rounded to whole hours.
example=../../code/components/form/date-time/hour-only.vue
:::

::: example Limited || A date time input constrained by a minimum and maximum value.
example=../../code/components/form/date-time/limited.vue
:::

::: example Disabled || A disabled date time input.
example=../../code/components/form/date-time/disabled.vue
:::

::: example Invalid || A date time input with an error message.
example=../../code/components/form/date-time/invalid.vue
:::

## Used components

* [Flyout](../flyout)
* [Date picker](../date-picker)
* [Form](../form)
  * [Input](./input)
  * [Input group](./input/group)
* [Button](../button)
  * [Secondary](../button/secondary)
* [Layout](../layout)
  * [Flex](../layout/flex/)

---

---
url: 'https://flux-ui.dev/components/drop-zone.md'
---

# Drop zone

The drop zone lets users drop files onto its contents, typically for file uploads. It can be combined with other components, such as the [Gallery](./gallery), to build richer upload experiences.

::: render
render=../code/components/drop-zone/preview.vue
:::

::: tip Accept handling and rejected files
The `accept` filter is enforced on both dropped and picked files, not just the native file picker. Files that do not match `accept` are emitted through the `reject` event instead of `select` / `select-multiple`. When `is-multiple` is off and several files are provided, only the first match is selected and the remaining files are reported as rejected too. Listen to `reject` to give the user feedback about what was skipped.
:::

## Examples

::: example Basic || A basic drop zone example.
example=../code/components/drop-zone/basic.vue
:::

::: example Avatar || A circular drop zone wrapped around an avatar, useful for profile picture uploads.
example=../code/components/drop-zone/avatar.vue
:::

## Used components

* [Spinner](./spinner)

---

---
url: 'https://flux-ui.dev/components/form/fader.md'
---

# Fader

The fader is a compact, inline slider that shows its `label` on the left and the current value on the right, right inside the track. The whole row acts as the track: a fill grows from the left up to the value, with a thin thumb marking the position. Set `min`, `max` and `step` to define the range, and provide a `formatter` to control how the value is displayed.

::: render
render=../../../code/components/form/fader/preview.vue
:::

::: tip
Clicking anywhere on the fader jumps to that position, and dragging keeps tracking the pointer even when it leaves the fader. The value can also be changed with the arrow keys, `Page Up` / `Page Down` for larger steps, and `Home` / `End` to jump to the minimum or maximum. Faders with a small number of steps snap to detents and show their marks automatically.
:::

## Examples

::: example Basic || A basic fader from 0 to 100.
example=../../../code/components/form/fader/basic.vue
:::

::: example Vertical || A vertical fader: a slim column with rotated text, 210px tall by default and resizable with CSS.
example=../../../code/components/form/fader/vertical.vue
:::

::: example Vertical with icons || Vertical faders with a leading icon on top and a trailing icon at the bottom.
example=../../../code/components/form/fader/vertical-icons.vue
:::

::: example Steps || A stepped fader that snaps to detents and shows their marks automatically.
example=../../../code/components/form/fader/ticks.vue
:::

::: example Colors || A fader per color; the color only tints the value, the track stays neutral.
example=../../../code/components/form/fader/colors.vue
:::

::: example Icons || A fader with a leading icon before the label and a trailing icon after the value.
example=../../../code/components/form/fader/icons.vue
:::

::: example Custom formatter || A fader with a custom formatter.
example=../../../code/components/form/fader/formatter.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/fader/ranged.md'
---

# Range fader

The range fader lets users select a range of values between a lower and an upper bound. It works like the [Fader](../fader/), but with two thumbs, one for each end of the range, and shows both values on the right.

::: render
render=../../../code/components/form/fader/ranged/preview.vue
:::

::: tip
Clicking anywhere on the track moves the thumb closest to the pointer, so the range can be adjusted without grabbing a handle first. Tab between the two thumbs and use the arrow keys to fine-tune each bound. Use `min-distance` to keep a minimum gap between the two thumbs.
:::

## Examples

::: example Basic || A basic range fader from 0 to 100.
example=../../../code/components/form/fader/ranged/basic.vue
:::

::: example Vertical || A vertical range fader: a slim column with rotated text, 210px tall by default and resizable with CSS.
example=../../../code/components/form/fader/ranged/vertical.vue
:::

::: example Minimum distance || A range fader that keeps at least 20 units between both thumbs.
example=../../../code/components/form/fader/ranged/min-distance.vue
:::

::: example Steps || A stepped range fader that snaps to detents and shows their marks automatically.
example=../../../code/components/form/fader/ranged/ticks.vue
:::

::: example Colors || A range fader per color; the color only tints the value, the track stays neutral.
example=../../../code/components/form/fader/ranged/colors.vue
:::

::: example Custom formatter || A range fader with a custom formatter.
example=../../../code/components/form/fader/ranged/formatter.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/field.md'
---

# Field

The form field component is a base component that wraps a form control, such as [FluxFormInput](../input/index.md). It provides a label, error and hint. Fields can also be marked optional.

By default a field wraps a **single** control and associates its label with that control through `<label for>`. When a field hosts a **group** of controls (multiple [checkboxes](../checkbox), a [Checkbox group](../checkbox), or a [Radio group](../radio/group)), set `as="group"`. The label is then rendered as a group label (`role="group"` + `aria-labelledby`), which keeps the markup accessible and avoids the duplicate `id`s that a single shared `for` would create.

::: render
render=../../../code/components/form/field/preview.vue
:::

::: info Accessibility
The `error` and `hint` messages are linked to the control through `aria-describedby`, so assistive technology announces them when the control is focused. The error message also carries `role="alert"` so it is announced as soon as it appears.
:::

## Examples

::: example Basic || A basic form field.
example=../../../code/components/form/field/basic.vue
:::

::: example Optional || An optional form field.
example=../../../code/components/form/field/optional.vue
:::

::: example Hint and error || A form field with a hint and error.
example=../../../code/components/form/field/error-hint.vue
:::

::: example Multiple hints or errors || A form field with multiple hints and errors.
example=../../../code/components/form/field/error-hint-multiple.vue
:::

::: example Group || A field hosting a group of controls with `as="group"`.
example=../../../code/components/form/field/group.vue
:::

## Used components

* [Form](../../form)
  * [Addition](./addition)

---

---
url: 'https://flux-ui.dev/components/form/field/addition.md'
---

# Field addition

The field addition is used to display contextual text beneath an input field, providing either a hint or an error message. Hints offer subtle guidance or clarification to help users input information correctly, while errors appear when validation fails, clearly indicating what needs to be fixed.

::: render
render=../../../code/components/form/field/addition/preview.vue
:::

::: tip
This component is best used within a [Form field](index.md).
:::

## Examples

::: example Hint || A form field addition that displays a hint.
example=../../../code/components/form/field/addition/hint.vue
:::

::: example Error || A form field addition that displays an error.
example=../../../code/components/form/field/addition/error.vue
:::

## Used components

* [Icon](../../icon)

---

---
url: 'https://flux-ui.dev/components/form.md'
---

# Form

Form layout components arrange inputs, selects, checkboxes and other controls into a clear, consistent structure, making forms easier to scan and complete.

::: render
render=../../code/components/form/preview.vue
:::

::: info
The form renders with `novalidate`, so the browser's native bubble validation is suppressed. Flux components surface validation through their own `error` prop and the [Form field](./field/) instead.
:::

## Examples

::: example Login
example=../../code/components/form/login.vue
:::

::: example Contact || A contact form combining a `FluxFormGrid`, single fields, and a textarea, all wrapped inside a single `FluxForm`.
example=../../code/components/form/contact.vue
:::

## Used components

* [Disabled](../disabled)

---

---
url: 'https://flux-ui.dev/components/form/grid.md'
---

# Form grid

The form grid arranges fields in a configurable number of columns. It is useful when you want to display multiple inputs side by side, for example in dense forms or settings panels.

::: render
render=../../code/components/form/grid/preview.vue
:::

::: tip
This component is best used within a [Form](../form).
:::

## Examples

::: example Three columns || A form grid with three columns for short related fields like an address.
example=../../code/components/form/grid/three-columns.vue
:::

---

---
url: 'https://flux-ui.dev/components/inline-edit.md'
---

# Inline edit

The inline edit displays a value that turns into an input when clicked, letting users edit it in place. It is well suited for editable fields in detail panels and tables. Editing commits on Enter (or ⌘/Ctrl + Enter in multi-line mode) and reverts on Escape.

Cancelling (through Escape or the cancel control) takes precedence over `save-on-blur`, so the draft is never persisted when the user explicitly cancels, even though leaving the field moves focus. After editing closes, focus stays within the component rather than dropping to the document body.

::: render
render=../code/components/inline-edit/preview.vue
:::

## Examples

::: example Basic || A basic inline edit field.
example=../code/components/inline-edit/basic.vue
:::

::: example Multi-line || An inline edit field that edits with a text area.
example=../code/components/inline-edit/multiline.vue
:::

## Used components

* [Button](./button/)
* [Input](./form/input/)
* [Text area](./form/text-area)

---

---
url: 'https://flux-ui.dev/components/form/input.md'
---

# Input

The input is a single-line text field. It accepts various data types, set through the `type` prop.

::: render
render=../../../code/components/form/input/preview.vue
:::

## Examples

::: example Basic || A basic form input.
example=../../../code/components/form/input/basic.vue
:::

::: example Icon || Form input with an icon.
example=../../../code/components/form/input/icon.vue
:::

::: example Password || A password form input. The visibility toggle is a real button with an accessible label and `aria-pressed` state, so it is reachable and operable by keyboard.
example=../../../code/components/form/input/password.vue
:::

::: example Pattern || A form input with a pattern.
example=../../../code/components/form/input/pattern.vue
:::

## Used components

* [Icon](../../icon)

---

---
url: 'https://flux-ui.dev/components/form/input/addition.md'
---

# Input addition

The input addition is a small element placed visually inside a form input, typically used to display a unit, currency symbol, or icon. It can be placed before or after the input when combined with an [Input group](./group).

::: render
render=../../../code/components/form/input/addition/preview.vue
:::

::: tip
This component is best used within an [Input group](./group).
:::

## Snippet

::: code-group

```vue \[FluxFormInputAddition.vue]
<template>
    <Preview>
        <FluxFlex
            direction="vertical"
            :gap="18"
            style="width: min(100%, 320px)">
            <FluxFormField label="Price">
                <FluxFormInputGroup>
                    <FluxFormInputAddition label="€"/>
                    <FluxFormInput
                        type="number"
                        placeholder="0.00"/>
                </FluxFormInputGroup>
            </FluxFormField>

            <FluxFormField label="Domain">
                <FluxFormInputGroup>
                    <FluxFormInput placeholder="example"/>
                    <FluxFormInputAddition label=".com"/>
                </FluxFormInputGroup>
            </FluxFormField>
        </FluxFlex>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxFlex, FluxFormField, FluxFormInput, FluxFormInputAddition, FluxFormInputGroup } from '@flux-ui/components';
</script>

```

:::

## Used components

* [Icon](../../icon)

---

---
url: 'https://flux-ui.dev/components/form/input/group.md'
---

# Input group

The input group combines an input field with an additional element, such as a button to create a single, cohesive control. This layout is useful for actions or context directly related to the input.

::: render
render=../../../code/components/form/input/group/preview.vue
:::

## Examples

::: example Basic || A basic and simple input group.
example=../../../code/components/form/input/group/basic.vue
:::

::: example Labelled || An accessible group label via `aria-label`; the group only takes `role="group"` when labelled.
example=../../../code/components/form/input/group/labelled.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/number-input.md'
---

# Number input

A number input is a form-integrated numeric field with stepper buttons. Users can type a value directly, use the up and down buttons, or the arrow keys to step by the configured `step`. The value is clamped to `min` and `max` when stepping and on blur, and on blur it is additionally snapped to the nearest `step`. It is bound through `v-model` as a `number` (or `null` when empty).

::: render
render=../../code/components/form/number-input/preview.vue
:::

::: tip
For a standalone amount picker outside of a form (such as a quantity in a shopping cart), consider the [Quantity selector](./quantity-selector) instead.
:::

## Examples

::: example Basic || A number input inside a form field.
example=../../code/components/form/number-input/basic.vue
:::

::: example Range and step || A number input bound to a range with a custom step.
example=../../code/components/form/number-input/range.vue
:::

::: example Step snapping || Typed values snap to the nearest valid step (from `min`) and clamp on blur.
example=../../code/components/form/number-input/snapping.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/form/pin-input.md'
---

# PIN input

The PIN input renders a fixed number of single-character boxes for entering a PIN-like value, such as a TOTP code from an authenticator app.

::: render
render=../../code/components/form/pin-input/preview.vue
:::

::: tip
Pasting a code fills the fields automatically. Non-digit characters are stripped and longer values are truncated to `max-length`, so a partial or padded paste still lands the cursor on the last filled field.
:::

## Examples

::: example Basic || A basic pin input.
example=../../code/components/form/pin-input/basic.vue
:::

::: example Toggle || A pin input where you can toggle the private state.
example=../../code/components/form/pin-input/toggle.vue
:::

::: example Custom || A pin input with a different amount of numbers.
example=../../code/components/form/pin-input/longer.vue
:::

::: example Accessible label || An accessible label for screen readers; pasted codes are truncated to the length and partial pastes are supported.
example=../../code/components/form/pin-input/accessible.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/quantity-selector.md'
---

# Quantity selector

A quantity selector can be used when users need to select an amount of something. For example, Within a shop, a user is able to select how many of a certain product they want to buy.

::: render
render=../../code/components/form/quantity-selector/preview.vue
:::

## Examples

::: example Basic || A basic quantity selector.
example=../../code/components/form/quantity-selector/basic.vue
:::

::: example Step || A quantity selector with steps.
example=../../code/components/form/quantity-selector/step.vue
:::

::: example Fractional step || A quantity selector with a decimal step; values snap to the step.
example=../../code/components/form/quantity-selector/fractional.vue
:::

::: example Disabled || A disabled quantity selector.
example=../../code/components/form/quantity-selector/disabled.vue
:::

## Used components

* [Button](../button)
  * [Secondary](../button/secondary)
  * [Group](../button/group)

---

---
url: 'https://flux-ui.dev/components/form/radio.md'
---

# Radio

A radio represents a single option within a [Radio group](./group). It carries a `value`; selecting it updates the group's `v-model` to that value. A radio can render a plain label or fully custom content through its default slot.

::: render
render=../../../code/components/form/radio/preview.vue
:::

::: warning
This component is best used within a [Radio group](./group).
:::

## Examples

::: example Custom content || A radio with custom label content.
example=../../../code/components/form/radio/content.vue
:::

::: example Sub-label || A radio with a secondary line of text below the label.
example=../../../code/components/form/radio/sub-label.vue
:::

::: example Disabled option || A radio group where a single option is disabled.
example=../../../code/components/form/radio/disabled-option.vue
:::

::: example Label only || A minimal radio group using just the `label` prop.
example=../../../code/components/form/radio/label-only.vue
:::

## Used components

* [Radio group](./group)

---

---
url: 'https://flux-ui.dev/components/form/radio/group.md'
---

# Radio group

A radio group lets users pick a single option from a small, fully visible set of choices. Each choice is a [Radio](./), and the selected one is bound through `v-model` and reflects the `value` of the active radio.

::: render
render=../../../code/components/form/radio/group/preview.vue
:::

::: tip
Reach for a radio group when every option should stay visible at a glance. When the list is long or space is tight, prefer a [Select](../select/) instead. When wrapped in a `required` [Form field](../field/), the group (`role="radiogroup"`) automatically receives `aria-required`, and setting `error` exposes `aria-invalid`.
:::

## Examples

::: example Basic || A radio group inside a form field.
example=../../../code/components/form/radio/group/basic.vue
:::

::: example Inline || A radio group laid out horizontally.
example=../../../code/components/form/radio/group/inline.vue
:::

::: example Disabled item || A radio group with a single disabled option.
example=../../../code/components/form/radio/group/disabled.vue
:::

::: example Tile || Card-style options through [Radio tile](./tile), with an icon and description.
example=../../../code/components/form/radio/tile/stacked.vue
:::

::: example Mixed || Combine tiles with a regular radio for a less prominent option.
example=../../../code/components/form/radio/tile/mixed.vue
:::

::: example Connected || Join the tiles into a single block with is-connected.
example=../../../code/components/form/radio/tile/connected.vue
:::

## Used components

* [Radio](./)
* [Radio tile](./tile)

---

---
url: 'https://flux-ui.dev/components/form/radio/tile.md'
---

# Radio tile

A radio tile is a card-style [Radio](./) for prominent, fully visible choices. Each option carries an icon, a label and a short description. Place the tiles inside a [Radio group](./group) just like regular radios; the group handles selection and state.

::: render
render=../../../code/components/form/radio/tile/preview.vue
:::

::: tip
Tiles fill the group's width when stacked. Add `is-inline` to the [Radio group](./group) to lay them out in equal columns, best for two or three options. You can mix tiles and regular [Radios](./) in the same group when one option is less prominent.
:::

## Examples

::: example Stacked || Card-style radios stacked at full width.
example=../../../code/components/form/radio/tile/stacked.vue
:::

::: example Inline || Tiles laid out in equal columns with is-inline.
example=../../../code/components/form/radio/tile/inline.vue
:::

::: example Without description || Compact tiles with just an icon and label, no sub-label.
example=../../../code/components/form/radio/tile/without-description.vue
:::

::: example Shipping method || A real-world group with a description and price per option.
example=../../../code/components/form/radio/tile/shipping.vue
:::

## Used components

* [Icon](../../icon)
* [Radio group](./group)

---

---
url: 'https://flux-ui.dev/components/form/rating.md'
---

# Rating

The rating lets a user pick a score by selecting stars. It supports half-step selection, a read-only mode for displaying an existing rating, and full keyboard control: arrow keys adjust the value, number keys jump to a score, Home/End select the extremes, and Delete/Backspace clear it when `clearable`. The model value is a number, or `null` when no rating is set.

::: render
render=../../code/components/form/rating/preview.vue
:::

## Examples

::: example Basic || A basic rating.
example=../../code/components/form/rating/basic.vue
:::

::: example Half steps || A rating that allows half steps.
example=../../code/components/form/rating/half-steps.vue
:::

::: example Read-only || A read-only rating for displaying a value.
example=../../code/components/form/rating/readonly.vue
:::

::: example Clearable || A clearable rating; keyboard users can press Delete or Backspace to reset it.
example=../../code/components/form/rating/clearable.vue
:::

::: example Custom count || A rating out of ten stars using `count`.
example=../../code/components/form/rating/count.vue
:::

::: example Custom icon || A rating using a different icon.
example=../../code/components/form/rating/icon.vue
:::

::: example Custom size || Larger stars using the `size` prop.
example=../../code/components/form/rating/size.vue
:::

::: example Disabled || A disabled rating showing a fixed value.
example=../../code/components/form/rating/disabled.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/form/row.md'
---

# Row

The row places fields in a horizontal stack. It's ideal for grouping related inputs side-by-side, such as first and last name fields. This layout keeps the form compact and visually aligned while maintaining a clear relationship between the fields.

::: render
render=../../code/components/form/row/preview.vue
:::

## Examples

::: example Basic || A basic form row.
example=../../code/components/form/row/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/section.md'
---

# Form section

The form section groups related fields under a shared title. It helps divide longer forms into logical blocks, making them easier to scan and complete.

::: render
render=../../code/components/form/section/preview.vue
:::

::: info Accessibility
The section is exposed as a labelled group (`role="group"` + `aria-labelledby`) so assistive technology announces the title as the name of the contained fields. Use `heading-level` to keep the rendered heading (`<h1>`–`<h6>`) consistent with the surrounding document outline.
:::

::: tip
This component is best used within a [Form](../form).
:::

## Examples

::: example Heading level || Render the section title as a real heading (h1–h6) instead of the default h3.
example=../../code/components/form/section/heading-level.vue
:::

## Snippet

::: code-group

```vue \[FluxFormSection.vue]
<template>
    <Preview>
        <FluxPane style="max-width: 390px">
            <FluxForm>
                <FluxPaneBody>
                    <FluxFormColumn>
                        <FluxFormSection title="Personal information">
                            <FluxFormColumn>
                                <FluxFormField label="Full name">
                                    <FluxFormInput placeholder="E.g. John Doe"/>
                                </FluxFormField>

                                <FluxFormField label="Email address">
                                    <FluxFormInput
                                        type="email"
                                        placeholder="E.g. john@example.com"/>
                                </FluxFormField>
                            </FluxFormColumn>
                        </FluxFormSection>

                        <FluxFormSection title="Address">
                            <FluxFormColumn>
                                <FluxFormField label="Street">
                                    <FluxFormInput placeholder="E.g. Main Street 1"/>
                                </FluxFormField>

                                <FluxFormField label="City">
                                    <FluxFormInput placeholder="E.g. Amsterdam"/>
                                </FluxFormField>
                            </FluxFormColumn>
                        </FluxFormSection>
                    </FluxFormColumn>
                </FluxPaneBody>
            </FluxForm>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxForm, FluxFormColumn, FluxFormField, FluxFormInput, FluxFormSection, FluxPane, FluxPaneBody } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/form/select.md'
---

# Select

The select lets users choose one or more options from a list. Enable `is-searchable` to filter long lists and `is-multiple` to allow several values at once. Options can be grouped.

::: render
render=../../../code/components/form/select/preview.vue
:::

::: info Accessibility
The control is exposed as a `role="combobox"` and tracks the highlighted option through `aria-activedescendant` and `aria-controls` while the popup is open. When `name` is set, the selected values are mirrored into a hidden input so the select participates in native form submission.
:::

## Examples

::: example Basic || A basic form select.
example=../../../code/components/form/select/basic.vue
:::

::: example Searchable || A form select in where you can search for the items.
example=../../../code/components/form/select/searchable.vue
:::

::: example Multiple || A form select in where you can select multiple options.
example=../../../code/components/form/select/multiple.vue
:::

::: example Read-only || A read-only select that shows its value but cannot be opened or changed.
example=../../../code/components/form/select/readonly.vue
:::

## Used components

* [Form](../../form)
  * [Input](../input)
* [Menu](../../menu)
  * [Item](../../menu/item)
  * [Group](../../menu/group)
  * [SubHeader](../../menu/sub-header)
* [Icon](../../icon)
* [Spinner](../../spinner)
* [Tag](../../tag)

---

---
url: 'https://flux-ui.dev/components/form/select/async.md'
---

# Select async

The async select fetches its options on demand instead of receiving them up front. Provide `fetch-relevant`, `fetch-search` and `fetch-options` to load the initial set, respond to the search query, and resolve selected values by their id. Enable `is-multiple` to allow several values at once.

::: render
render=../../../code/components/form/select/async/preview.vue
:::

::: tip
When the popup opens with an active search query, `fetch-search` is called with that query; otherwise `fetch-relevant` is used. This keeps a previously typed search reflected in the initial result set.
:::

## Examples

::: example Basic || A basic asynchronous form select.
example=../../../code/components/form/select/async/basic.vue
:::

::: example Multiple || An asynchronous form select in where you can select multiple options.
example=../../../code/components/form/select/async/multiple.vue
:::

## Used components

* [Form](../../form)
  * [Input](../input)
* [Menu](../../menu)
  * [Item](../../menu/item)
  * [Group](../../menu/group)
  * [SubHeader](../../menu/sub-header)
* [Icon](../../icon)
* [Spinner](../../spinner)
* [Tag](../../tag)

---

---
url: 'https://flux-ui.dev/components/form/slider.md'
---

# Slider

The slider lets users pick a single value from a range by dragging a thumb. Set `min`, `max` and `step` to define the range, and provide a `formatter` to control how the value is displayed.

::: render
render=../../../code/components/form/slider/preview.vue
:::

::: tip
Clicking anywhere on the track jumps the thumb to that position, and dragging keeps tracking the pointer even when it leaves the slider. The thumb can also be moved with the arrow keys for keyboard users.
:::

## Examples

::: example Basic || A basic slider from 0 to 100.
example=../../../code/components/form/slider/basic.vue
:::

::: example Vertical || A vertical slider. It defaults to 210px tall and can be resized with CSS.
example=../../../code/components/form/slider/vertical.vue
:::

::: example Ticks || A slider where the ticks are visible.
example=../../../code/components/form/slider/ticks.vue
:::

::: example Custom formatter || A slider with a custom formatter.
example=../../../code/components/form/slider/formatter.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/slider/ranged.md'
---

# Range slider

The range slider lets users select a range of values between a lower and an upper bound. It works like the [Slider](../slider/), but with two thumbs, one for each end of the range.

::: render
render=../../../code/components/form/slider/ranged/preview.vue
:::

::: tip
Clicking anywhere on the track moves the thumb closest to the pointer, so the range can be adjusted without grabbing a handle first. Use `min-distance` to keep a minimum gap between the two thumbs.
:::

## Examples

::: example Basic || A basic range slider from 0 to 100.
example=../../../code/components/form/slider/ranged/basic.vue
:::

::: example Vertical || A vertical range slider. It defaults to 210px tall and can be resized with CSS.
example=../../../code/components/form/slider/ranged/vertical.vue
:::

::: example Minimum distance || A range slider that keeps at least 20 units between both thumbs.
example=../../../code/components/form/slider/ranged/min-distance.vue
:::

::: example Ticks || A range slider where the ticks are visible.
example=../../../code/components/form/slider/ranged/ticks.vue
:::

::: example Custom formatter || A range slider with a custom formatter.
example=../../../code/components/form/slider/ranged/formatter.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/step.md'
---

# Form step

The form step breaks a longer form into numbered stages. Each step is automatically numbered and pairs a required title with an optional subtitle, followed by its own content at full width.

::: render
render=../../code/components/form/step/preview.vue
:::

::: info Accessibility
Every step is exposed as a labelled group (`role="group"` + `aria-labelledby`) so assistive technology announces the title as the name of its content. The number badge is decorative (`aria-hidden`).
:::

::: tip
This component is best used within a [Form](../form), which resets the numbering. Steps are numbered automatically with a CSS counter.
:::

## Examples

::: example End slot || Add trailing content, like a status badge, to the step header through the `end` slot.
example=../../code/components/form/step/end-slot.vue
:::

## Snippet

::: code-group

```vue \[FluxFormStep.vue]
<template>
    <Preview>
        <FluxPane style="max-width: 480px">
            <FluxPaneBody>
                <FluxForm>
                    <FluxFormStep
                        title="Choose how to connect"
                        subtitle="Bring an existing subscription or supply credentials from a provider.">
                        <FluxFormRadioGroup
                            v-model="method"
                            is-connected>
                            <FluxFormRadioTile
                                value="subscription"
                                icon="sparkles"
                                label="Use an existing subscription"
                                sub-label="Bring a plan you already pay for."/>

                            <FluxFormRadioTile
                                value="credentials"
                                icon="user-key"
                                label="Provider credentials"
                                sub-label="Supply an API key to power your agents."/>
                        </FluxFormRadioGroup>
                    </FluxFormStep>

                    <FluxFormStep
                        title="Name your workspace"
                        subtitle="Pick a name your team will recognise.">
                        <FluxFormField label="Workspace name">
                            <FluxFormInput placeholder="E.g. Acme Inc."/>
                        </FluxFormField>
                    </FluxFormStep>

                    <FluxFormStep
                        title="Link an agent"
                        subtitle="Pick which agent you want to link, then finish authenticating.">
                        <FluxFormField label="Agent">
                            <FluxFormSelect
                                v-model="agent"
                                :options="agents"/>
                        </FluxFormField>
                    </FluxFormStep>
                </FluxForm>
            </FluxPaneBody>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxForm, FluxFormField, FluxFormInput, FluxFormRadioGroup, FluxFormRadioTile, FluxFormSelect, FluxFormStep, FluxPane, FluxPaneBody } from '@flux-ui/components';
    import { ref } from 'vue';

    const method = ref('subscription');
    const agent = ref('claude-code');

    const agents = [
        {label: 'Claude Code', value: 'claude-code'},
        {label: 'Codex CLI', value: 'codex-cli'},
        {label: 'Custom agent', value: 'custom'}
    ];
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/form/tags-input.md'
---

# Tags input

The tags input lets users build a list of tags by typing and committing each value, for example to assign keywords or labels. Values are committed on Enter or a comma (configurable), pasted text is split into multiple tags, and Backspace on an empty input removes the last tag. When `suggestions` are provided, a filtered dropdown is shown while typing.

::: info
Picking a suggestion stores its `value` (as a string) when one is set, falling back to the `label` otherwise. This keeps the bound `v-model` made up of stable identifiers rather than display text. The input is exposed as a `role="combobox"` and links the highlighted suggestion through `aria-activedescendant`.
:::

::: render
render=../../code/components/form/tags-input/preview.vue
:::

## Examples

::: example Basic || A basic tags input.
example=../../code/components/form/tags-input/basic.vue
:::

::: example Suggestions || A tags input with suggestions.
example=../../code/components/form/tags-input/suggestions.vue
:::

::: example Tag color || Render the tags in a chosen color with `tag-color`.
example=../../code/components/form/tags-input/tag-color.vue
:::

::: example Validation || Only accept valid entries by passing a `validate` function.
example=../../code/components/form/tags-input/validation.vue
:::

::: example Custom delimiters || Commit tags on a space or comma in addition to Enter.
example=../../code/components/form/tags-input/delimiters.vue
:::

::: example Disabled || A disabled tags input with existing tags.
example=../../code/components/form/tags-input/disabled.vue
:::

## Used components

* [Tag](../tag)

---

---
url: 'https://flux-ui.dev/components/form/text-area.md'
---

# Text area

A form text area is a text field that may have multiple lines of text. It is used for longer text and can be used within a contact form to ask for a question.

::: render
render=../../code/components/form/text-area/preview.vue
:::

## Examples

::: example Basic || A basic text area.
example=../../code/components/form/text-area/basic.vue
:::

::: example Multiple rows || A text area with multiple rows
example=../../code/components/form/text-area/rows.vue
:::

::: example Max length || A text area capped with `max-length`.
example=../../code/components/form/text-area/max-length.vue
:::

::: example Disabled || A disabled text area.
example=../../code/components/form/text-area/disabled.vue
:::

::: example Invalid || A text area with an error message.
example=../../code/components/form/text-area/invalid.vue
:::

::: example Read-only || A read-only text area showing prefilled content.
example=../../code/components/form/text-area/readonly.vue
:::

---

---
url: 'https://flux-ui.dev/components/form/time.md'
---

# Time

::: warning
This component is coming soon!
:::

---

---
url: 'https://flux-ui.dev/components/form/time-zone-picker.md'
---

# Time zone picker

The time zone picker lets users choose a time zone from a comprehensive list, so date and time information stays accurate for their location.

::: render
render=../../code/components/form/time-zone-picker/preview.vue
:::

## Examples

::: example Basic || A basic time zone picker.
example=../../code/components/form/time-zone-picker/basic.vue
:::

::: example Preselected || A time zone picker with a value already selected.
example=../../code/components/form/time-zone-picker/preselected.vue
:::

::: example Disabled || A disabled time zone picker.
example=../../code/components/form/time-zone-picker/disabled.vue
:::

::: example Invalid || A time zone picker with an error message.
example=../../code/components/form/time-zone-picker/invalid.vue
:::

## Used components

* [Form](../form)
  * [Select](./select)

---

---
url: 'https://flux-ui.dev/components/form/toggle.md'
---

# Toggle

The toggle switches between two states, on and off. Use it in settings and option panels to enable or disable a feature.

::: render
render=../../code/components/form/toggle/preview.vue
:::

::: info Accessibility
The toggle is exposed as a native `role="switch"` checkbox. State and validation attributes (`aria-checked`, `aria-disabled`, `aria-readonly`, `aria-invalid`) sit on that control, and when wrapped in a required [Form field](./field/) it also receives `aria-required`.
:::

## Examples

::: example Basic || A basic toggle.
example=../../code/components/form/toggle/basic.vue
:::

::: example Icons || A toggle with icons for both the on and off state.
example=../../code/components/form/toggle/icon.vue
:::

::: example Form || A toggle used in a form.
example=../../code/components/form/toggle/form.vue
:::

::: example Disabled || A disabled toggle in both the off and on state.
example=../../code/components/form/toggle/disabled.vue
:::

::: example Invalid || A toggle with an error message.
example=../../code/components/form/toggle/invalid.vue
:::

::: example Read-only || A read-only toggle that cannot be changed.
example=../../code/components/form/toggle/readonly.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/form/tree-view-select.md'
---

# Tree view select

This is a form select element that displays options in a hierarchical tree structure. It supports expanding and collapsing branches, single and multiple selection, an optional search input for filtering, and cascading selection where picking a parent covers its whole subtree. Each selectable option carries a checkbox (multiple) or radio (single) showing whether it is selected. The tree is rendered with connecting lines to visualize the hierarchy. Every option ends its guide line with a marker of the same size: options with children render it as the expand toggle holding the chevron, leaf options as a plain circle. Markers can be colored per option or per depth level, using either a `FluxColor` name or any CSS/HEX color string.

::: render
render=../../code/components/form/tree-view-select/preview.vue
:::

::: info Accessibility
The trigger is exposed as a `role="combobox"` (`aria-haspopup="tree"`) and the option list as a `role="listbox"`. The highlighted node is tracked through `aria-activedescendant`, selectable nodes carry `role="option"` with `aria-selected`, and non-selectable group headers are marked `role="presentation"`. The option row itself stays the control: its checkbox or radio is a read-only indicator marked `aria-hidden`, so assistive tech announces the selection once, through `aria-selected`. When wrapped in a required [Form field](./field/) the trigger also receives `aria-required`.
:::

## Option object

Each entry in the `options` array (and nested `children` arrays) is a `FluxFormTreeViewSelectOption`:

## Keyboard navigation

## Examples

::: example Basic || A tree view select with per-level colors.
example=../../code/components/form/tree-view-select/basic.vue
:::

::: example Multiple || A tree view select that allows selecting multiple items across the tree.
example=../../code/components/form/tree-view-select/multiple.vue
:::

::: example Searchable || A tree view select with a search input. Matching nodes keep their place in the hierarchy: their ancestors stay visible and non-matching branches are pruned.
example=../../code/components/form/tree-view-select/searchable.vue
:::

::: example Non-selectable parents || Parent nodes can have `selectable: false` so they act as group headers. Only leaf nodes can be selected.
example=../../code/components/form/tree-view-select/non-selectable-parents.vue
:::

::: example Expanded depth || With `expanded-depth`, the popup opens with more than just its roots visible. Handy when the top level only groups the options that can actually be picked.
example=../../code/components/form/tree-view-select/expanded-depth.vue
:::

::: example Cascading || With `is-cascading`, selecting a parent covers its whole subtree. Its descendants are shown as checked and locked, while the model value keeps only the explicitly selected ids.
example=../../code/components/form/tree-view-select/cascading.vue
:::

::: example Disabled options || Options with `disabled: true` cannot be selected, but their branch can still be expanded.
example=../../code/components/form/tree-view-select/disabled-options.vue
:::

::: example Per-option colors || Coloring each option individually with `color`, instead of per depth level.
example=../../code/components/form/tree-view-select/per-option-colors.vue
:::

::: example Custom colors || Using HEX colors instead of FluxColor names for each level.
example=../../code/components/form/tree-view-select/custom-colors.vue
:::

## Used components

* [Form](../form)
  * [Checkbox](./checkbox)
  * [Input](./input)
  * [Radio](./radio)
* [Icon](../icon)
* [Tag](../tag)

---

---
url: 'https://flux-ui.dev/components/navigation.md'
---

# Navigation

The navigation components handle wayfinding and view-switching, so people can move around, change what they see and step through multi-stage flows.

---

---
url: 'https://flux-ui.dev/components/breadcrumb.md'
---

# Breadcrumb

A breadcrumb shows users where they are within a hierarchy and lets them navigate back to any ancestor. Each step is a [Breadcrumb item](./item) or a [Breadcrumb flyout](./flyout); a non-linked item represents the current page and is rendered as plain, non-interactive text with `aria-current="page"`. Separators are inserted automatically between steps.

Steps are not limited to a label and icon. An item can hold an [avatar](../avatar), a [badge](../badge) or a [tag](../tag) through its `leading` and `trailing` slots, and a [Breadcrumb flyout](./flyout) turns a step into a dropdown so users can switch to a sibling without leaving the trail.

::: render
render=../../code/components/breadcrumb/preview.vue
:::

## Examples

::: example Basic || A breadcrumb trail with links.
example=../../code/components/breadcrumb/basic.vue
:::

::: example With icons || An icon per step makes the trail easier to scan.
example=../../code/components/breadcrumb/icons.vue
:::

::: example Custom separator || The separator defaults to a chevron. Set `separator` to any icon, such as `slash-forward`, to change it.
example=../../code/components/breadcrumb/separator.vue
:::

::: example Collapse the middle || Set `collapse="middle"` to keep the first and last step visible and fold the rest into an overflow menu when the trail runs out of space. Collapsed [Breadcrumb flyout](./flyout) steps become nested submenus.
example=../../code/components/breadcrumb/collapse-middle.vue
:::

::: example Collapse from the start || Set `collapse="start"` to keep only the trailing steps visible and fold everything before them into an overflow menu.
example=../../code/components/breadcrumb/collapse-start.vue
:::

::: example Rich trail || Combine icons, an [avatar](../avatar), a [badge](../badge) and a [flyout](./flyout) switcher in a single trail.
example=../../code/components/breadcrumb/rich.vue
:::

::: tip
Collapsing measures the available width, so the breadcrumb needs a bounded container to fold. Place it in a layout that constrains its width (a header bar, a card) rather than an intrinsically sized wrapper.
:::

## Used components

* [Breadcrumb item](./item)
* [Breadcrumb flyout](./flyout)

---

---
url: 'https://flux-ui.dev/components/breadcrumb/item.md'
---

# Breadcrumb item

A breadcrumb item is a single step in a [Breadcrumb](../breadcrumb/) trail. Provide a `to` to render it as a router link, an `href` to render it as an external anchor, or neither to mark it as the current page, in which case it becomes plain text with `aria-current="page"`.

Beyond a `label` and `icon`, an item can render richer content through its `leading` and `trailing` slots — an [avatar](../avatar) for a person, a [badge](../badge) for a status, a [tag](../tag) for a label — or fully custom markup through the default slot. When the item is collapsed into an overflow menu, its `label`, `icon` and `leading` slot are shown as a menu entry.

::: render
render=../../code/components/breadcrumb/item/preview.vue
:::

::: warning
This component is best used within a [Breadcrumb](../breadcrumb/).
:::

## Examples

::: example Current page || Using `is-current` to mark a linked last item as the current page.
example=../../code/components/breadcrumb/item/current.vue
:::

::: example With icons || Add an `icon` to each item to make the trail easier to scan.
example=../../code/components/breadcrumb/item/icons.vue
:::

::: example With an avatar || Use the `leading` slot to render an [avatar](../avatar) for a person or organisation.
example=../../code/components/breadcrumb/item/avatar.vue
:::

::: example With a badge or tag || Use the `trailing` slot to annotate a step with a [badge](../badge) or [tag](../tag).
example=../../code/components/breadcrumb/item/badge.vue
:::

::: example Custom label || Use the default slot to render custom markup instead of the `label` prop.
example=../../code/components/breadcrumb/item/slot.vue
:::

## Used components

* [Icon](../icon)
* [Avatar](../avatar)
* [Badge](../badge)
* [Tag](../tag)

---

---
url: 'https://flux-ui.dev/components/breadcrumb/flyout.md'
---

# Breadcrumb flyout

A breadcrumb flyout is a step that opens a dropdown instead of navigating, letting users switch to a sibling in the middle of a [Breadcrumb](../breadcrumb/) trail — a different client, project or account — without leaving the current view. It renders a chevron to signal the dropdown and, when collapsed into an overflow menu, becomes a nested submenu.

Provide the menu entries in the default slot as [Menu item](../menu/item) components; the wrapping [Menu](../menu/) is added for you.

::: render
render=../../code/components/breadcrumb/flyout/preview.vue
:::

::: warning
This component is best used within a [Breadcrumb](../breadcrumb/).
:::

## Examples

::: example Path switcher || Group the sibling options, and add actions such as creating a new one below a separator.
example=../../code/components/breadcrumb/flyout/basic.vue
:::

::: example With an avatar || Use the `leading` slot to switch between people, showing an [avatar](../avatar) on the trigger.
example=../../code/components/breadcrumb/flyout/avatar.vue
:::

## Used components

* [Icon](../icon)
* [Menu](../menu/)
* [Menu item](../menu/item)
* [Avatar](../avatar)

---

---
url: 'https://flux-ui.dev/components/command-palette.md'
---

# Command Palette

A searchable command palette that provides quick access to navigation, actions, and entity search through a unified interface. It can optionally be opened with a global `⌘K` (Mac) or `Ctrl+K` (Windows/Linux) keyboard shortcut by setting the `has-keyboard-shortcut` prop.

Items are organized through sources, where each source represents a group of related items. Sources can optionally appear as horizontal tabs for scoped filtering. Items within a source can have sub-actions, which are shown after selecting the item.

The palette follows the ARIA combobox pattern: the search input owns focus and points at the active result through `aria-activedescendant`, while the results render as a `listbox` of `option`s. The placeholder, empty-state text and accessible labels are localized through the Flux translation keys, so they follow the active locale automatically.

::: render
render=../code/components/command-palette/preview.vue
:::

## Sources

Sources are the core building blocks of the command palette. Each source has a `key`, `label`, and a list of `items`. Set `tab: true` to show the source as a tab in the tab bar. Use an empty `label` to hide the group header for a source.

```ts
type FluxCommandSource = {
    readonly key: string;
    readonly label: string;
    readonly icon?: FluxIconName;
    readonly tab?: boolean;
    readonly items: FluxCommandSourceItem[];
    readonly fetchSearch?: (query: string) => Promise<FluxCommandSourceItem[]>;
};
```

### Async sources

A source can provide a `fetchSearch` function to load items asynchronously when the user types a search query. Static `items` are shown when the search is empty, and `fetchSearch` results replace them when a query is entered. A centered spinner is displayed while the fetch is in progress.

## Items

Each item has a label, optional icon, and an `onActivate` callback. Items can also have a `command` string (e.g. `⌘D`) displayed as a keyboard shortcut badge, and `subActions` for secondary actions.

```ts
type FluxCommandSourceItem = {
    readonly id: string | number;
    readonly label: string;
    readonly subLabel?: string;
    readonly icon?: FluxIconName;
    readonly command?: string;
    readonly subActions?: FluxCommandSubAction[];
    readonly onActivate: () => void;
};
```

## Sub-actions

When an item has `subActions`, selecting it will show a sub-action menu instead of immediately activating the item. This is useful for entities that have multiple possible actions, such as "View", "Edit", or "Delete".

```ts
type FluxCommandSubAction = {
    readonly label: string;
    readonly icon?: FluxIconName;
    readonly onActivate: () => void;
};
```

## Examples

::: example Basic || A basic command palette with navigation and actions. Press `⌘K` or click the button to open.
example=../code/components/command-palette/basic.vue
:::

::: example Multiple sources || A command palette with multiple sources, tabs, and sub-actions.
example=../code/components/command-palette/with-sources.vue
:::

::: example Async || A command palette with an async source that fetches customers from a simulated API. Static items are shown initially, and search results are loaded dynamically.
example=../code/components/command-palette/async.vue
:::

::: example Complex || A full-featured command palette with navigation, entity search, standalone actions with sub-menus (Theme, Language, Export), recent items, and keyboard shortcut badges.
example=../code/components/command-palette/complex.vue
:::

---

---
url: 'https://flux-ui.dev/components/context-menu.md'
---

# Context menu

The Context menu component opens a menu at the cursor when the user right-clicks its content. It is positioned at the pointer, traps focus while open, supports arrow-key navigation through the menu, and closes on Escape, scroll, or an outside click.

Nest a [Menu flyout](./menu/flyout) inside the menu to add submenus. A prediction cone keeps a submenu open while the pointer moves diagonally towards it, and back out to its opener, even when the cursor briefly crosses another item. Set `debug-cone` to visualize that cone.

::: render
render=../code/components/context-menu/preview.vue
:::

## Examples

::: example Basic || A basic context menu.
example=../code/components/context-menu/basic.vue
:::

::: example With icons || A context menu with icons.
example=../code/components/context-menu/with-icons.vue
:::

::: example With submenus || Nest a Menu flyout to add a submenu that opens to the side.
example=../code/components/context-menu/with-submenu.vue
:::

::: example Deep submenus || Menu flyouts nest arbitrarily deep. The prediction cone guides the pointer into a submenu and back out to its opener across every level.
example=../code/components/context-menu/deep-submenus.vue
:::

::: example Nested formatting || A spreadsheet-style menu mixing several openers with two and three levels of nesting.
example=../code/components/context-menu/nested-formatting.vue
:::

::: example Real-world || A Finder-style menu with several submenu openers stacked under each other.
example=../code/components/context-menu/finder.vue
:::

::: example With color picker || Embed a full component with a Menu pane. The picker stays interactive while the menu is open.
example=../code/components/context-menu/with-color-picker.vue
:::

## Used components

* [Menu](./menu/)
* [Menu flyout](./menu/flyout)
* [Menu pane](./menu/pane)

---

---
url: 'https://flux-ui.dev/components/expandable.md'
---

# Expandable

This component provides a toggleable container for additional content. It consists of a header with a label and a body that holds the expandable content. When the header button is clicked, the body opens or closes to reveal or hide the content.

::: render
render=../../code/components/expandable/preview.vue
:::

::: tip
Multiple expandables can be grouped together using [Expandable Groups](./group).
:::

::: tip
The default header renders an accessible disclosure button with `aria-controls` and `aria-expanded` wired to the body region. When you provide a custom `header` slot, use the `headerId` and `contentId` slot props (also available on the `body` slot) to recreate this relationship on your own trigger element.
:::

## Examples

::: example Basic || The most basic form of an expandable.
example=../../code/components/expandable/basic.vue
:::

::: example Pane || Expandables work great with panes.
example=../../code/components/expandable/pane.vue
:::

::: example Custom || The header of an expandable can be overwritten with a slot called header. That slot is provided with an isOpen boolean and three functions to control the expandable.
example=../../code/components/expandable/custom.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/expandable/group.md'
---

# Expandable group

This component groups multiple [Expandables](../expandable) together, allowing for collective control of their open and close states. It provides mechanisms to register, unregister, and close all expandable items within the group. The first item in an uncontrolled group opens by default.

::: render
render=../../code/components/expandable/group/preview.vue
:::

## Examples

::: example Default || An expandable group makes sure that only one expandable is open at ant moment. It closes other expandables when one is opened.
example=../../code/components/expandable/group/default.vue
:::

::: example Pane || Grouped expandables are especially nice within a Pane.
example=../../code/components/expandable/group/pane.vue
:::

---

---
url: 'https://flux-ui.dev/components/menu.md'
---

# Menu

The menu is the base structure for building menus. It stacks its child elements vertically, which suits side navigations and flyout menus, and provides basic accessibility features.

Insert custom content freely; the menu handles keyboard navigation for you.

::: render
render=../../code/components/menu/container/preview.vue
:::

## Examples

::: example Basic || A basic menu that consists of a few items.
example=../../code/components/menu/container/basic.vue
:::

::: example Pane || Panes have first-class support for menus inside them. Place a menu directly inside a Pane to create a contained menu.
example=../../code/components/menu/container/pane.vue
:::

---

---
url: 'https://flux-ui.dev/components/menu/collapsible.md'
---

# Menu collapsible

A menu item that expands to reveal a nested group of sub-items. When Vue Router is available, the collapsible automatically opens if any direct sub-item's `to` or `href` matches the current route.

If a `to` or `href` is set on the collapsible itself, clicking the header navigates and opens the group in a single interaction. Without those props, clicking the header simply toggles the open state.

::: render
render=../../code/components/menu/collapsible/preview.vue
:::

## Examples

::: example Basic || A collapsible group without its own route. Click the header to toggle.
example=../../code/components/menu/collapsible/basic.vue
:::

::: example Navigate || A collapsible with a link on the header. Clicking navigates and opens.
example=../../code/components/menu/collapsible/navigate.vue
:::

::: example Controlled || Control the open state from outside with v-model:isOpened.
example=../../code/components/menu/collapsible/controlled.vue
:::

## Used components

* [Menu item](./item)
* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/menu/flyout.md'
---

# Menu flyout

A menu item that opens a submenu in a flyout next to it, rather than expanding inline like a [Collapsible](./collapsible). Use it inside any [Menu](./), such as a [Context menu](../context-menu), a dropdown, or a plain menu in a pane. Submenus may be nested arbitrarily deep.

The flyout opens on hover and on `ArrowRight`, `Enter` or click, and keeps itself within the browser window: when there is no room on the chosen side it flips to the opposite side and is clamped to the viewport.

A **prediction cone** keeps the submenu open while the pointer moves diagonally towards it, even when the cursor briefly passes over a sibling item, so reaching a submenu no longer requires a perfectly straight path. A matching return cone does the same on the way back, so heading from the submenu to its opener does not drop the submenu or activate the items in between. The cone can be visualized for debugging with the `debug-cone` prop on the surrounding [Context menu](../context-menu) or [Menu](./).

::: render
render=../../code/components/menu/flyout/preview.vue
:::

## Examples

::: example Basic || A menu item that opens a submenu on hover or with the keyboard.
example=../../code/components/menu/flyout/basic.vue
:::

::: example Nested || A submenu inside a submenu. There is no depth limit.
example=../../code/components/menu/flyout/nested.vue
:::

::: example Stacked || Several submenu openers under each other, like a Format menu in an editor.
example=../../code/components/menu/flyout/stacked.vue
:::

## Used components

* [Menu](./)
* [Menu item](./item)
* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/menu/group.md'
---

# Menu group

This component provides a container for grouping menu items, adjusting its orientation based on the `isHorizontal` prop. When set to horizontal, it applies a specific style; otherwise, it defaults to a vertical layout.

::: render
render=../../code/components/menu/group/preview.vue
:::

## Examples

::: example Vertical || Vertical groups are for combining menu items that share context.
example=../../code/components/menu/group/vertical.vue
:::

::: example Horizontal || Horizontal groups suit menu items that together form a single state, such as text alignment.
example=../../code/components/menu/group/horizontal.vue
:::

::: example Separated || Groups can also be separated using a separator.
example=../../code/components/menu/group/separated.vue
:::

::: example Both || Menu's can also have both horizontal and vertical groups in them.
example=../../code/components/menu/group/both.vue
:::

---

---
url: 'https://flux-ui.dev/components/menu/item.md'
---

# Menu item

This component is designed to be a flexible menu item that fits into a navigation or action menu. It leverages the properties of buttons and can display icons, images, and commands to suit various needs.

You can customize it with different states like active, selected, or highlighted, and it's capable of handling click events. Its versatility makes it easy to integrate into any menu structure, enhancing the user experience with well-defined actions and options.

::: render
render=../../code/components/menu/item/preview.vue
:::

## Examples

::: example Basic || A simple menu item with an icon.
example=../../code/components/menu/item/basic.vue
:::

::: example Selectable || Menu items can be selectable, mostly used within groups.
example=../../code/components/menu/item/selectable.vue
:::

::: example Persistent || Mark items with is-persistent to keep the surrounding menu open on click, useful for toggles and multi-select actions. Items without it (like Done) still close the menu.
example=../../code/components/menu/item/persistent.vue
:::

::: example Keybind || Each menu item can have a keybind (command).
example=../../code/components/menu/item/keybind.vue
:::

::: example Navigate || A menu item can also just contain an icon at the end.
example=../../code/components/menu/item/navigate.vue
:::

::: example Spinner || Loading states can also be applied to menu items to indicate that something is loading.
example=../../code/components/menu/item/spinner.vue
:::

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/menu/options.md'
---

# Menu options

This component provides a container for grouping menu items that behave like options, allowing only one to be selected at a time. Its layout can be adjusted based on the `isHorizontal` prop. When set to horizontal, it applies a specific style; otherwise, it defaults to a vertical layout.

Selection is tracked by identity rather than position: each item is matched on its vnode `:key` when it has one, falling back to its index for keyless static lists. Give items an explicit `:key` so the selection survives conditional or reordered items.

::: render
render=../../code/components/menu/options/preview.vue
:::

## Examples

::: example Alignment || Horizontal option menus can be used to allow users to select an alignment.
example=../../code/components/menu/options/alignment.vue
:::

::: example Option || Vertical option menus can be used to allow the user to switch between different view modes.
example=../../code/components/menu/options/option.vue
:::

::: example Inside a flyout || Option menus stay open while selecting, even inside a flyout. Pass :is-persistent="false" if you want the menu to close on selection instead.
example=../../code/components/menu/options/persistent.vue
:::

## Used components

* [Button](../button)
  * [Menu group](./group)

---

---
url: 'https://flux-ui.dev/components/menu/pane.md'
---

# Menu pane

A container that lets you drop a full interactive component (a [Color picker](../color/picker), a slider or a small form) into a [Menu](./), a [Menu flyout](./flyout) submenu or a [Context menu](../context-menu).

A plain [Menu](./) runs a roving focus zone: arrow keys move between its items and only one item sits in the tab order at a time. Wrapping custom content in a Menu pane opts that subtree out of the focus zone, so the embedded component keeps its own keyboard behavior. Arrow keys drive its sliders and steppers and `Tab` reaches every control. Arrow navigation across the surrounding menu items simply skips over the pane; reach it with `Tab`.

Clicking inside a pane never closes the menu, so the embedded component stays usable while the menu is open.

::: render
render=../../code/components/menu/pane/preview.vue
:::

## Examples

::: example Color picker || Embed a full color picker in a menu flyout submenu. Drag the saturation field, use the sliders and type into the inputs without the menu interfering.
example=../../code/components/menu/pane/color-picker.vue
:::

::: example Slider || A single control such as a slider. Focus it with `Tab`, then the arrow keys adjust the value instead of moving between menu items.
example=../../code/components/menu/pane/slider.vue
:::

::: example Range slider || A two-thumb range. Each thumb is its own focus stop and the arrow keys move it without disturbing the menu.
example=../../code/components/menu/pane/range.vue
:::

::: example Text area || A multi-line input. Typing, Enter and the arrow keys for the caret all stay inside the field.
example=../../code/components/menu/pane/note.vue
:::

::: example Filter || A search field that filters the items below it. Typing (including the arrow keys for the caret) stays inside the input.
example=../../code/components/menu/pane/filter.vue
:::

::: example Settings || Several controls in one pane. `Tab` reaches every toggle, and toggling one never closes the menu.
example=../../code/components/menu/pane/settings.vue
:::

---

---
url: 'https://flux-ui.dev/components/menu/sub-header.md'
---

# Menu sub header

This component is used for creating subheaders within menus. It can display an optional icon before and after the label, making it easy to visually separate different sections of a menu.

The label text is prominently displayed, and the subheader plays a role in organizing menu items into more digestible and structured sections. This component helps enhance the readability and usability of complex menus by providing clear visual breaks.

::: render
render=../../code/components/menu/sub-header/preview.vue
:::

## Examples

::: example Grouped
example=../../code/components/menu/sub-header/grouped.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/menu/title.md'
---

# Menu title

This component is used to display a title within a menu. The title is highlighted, enhancing the visual structure of the menu by clearly indicating different sections or overall context. This simple yet effective component ensures that users can easily identify the purpose or category of the menu items that follow.

::: render
render=../../code/components/menu/title/preview.vue
:::

## Examples

::: example Section
example=../../code/components/menu/title/section.vue
:::

---

---
url: 'https://flux-ui.dev/components/pagination.md'
---

# Pagination

A component that displays the pages for paginated content. The component automatically decides which pages to show or not.

::: render
render=../../code/components/pagination/preview.vue
:::

::: info Ellipsis behavior
Hidden pages are collapsed into a non-interactive ellipsis (`…`), which is hidden from assistive technologies via `aria-hidden`. A gap is only collapsed when at least two pages are hidden; a single hidden page is rendered directly, since an ellipsis would take up the same space as the page it replaces. In compact mode the current page button is labelled for screen readers so its purpose stays clear.
:::

## Examples

::: example Basic || A basic pagination.
example=../../code/components/pagination/basic.vue
:::

::: example Compact || A compact pagination.
example=../../code/components/pagination/compact.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/pagination/bar.md'
---

# Pagination bar

The pagination bar displays information about the current page of data and allows the user to change how many items are shown per page.

::: render
render=../../code/components/pagination/bar/preview.vue
:::

::: tip Empty data sets
When `total` is `0` the range readout shows `0` as its lower bound instead of `1`, so an empty result reads as `0–0 of 0` rather than implying a first item that does not exist.
:::

## Examples

::: example Basic || A basic pagination bar.
example=../../code/components/pagination/bar/basic.vue
:::

## Used components

* [Pagination](../pagination)
* [Layout](../layout)
  * [Spacer](../layout/spacer)
* [Form](../form)
  * [Select](../form/select)

---

---
url: 'https://flux-ui.dev/components/segmented-control.md'
---

# Segmented control

The segmented control lets users choose one option from a small set of segments. Each segment is a [Segmented control item](./item) with a label and/or icon, and the selected segment is highlighted. Use it in navigation, forms, or settings where a compact choice fits.

The selected segment is bound through `v-model` and reflects the `value` of the active [Segmented control item](./item).

::: render
render=../../code/components/segmented-control/preview.vue
:::

::: tip
To switch between content areas based on the selected segment, use [Tabs](../tabs/).
:::

## Examples

::: example Basic || A basic segmented control.
example=../../code/components/segmented-control/basic.vue
:::

::: example Icons || A segmented control with icons only.
example=../../code/components/segmented-control/icon.vue
:::

::: example With tabs || A segmented control driving the tab bar of [Tabs](../tabs/) to switch content.
example=../../code/components/segmented-control/tabs.vue
:::

::: example Sizes || A segmented control in all available sizes.
example=../../code/components/segmented-control/sizes.vue
:::

::: example Fill || A segmented control that fills its parent.
example=../../code/components/segmented-control/fill.vue
:::

::: example Disabled item || A segmented control with a single disabled segment.
example=../../code/components/segmented-control/disabled-item.vue
:::

::: example Disabled || A segmented control disabled in its entirety.
example=../../code/components/segmented-control/disabled.vue
:::

## Used components

* [Segmented control item](./item)
* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/segmented-control/item.md'
---

# Segmented control item

The segmented control item represents an individual segment within the segmented control. Each item carries a `value`; selecting it updates the segmented control's `v-model` to that value. An item can render an icon, a label, or fully custom content.

::: render
render=../../code/components/segmented-control/item/preview.vue
:::

::: warning
This component is best used within a [Segmented control](../segmented-control).
:::

## Examples

::: example Basic || A basic segmented control item.
example=../../code/components/segmented-control/item/basic.vue
:::

::: example Disabled || A segmented control with a disabled item.
example=../../code/components/segmented-control/item/disabled.vue
:::

::: example Icon only || Omit the `label` to render compact, icon-only segments.
example=../../code/components/segmented-control/item/icon-only.vue
:::

::: example Labels only || Omit the `icon` to render text-only segments.
example=../../code/components/segmented-control/item/labels-only.vue
:::

::: example Custom content || Use the default slot to render custom content such as an icon with a badge.
example=../../code/components/segmented-control/item/custom.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/stepper.md'
---

# Stepper

The stepper guides users through a process in clearly numbered steps, showing where they are and what remains.

::: render
render=../../code/components/stepper/preview.vue
:::

## Examples

::: example Basic || A basic stepper.
example=../../code/components/stepper/basic.vue
:::

::: example Custom steps || Override the `steps` slot to render labelled buttons instead of the default dot indicator.
example=../../code/components/stepper/custom-steps.vue
:::

## Used components

* [Stepper](../stepper)
  * [Steps](../stepper/steps)
* [Dynamic view](../dynamic-view)

---

---
url: 'https://flux-ui.dev/components/stepper/steps.md'
---

# Stepper steps

The stepper steps component displays the list of steps available in the stepper, showing users where they are in the overall process. It acts as a navigation layer, allowing users to understand their current position and progress while also offering a clear overview of what comes next.

::: render
render=../../code/components/stepper/steps/preview.vue
:::

## Examples

::: example Basic || A basic stepper steps.
example=../../code/components/stepper/steps/basic.vue
:::

::: example Progress states || The `current` prop drives the active step; completed steps show a check.
example=../../code/components/stepper/steps/progress.vue
:::

::: example Two steps || A minimal stepper with only two steps.
example=../../code/components/stepper/steps/two-steps.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/stepper/step.md'
---

# Stepper step

The stepper step represents an individual step within the stepper. It contains the content, actions, and guidance needed for that part of the process. Each FluxStepperStep helps users focus on one task at a time, making multi-step workflows feel clear and manageable.

## Snippet

::: code-group

```vue \[StepperStep.vue]
<template>
    <FluxStepperStep>
        <!-- Step content here -->
    </FluxStepperStep>
</template>

<script
    setup
    lang="ts">
    import { FluxStepperStep } from '@flux-ui/components';
</script>

```

:::

## Usage

Each step is placed inside a [Stepper steps](./steps) component. The step's content is only rendered when the corresponding step is active.

```vue
<FluxStepper v-model="currentStep">
    <FluxStepperSteps>
        <FluxStepperStep>
            <p>Content for the first step.</p>
        </FluxStepperStep>

        <FluxStepperStep>
            <p>Content for the second step.</p>
        </FluxStepperStep>
    </FluxStepperSteps>
</FluxStepper>
```

## Used components

* [Stepper](./index)
* [Stepper steps](./steps)

---

---
url: 'https://flux-ui.dev/components/tab-bar.md'
---

# Tab bar

The tab bar displays a row of navigation tabs, allowing users to switch between different sections or views within the interface. It groups multiple tab items together in a single bar and provides a consistent, easy-to-scan structure for navigating related content areas.

The bar is exposed as a `role="tablist"` and is fully keyboard navigable: ArrowLeft/ArrowUp and ArrowRight/ArrowDown move between tabs (wrapping around the ends), while Home and End jump to the first and last tab. Disabled tabs are skipped, and the overflow scroll arrows are hidden from assistive technologies. A single roving tab stop keeps the bar reachable with Tab: the selected tab is tabbable, or the first enabled tab when none is selected.

::: render
render=../../code/components/tab-bar/preview.vue
:::

## Examples

::: example Basic || A basic tab bar.
example=../../code/components/tab-bar/basic.vue
:::

::: example Icon and label || A tab bar with both icons and labels.
example=../../code/components/tab-bar/icon-label.vue
:::

::: example Pane || A tab bar inside a pane.
example=../../code/components/tab-bar/pane.vue
:::

::: example Pills || A tab bar rendered as pills.
example=../../code/components/tab-bar/pills.vue
:::

::: example Pills with icon and label || A pills tab bar with both icons and labels.
example=../../code/components/tab-bar/pills-icon-label.vue
:::

::: example Pills in pane || A pills tab bar inside a pane.
example=../../code/components/tab-bar/pills-pane.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/tab-bar/item.md'
---

# Tab bar item

The tab bar item represents an individual tab within the tab bar. Each item corresponds to a specific content view or section. When selected, it updates the displayed content accordingly, helping users understand where they are and switch between sections effortlessly.

::: render
render=../../code/components/tab-bar/item/preview.vue
:::

::: warning
This component is best used within a [Tab bar](../tab-bar).
:::

## Examples

::: example Basic || A basic tab bar item.
example=../../code/components/tab-bar/item/basic.vue
:::

::: example Pills || A tab bar item rendered as a pill.
example=../../code/components/tab-bar/item/pills.vue
:::

::: example Active tab || Mark the selected tab with `is-active`.
example=../../code/components/tab-bar/item/active.vue
:::

::: example Disabled tab || A tab bar with a disabled item that cannot be selected.
example=../../code/components/tab-bar/item/disabled.vue
:::

::: example Label only || Tab bar items can render just a `label` without an icon.
example=../../code/components/tab-bar/item/label-only.vue
:::

::: example Count badge || Show an unread or item count after the label using the `end` slot.
example=../../code/components/tab-bar/item/count.vue
:::

::: example Avatar and status || Render an avatar with a status indicator before the label using the `start` slot.
example=../../code/components/tab-bar/item/avatar.vue
:::

::: example Validation state || Flag a tab that contains errors. The slot may be filled conditionally.
example=../../code/components/tab-bar/item/validation.vue
:::

::: example Start and end slots || Both slots combined in a single tab.
example=../../code/components/tab-bar/item/slots.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/tabs.md'
---

# Tabs

The tabs component organizes content into separate views, showing one at a time. Each tab switches to its matching content area, keeping related content grouped without crowding the interface.

::: render
render=../../code/components/tabs/preview.vue
:::

## Examples

::: example Basic || A basic tabs pane.
example=../../code/components/tabs/basic.vue
:::

::: example Icons || A tabs pane with only icons.
example=../../code/components/tabs/icons.vue
:::

::: example Icon and label || A tabs pane with both icons and labels.
example=../../code/components/tabs/icon-label.vue
:::

::: example Pills || A tabs pane with the tab bar rendered as pills.
example=../../code/components/tabs/pills.vue
:::

::: example Pills with icons || A pills tabs pane with only icons.
example=../../code/components/tabs/pills-icons.vue
:::

::: example Pills with icon and label || A pills tabs pane with both icons and labels.
example=../../code/components/tabs/pills-icon-label.vue
:::

## Used components

* [Tab bar](../tab-bar)
  * [Item](../tab-bar/item)

---

---
url: 'https://flux-ui.dev/components/tabs/tab.md'
---

# Tab

A tab represents a single selectable option within a tabs interface. Each tab is labelled to indicate the content it corresponds to, and selecting it updates the view to display the associated content area.

::: render
render=../../code/components/tabs/tab/preview.vue
:::

::: warning
This component is best used within [Tabs](../tabs). The icon and label props are not rendered without it.
:::

## Examples

::: example Basic || A basic tab.
example=../../code/components/tabs/tab/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/data-display.md'
---

# Data display

The data display components present structured data in a clear, scannable way, from tables and filters to timelines, calendars and tree views.

---

---
url: 'https://flux-ui.dev/components/calendar.md'
---

# Calendar

This component shows a calendar with four different views (month, week, two-days, day). Items can
be added to the calendar by filling the default slot with `FluxCalendarItem` instances.

::: render
render=../../code/components/calendar/preview.vue
:::

## Snippet

::: code-group

```vue \[Calendar.vue]
<template>
    <FluxCalendar :initial-date="anchorDate">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }}
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    const anchorDate = DateTime.now().startOf('month').plus({days: 9});

    const events = [
        {id: 1, date: anchorDate, label: 'Stand-up', color: 'primary' as Color},
        {id: 2, date: anchorDate, label: 'Design review', color: 'info' as Color},
        {id: 3, date: anchorDate.plus({days: 1}), label: 'Sprint planning', color: 'warning' as Color},
        {id: 4, date: anchorDate.plus({days: 2}), label: 'Demo', color: 'success' as Color},
        {id: 5, date: anchorDate.plus({days: 4}), label: 'Retro', color: 'primary' as Color},
        {id: 6, date: anchorDate.plus({days: 7}), label: 'Release', color: 'success' as Color}
    ];

    function cardStyle(color: Color): string {
        return `padding: 6px 9px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 13px; line-height: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`;
    }
</script>

```

:::

## Auto-responsive views

When you don't pass a `view` prop, the calendar picks the most appropriate view based on the viewport.
On large screens it shows `month`, on medium screens it falls back to `week`, then `two-days` and finally
`day` on small viewports.

::: render
render=../../code/components/calendar/auto-responsive.vue
:::

::: code-group

```vue \[AutoResponsive.vue]
<template>
    <FluxCalendar :initial-date="anchorDate">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :duration="event.duration"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }}
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    const anchorDate = DateTime.now().startOf('week').plus({hours: 9});

    const events = [
        {id: 1, date: anchorDate, duration: 30, label: 'Stand-up', color: 'primary' as Color},
        {id: 2, date: anchorDate.plus({day: 1, hours: 1}), duration: 60, label: 'Design review', color: 'info' as Color},
        {id: 3, date: anchorDate.plus({day: 2, hours: 4}), duration: 30, label: 'Demo', color: 'success' as Color},
        {id: 4, date: anchorDate.plus({day: 3, hours: 2}), duration: 90, label: 'Workshop', color: 'warning' as Color},
        {id: 5, date: anchorDate.plus({day: 4, hours: 5}), duration: 60, label: 'Retro', color: 'primary' as Color}
    ];

    function cardStyle(color: Color): string {
        return `padding: 4px 8px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 12px; line-height: 1.2;`;
    }
</script>

```

:::

## Week view

A 7-column time-grid with a sticky day-header, an all-day section and a vertically scrollable hour-grid.
Use `duration` on items to set their length in minutes.

::: render
render=../../code/components/calendar/week-view.vue
:::

::: code-group

```vue \[WeekView.vue]
<template>
    <FluxCalendar
        :initial-date="anchorDate"
        :hour-range="[7, 20]"
        view="week">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :duration="event.duration"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }}
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    const anchorDate = DateTime.now().startOf('week').plus({hours: 9});

    const events = [
        {id: 1, date: anchorDate, duration: 30, label: 'Stand-up', color: 'primary' as Color},
        {id: 2, date: anchorDate.plus({hours: 3}), duration: 60, label: 'Lunch', color: 'warning' as Color},
        {id: 3, date: anchorDate.plus({day: 1, hours: 1}), duration: 120, label: 'Design review', color: 'info' as Color},
        {id: 4, date: anchorDate.plus({day: 2, hours: 5}), duration: 30, label: 'Demo', color: 'success' as Color},
        {id: 5, date: anchorDate.plus({day: 3, hours: 2}), duration: 90, label: 'Workshop', color: 'primary' as Color},
        {id: 6, date: anchorDate.plus({day: 4, hours: 4}), duration: 60, label: 'Retro', color: 'info' as Color}
    ];

    function cardStyle(color: Color): string {
        return `padding: 4px 8px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 12px; line-height: 1.2; height: 100%; box-sizing: border-box;`;
    }
</script>

```

:::

## Day view

The single-day variant of the time-grid. Combine `duration` with `all-day` for a richer day-planning view.

::: render
render=../../code/components/calendar/day-view.vue
:::

::: code-group

```vue \[DayView.vue]
<template>
    <FluxCalendar
        :initial-date="today"
        :hour-range="[8, 18]"
        view="day">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :duration="event.duration"
                :all-day="event.allDay"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }}
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    const today = DateTime.now().startOf('day');

    const events = [
        {id: 1, date: today, allDay: true, duration: 0, label: 'On call', color: 'warning' as Color},
        {id: 2, date: today.plus({hours: 9}), allDay: false, duration: 30, label: 'Stand-up', color: 'primary' as Color},
        {id: 3, date: today.plus({hours: 10}), allDay: false, duration: 90, label: 'Design review', color: 'info' as Color},
        {id: 4, date: today.plus({hours: 13}), allDay: false, duration: 60, label: 'Lunch', color: 'success' as Color},
        {id: 5, date: today.plus({hours: 15}), allDay: false, duration: 60, label: 'Pair session', color: 'primary' as Color},
        {id: 6, date: today.plus({hours: 16, minutes: 30}), allDay: false, duration: 30, label: 'Wrap up', color: 'info' as Color}
    ];

    function cardStyle(color: Color): string {
        return `padding: 4px 8px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 12px; line-height: 1.2; height: 100%; box-sizing: border-box;`;
    }
</script>

```

:::

## Draggable items

Set `draggable` on the calendar to let users move items between day-cells (and time-slots in time-grid views).
The calendar is fully controlled. Listen for the `reschedule` event and update your own state. While dragging,
hovering the previous/next month buttons advances the view so items can be moved across months.

::: render
render=../../code/components/calendar/draggable.vue
:::

::: code-group

```vue \[Draggable.vue]
<template>
    <FluxCalendar
        :initial-date="anchorDate"
        :draggable="true"
        @reschedule="onReschedule">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }}
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
    import { ref } from 'vue';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    type Event = {
        readonly id: number;
        date: DateTime;
        readonly label: string;
        readonly color: Color;
    };

    const anchorDate = DateTime.now().startOf('month').plus({days: 9});

    const events = ref<Event[]>([
        {id: 1, date: anchorDate, label: 'Stand-up', color: 'primary'},
        {id: 2, date: anchorDate.plus({days: 1}), label: 'Design review', color: 'info'},
        {id: 3, date: anchorDate.plus({days: 2}), label: 'Sprint demo', color: 'success'},
        {id: 4, date: anchorDate.plus({days: 3}), label: 'Retrospective', color: 'warning'},
        {id: 5, date: anchorDate.plus({days: 4}), label: 'Release', color: 'success'},
        {id: 6, date: anchorDate.plus({days: 7}), label: 'Planning', color: 'primary'}
    ]);

    function onReschedule({id, toDate}: {id: number | string; toDate: DateTime}): void {
        const event = events.value.find(e => e.id === id);

        if (event) {
            event.date = toDate;
        }
    }

    function cardStyle(color: Color): string {
        return `padding: 6px 9px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 13px; line-height: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`;
    }
</script>

```

:::

## Resize

In time-grid views, items expose top and bottom drag-handles when the calendar is `draggable`. Listen
for the `resize` event to update your `duration` (and optionally `date` for top-handle resizes).

::: render
render=../../code/components/calendar/resize.vue
:::

::: code-group

```vue \[Resize.vue]
<template>
    <FluxCalendar
        :initial-date="anchorDate"
        :hour-range="[8, 18]"
        view="day"
        draggable
        @reschedule="onReschedule"
        @resize="onResize">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :duration="event.duration"
                :id="event.id">
                <div :style="cardStyle(event.color)">
                    {{ event.label }} · {{ event.duration }}m
                </div>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
    import { ref } from 'vue';

    type Color = 'primary' | 'success' | 'info';

    type Event = {
        readonly id: number;
        date: DateTime;
        duration: number;
        readonly label: string;
        readonly color: Color;
    };

    const anchorDate = DateTime.now().startOf('day');

    const events = ref<Event[]>([
        {id: 1, date: anchorDate.plus({hours: 9}), duration: 60, label: 'Stand-up', color: 'primary'},
        {id: 2, date: anchorDate.plus({hours: 11}), duration: 90, label: 'Design review', color: 'info'},
        {id: 3, date: anchorDate.plus({hours: 14}), duration: 30, label: 'Demo', color: 'success'}
    ]);

    function onReschedule({id, toDate}: {id: number | string; toDate: DateTime}): void {
        const event = events.value.find(e => e.id === id);

        if (event) {
            event.date = toDate;
        }
    }

    function onResize({id, toDate, toDuration}: {id: number | string; toDate: DateTime; toDuration: number}): void {
        const event = events.value.find(e => e.id === id);

        if (event) {
            event.date = toDate;
            event.duration = toDuration;
        }
    }

    function cardStyle(color: Color): string {
        return `padding: 4px 8px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 12px; line-height: 1.2; height: 100%; box-sizing: border-box;`;
    }
</script>

```

:::

## Keyboard navigation

When `draggable` is enabled, items become focusable. Press Tab to focus an item, then
Space or Enter to grab. Use the arrow keys to move it (per day in
month, per snap-step or per day in time-grid). Enter drops; Escape
cancels.

::: render
render=../../code/components/calendar/keyboard.vue
:::

::: code-group

```vue \[Keyboard.vue]
<template>
    <div>
        <p style="margin-bottom: 12px; font-size: 13px; color: var(--foreground-secondary);">
            Tab to focus an item, then use <strong>Space</strong> or <strong>Enter</strong> to grab it.
            Use <strong>Arrow keys</strong> to move, <strong>Enter</strong> to drop and <strong>Escape</strong> to cancel.
        </p>

        <FluxCalendar
            :initial-date="anchorDate"
            draggable
            @reschedule="onReschedule">
            <template
                v-for="event of events"
                :key="event.id">
                <FluxCalendarItem
                    :date="event.date"
                    :id="event.id">
                    <div :style="cardStyle(event.color)">
                        {{ event.label }}
                    </div>
                </FluxCalendarItem>
            </template>
        </FluxCalendar>
    </div>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
    import { ref } from 'vue';

    type Color = 'primary' | 'success' | 'warning' | 'info';

    type Event = {
        readonly id: number;
        date: DateTime;
        readonly label: string;
        readonly color: Color;
    };

    const anchorDate = DateTime.now().startOf('month').plus({days: 9});

    const events = ref<Event[]>([
        {id: 1, date: anchorDate, label: 'Stand-up', color: 'primary'},
        {id: 2, date: anchorDate.plus({days: 1}), label: 'Design review', color: 'info'},
        {id: 3, date: anchorDate.plus({days: 2}), label: 'Demo', color: 'success'},
        {id: 4, date: anchorDate.plus({days: 4}), label: 'Retro', color: 'warning'},
        {id: 5, date: anchorDate.plus({days: 7}), label: 'Release', color: 'success'}
    ]);

    function onReschedule({id, toDate}: {id: number | string; toDate: DateTime}): void {
        const event = events.value.find(e => e.id === id);

        if (event) {
            event.date = toDate;
        }
    }

    function cardStyle(color: Color): string {
        return `padding: 6px 9px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 13px; line-height: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`;
    }
</script>

```

:::

## Plain items

An item without custom styling, just text in the slot. Useful for lightweight calendars where the day's
events are simply listed.

::: render
render=../../code/components/calendar/plain.vue
:::

::: code-group

```vue \[Plain.vue]
<template>
    <FluxCalendar :initial-date="anchorDate">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :id="event.id"
                @click="event.onClick">
                {{ event.label }}
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    const anchorDate = DateTime.now().startOf('month').plus({days: 9});

    const events = [
        {id: 1, date: anchorDate, label: 'Stand-up', onClick: undefined},
        {id: 2, date: anchorDate, label: 'Lunch with team', onClick: () => alert('Lunch')},
        {id: 3, date: anchorDate.plus({days: 1}), label: 'Pair programming', onClick: undefined},
        {id: 4, date: anchorDate.plus({days: 2}), label: 'Code review', onClick: () => alert('Code review')},
        {id: 5, date: anchorDate.plus({days: 4}), label: 'Demo', onClick: undefined},
        {id: 6, date: anchorDate.plus({days: 4}), label: 'Drinks', onClick: undefined},
        {id: 7, date: anchorDate.plus({days: 7}), label: 'Release', onClick: () => alert('Release')}
    ];
</script>

```

:::

## Item with tooltip

Wrap your item content in a [Tooltip](../tooltip) component to surface extra detail on hover.

::: render
render=../../code/components/calendar/tooltip.vue
:::

::: code-group

```vue \[Tooltip.vue]
<template>
    <FluxCalendar :initial-date="anchorDate">
        <template
            v-for="event of events"
            :key="event.id">
            <FluxCalendarItem
                :date="event.date"
                :id="event.id">
                <FluxTooltip :content="event.tooltip">
                    <div :style="cardStyle(event.color)">
                        {{ event.label }}
                    </div>
                </FluxTooltip>
            </FluxCalendarItem>
        </template>
    </FluxCalendar>
</template>

<script
    lang="ts"
    setup>
    import { FluxCalendar, FluxCalendarItem, FluxTooltip } from '@flux-ui/components';
    import { DateTime } from 'luxon';

    type Color = 'primary' | 'success' | 'warning';

    const anchorDate = DateTime.now().startOf('month').plus({days: 9});

    const events = [
        {id: 1, date: anchorDate, label: 'Stand-up', tooltip: 'Daily stand-up at 09:30 with the engineering team.', color: 'primary' as Color},
        {id: 2, date: anchorDate.plus({days: 1}), label: 'Lunch with Anna', tooltip: 'Lunch with Anna at the new place around the corner. 12:30.', color: 'warning' as Color},
        {id: 3, date: anchorDate.plus({days: 2}), label: 'Demo', tooltip: 'Demo of the new dashboard for stakeholders. 15:00 — 16:00.', color: 'success' as Color},
        {id: 4, date: anchorDate.plus({days: 4}), label: 'Retro', tooltip: 'Sprint retrospective. 14:00.', color: 'primary' as Color}
    ];

    function cardStyle(color: Color): string {
        return `padding: 6px 9px; background: var(--${color}-100); color: var(--${color}-800); border-radius: var(--radius-half); font-size: 13px; line-height: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`;
    }
</script>

```

:::

## Used components

* [Action bar](../action-bar)
* [Button](../button)
  * [Secondary](../button/secondary)
  * [Group](../button/group)
* [Calendar](../calendar)
  * [Item](../calendar/item)
* [Date picker](../date-picker)
* [Flyout](../flyout)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/calendar/item.md'
---

# Calendar item

This component is used within the [Calendar](../calendar) component to render a single calendar entry. The
`default` slot is yours to fill. Render any content (icons, labels, badges, copy) you like. When the parent
calendar has `draggable` enabled, items with an `id` can be dragged between day-cells (in month view) or between
day-cells and time-slots (in time-grid views).

To add a tooltip, wrap your slot content in a [Tooltip](../tooltip) component.

## Snippets

::: code-group

```vue [CalendarItem.vue]
<template>
    <FluxCalendarItem
        :date="DateTime.now()"
        :id="1">
        <div class="my-card">
            Work
        </div>
    </FluxCalendarItem>
</template>

<script
    setup
    lang="ts">
    import { FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
</script>
```

```vue [CalendarItemWithDuration.vue]
<template>
    <FluxCalendarItem
        :date="DateTime.now().set({hour: 10})"
        :duration="90"
        :id="2">
        <div class="my-card">
            Design review
        </div>
    </FluxCalendarItem>
</template>

<script
    setup
    lang="ts">
    import { FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
</script>
```

```vue [CalendarItemAllDay.vue]
<template>
    <FluxCalendarItem
        :date="DateTime.now()"
        :all-day="true"
        :id="3">
        <div class="my-card">
            On call
        </div>
    </FluxCalendarItem>
</template>

<script
    setup
    lang="ts">
    import { FluxCalendarItem } from '@flux-ui/components';
    import { DateTime } from 'luxon';
</script>
```

```vue [CalendarItemWithTooltip.vue]
<template>
    <FluxCalendarItem
        :date="DateTime.now()"
        :id="4">
        <FluxTooltip content="Important meeting today.">
            <div class="my-card">
                Meeting
            </div>
        </FluxTooltip>
    </FluxCalendarItem>
</template>

<script
    setup
    lang="ts">
    import { FluxCalendarItem, FluxTooltip } from '@flux-ui/components';
    import { DateTime } from 'luxon';
</script>
```

:::

---

---
url: 'https://flux-ui.dev/components/comment.md'
---

# Comment

This component represents a user comment with support for customizable details such as the author's name, avatar, and optional time information. It includes a structured layout with an avatar, header, and message body, allowing additional content to be provided via a slot. Styles can adjust its appearance, such as flipping or differentiating received comments.

::: render
render=../code/components/comment/preview.vue
:::

## Examples

::: example Incoming || An incoming comment that is used within a message thread.
example=../code/components/comment/incoming.vue
:::

::: example Outgoing || An outgoing comment that is used within a message thread.
example=../code/components/comment/outgoing.vue
:::

::: example Typing || An indication that someone is typing a message.
example=../code/components/comment/typing.vue
:::

## Used components

* [Avatar](./avatar)

---

---
url: 'https://flux-ui.dev/components/data-table.md'
---

# Data table

The data table organizes large sets of data into rows and columns, layering sorting, filtering, pagination, selection, grouping and expandable rows on top of a plain [Table](./table). It is built for server-driven data, so you feed it one page of rows at a time.

::: render
render=../code/components/data-table/preview.vue
:::

::: info Server-side pagination
The data table does **not** paginate `items` internally. The `items` prop should contain only the rows for the currently active page, fetched from your server or API. The `page` and `per-page` props are used to drive the pagination bar and are exposed through slot bindings so you can display them, but the component never slices or filters the `items` array itself.
:::

::: tip Fast group toggling
By default a collapsed group unmounts its rows, so re-expanding a group of rich rows (per-row flyouts, links, indicators) re-mounts all of them. Set `collapse-mode="hide"` to keep the rows mounted and hide them instead, making every toggle instant. Hidden rows are excluded from keyboard navigation and assistive technology, so there is no visible or behavioural change beyond the speed.
:::

## Examples

::: example File manager || A data table that is used for file management.
example=../code/components/data-table/file-manager.vue
:::

::: example Paginated || A data table that is split into pages.
example=../code/components/data-table/paginated.vue
:::

::: example Custom pagination || A data table whose `pagination` slot renders a compact pager instead of the default bar.
example=../code/components/data-table/pagination-slot.vue
:::

::: example Clickable rows || A data table that emits `row-click` per row, while ignoring clicks on the action button inside a cell. Focused rows can be walked with the arrow keys and activated with `Enter`/`Space`.
example=../code/components/data-table/clickable.vue
:::

::: example Row colors || A data table that tints rows based on their status.
example=../code/components/data-table/row-colors.vue
:::

::: example Selectable rows || A data table where multiple rows can be selected via checkboxes.
example=../code/components/data-table/selection.vue
:::

::: example Single selection || A data table where at most one row can be selected.
example=../code/components/data-table/selection-single.vue
:::

::: example Selection toolbar || A bar with bulk actions that takes the place of the filter bar while rows are selected.
example=../code/components/data-table/selection-toolbar.vue
:::

::: example Sortable columns || A data table whose columns drive a single, coordinated client-side sort.
example=../code/components/data-table/sortable.vue
:::

::: example Filtering and search || A data table with a filter bar, client-side filtering, pagination and selection.
example=../code/components/data-table/filterable.vue
:::

::: example Rich cells and row actions || A data table with avatars, badges, progress bars and a per-row actions menu.
example=../code/components/data-table/rich.vue
:::

::: example Expandable rows || A data table where each row can be expanded to reveal detail content.
example=../code/components/data-table/expandable.vue
:::

::: example Single expansion || A data table where opening a row collapses the previously opened one.
example=../code/components/data-table/expand-single.vue
:::

::: example Conditional expansion || A data table where only rows with detail content show an expand toggle.
example=../code/components/data-table/expand-conditional.vue
:::

::: example Grouped rows || A data table whose rows are grouped under collapsible headers.
example=../code/components/data-table/grouped.vue
:::

::: example Static groups || A data table whose rows are grouped under plain, non-collapsible headers.
example=../code/components/data-table/grouped-static.vue
:::

::: example Wide table || A wide data table with multiple pinned columns on the left and right edges.
example=../code/components/data-table/wide.vue
:::

::: example Pinned with selection || A data table where pinning the first column keeps the selection column pinned alongside it.
example=../code/components/data-table/pinned.vue
:::

::: example Column sizing || Headers mixing a fixed width, a min/max range and a shrinking column.
example=../code/components/data-table/column-sizing.vue
:::

::: example Numeric columns || Right-aligned numeric columns with sortable numeric and date headers.
example=../code/components/data-table/numeric.vue
:::

::: example Summary footer || A footer row that sums the page across spanning cells.
example=../code/components/data-table/footer.vue
:::

::: example Fixed-width columns || A weekly timesheet with fixed-width day columns and a total.
example=../code/components/data-table/timesheet.vue
:::

::: example Stacked cells || Cells that stack a primary and secondary line of content.
example=../code/components/data-table/stacked.vue
:::

::: example Wrapping content || A wrapping subject column whose meta columns stay on a single line.
example=../code/components/data-table/wrapping.vue
:::

::: example Consistent height || A partial page that keeps a fixed height with filler rows.
example=../code/components/data-table/fill.vue
:::

::: example Sticky header || A long list whose header and bar stick while scrolling.
example=../code/components/data-table/sticky.vue
:::

::: example Sticky groups || Grouped rows whose header sticks while scrolling through the groups.
example=../code/components/data-table/sticky-groups.vue
:::

::: example Skeleton loading || A data table whose `loading` slot replaces the spinner with skeleton rows.
example=../code/components/data-table/skeleton.vue
:::

::: example Empty || A data table that shows a custom message when there is no data.
example=../code/components/data-table/empty.vue
:::

## Used components

* [Table](./table)
  * [Actions](./table/actions)
  * [Cell](./table/cell)
  * [Group](./table/group)
  * [Header](./table/header)
  * [Row](./table/row)

---

---
url: 'https://flux-ui.dev/components/description-list.md'
---

# Description list

The Description list component displays a set of label/value pairs, such as the fields of a record in a detail panel. It renders as a semantic `<dl>` with an optional heading, an optional leading icon per row, and the value aligned to the trailing edge. Values can be plain text, or richer content such as a badge, a copy action, or a link.

::: render
render=../../code/components/description-list/preview.vue
:::

::: tip
For a single icon and message, use [Info](../info) instead. The description list is meant for multiple label/value pairs.
:::

## Examples

::: example Account || A profile panel with labels, icons, and a status badge.
example=../../code/components/description-list/account.vue
:::

::: example Order summary || An order panel with a copy action, a badge, and a stacked address.
example=../../code/components/description-list/order.vue
:::

::: example Aligned labels || Values aligned to the leading edge next to a label column, using `label-width`.
example=../../code/components/description-list/aligned.vue
:::

::: example Columns || Items laid out as columns separated by dividers, using `direction="horizontal"`.
example=../../code/components/description-list/horizontal.vue
:::

## Used components

* [Description item](./item)

---

---
url: 'https://flux-ui.dev/components/description-list/item.md'
---

# Description item

The Description item component represents a single label/value pair within a [Description list](./). The label is rendered as a `<dt>` with an optional leading icon, and the value, provided through the default slot, as a `<dd>` aligned to the trailing edge.

::: render
render=../../code/components/description-list/item/preview.vue
:::

## Examples

::: example Basic || A description item with an icon and a rich value.
example=../../code/components/description-list/item/basic.vue
:::

::: example Multiple pairs || A typical list of several term and value pairs.
example=../../code/components/description-list/item/multiple.vue
:::

::: example Stacked || Use `is-stacked` to place the value below the label instead of beside it.
example=../../code/components/description-list/item/stacked.vue
:::

::: example Custom label || Use the `label` slot to render custom markup for the term.
example=../../code/components/description-list/item/custom-label.vue
:::

## Used components

* [Description list](./)

---

---
url: 'https://flux-ui.dev/components/filter.md'
---

# Filter

The filter builds nested filter menus with state management, navigation, and optional reset support. It organizes its content from the slots you provide and animates height changes as users move between views.

::: render
render=../../code/components/filter/preview.vue
:::

::: tip
Don't make your view too complex. Limit yourself to one filter per view.
:::

::: tip
Looking for a toolbar-style filter with a search input? See [Filter bar](./bar).
:::

## Available filters

* [Date](./date)
* [Date range](./date-range)
* [Option](./option)
* [Options](./options)
* [Range](./range)
* [Async option](./async-option)
* [Async options](./async-options)

## Common props

Every filter component (built-in and custom) accepts the following props in addition to its own:

::: tip Clear vs. reset
Clearing a filter removes its key from the state entirely and calls on-clear. Resetting a filter that has a default-value writes that value back and calls on-change; resetting a filter without a default-value behaves like clear and removes the key while calling on-clear.
:::

## Custom filter types

Build your own filter component by calling `defineFilter()` on the top level of `<script setup>`. The macro registers a factory that `FluxFilter` and `FluxFilterBar` invoke to obtain the filter's runtime metadata (label, icon, badge text, lifecycle, …). The component name does not matter. Any component that calls `defineFilter()` is accepted.

::: warning Vite plugin required
`defineFilter()` is a compile-time macro. Add the plugin from `@flux-ui/components/vite` to your Vite config. Without it the call is left as a no-op and the filter will not register.

```ts [vite.config.ts]
import { defineFilterMacro } from '@flux-ui/components/vite';
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        defineFilterMacro(),
        vue()
    ]
});
```

:::

::: example Custom toggle filter || Defining a boolean toggle filter using `defineFilter`.
example=../../code/components/filter/custom/preview.vue
:::

The toggle component above is implemented like this:

::: code-group

```vue \[Usage]
<template>
    <FluxPane style="width: max-content; align-self: start">
        <FluxFilter
            v-model="filterState">
            <MyToggleFilter
                icon="bell"
                label="Notifications"
                name="notifications"
                :default-value="true"/>

            <MyToggleFilter
                icon="moon"
                label="Dark mode"
                name="darkMode"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';
    import MyToggleFilter from './MyToggleFilter.vue';

    const filterState = ref<FluxFilterState>({});
</script>

```

:::

## Examples

::: example Basic || A basic example of the filter.
example=../../code/components/filter/full.vue
:::

::: example Flyout || A filter that pops up when you press on a button.
example=../../code/components/filter/flyout.vue
:::

## Used components

* [Menu](../menu)
  * [Group](../menu/group)
  * [Item](../menu/item)
* [Window](../window)

---

---
url: 'https://flux-ui.dev/components/filter/bar.md'
---

# Filter bar

The filter bar combines a search input with dynamic filter buttons into a single toolbar. Active filters are shown as individual buttons with a badge indicating the selected value. When the bar runs out of space, overflow filters collapse into a flyout menu. This component is an alternative to [Filter](./index) and is well suited for use above data tables.

::: render
render=../../code/components/filter/bar/preview.vue
:::

::: tip
Don't make your view too complex. Limit yourself to one filter bar per view.
:::

## Examples

::: example Basic || A basic filter bar with a search input and filters.
example=../../code/components/filter/bar.vue
:::

::: example Start and end slots || Adding custom content before the search input and after the filter button.
example=../../code/components/filter/bar/slots.vue
:::

## Used components

* [Filter](./index)
* [Flyout](../flyout)
* [Form](../form)
  * [Input](../form/input/)
* [Button](../button)
  * [Secondary](../button/secondary)
* [Menu](../menu)
* [Overflow bar](../overflow-bar)
* [Separator](../separator)

---

---
url: 'https://flux-ui.dev/components/filter/date.md'
---

# Filter date

The date filter lets users pick a single date, honoring the configured minimum and maximum. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/date/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterDate.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterDate
                icon="calendar"
                label="Date"
                name="option"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterDate, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { DateTime } from 'luxon';
    import { ref } from 'vue';

    const filterState = ref<FluxFilterState>({
        option: DateTime.now()
    });
</script>

```

:::

## Used components

* [Date picker](../date-picker)

---

---
url: 'https://flux-ui.dev/components/filter/date-range.md'
---

# Filter date range

The date range filter lets users pick a start and end date, honoring the configured minimum and maximum. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/date-range/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterDateRange.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterDateRange
                icon="calendar"
                label="Date range"
                name="option"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterDateRange, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { DateTime } from 'luxon';
    import { ref } from 'vue';

    const filterState = ref<FluxFilterState>({
        option: [
            DateTime.now().startOf('week'),
            DateTime.now().endOf('week')
        ]
    });
</script>

```

:::

## Used components

* [Date picker](../date-picker)

---

---
url: 'https://flux-ui.dev/components/filter/option.md'
---

# Filter option

The option filter lets users pick a single option from a predefined set. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/option/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterOption.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterOption
                icon="clone"
                label="Option"
                name="option"
                :options="[
                        {label: 'Option A', value: 'a'},
                        {label: 'Option B', value: 'b'},
                        {label: 'Option C', value: 'c'},
                        {label: 'Option D', value: 'd'},
                        {label: 'Option E', value: 'e'}
                    ]"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterOption, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';

    const filterState = ref<FluxFilterState>({
        option: 'a'
    });
</script>

```

:::

## Used components

* [Form](../form)
  * [Input](../form/input)
* [Menu](../menu)
  * [Group](../menu/group)
  * [Item](../menu/item)
  * [Sub header](../menu/sub-header)

---

---
url: 'https://flux-ui.dev/components/filter/options.md'
---

# Filter options

The options filter lets users pick multiple options from a predefined set. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/options/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterOptions.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterOptions
                icon="clone"
                label="Options"
                name="options"
                :options="[
                        {label: 'Option A', value: 'a'},
                        {label: 'Option B', value: 'b'},
                        {label: 'Option C', value: 'c'},
                        {label: 'Option D', value: 'd'},
                        {label: 'Option E', value: 'e'}
                    ]"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterOptions, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';

    const filterState = ref<FluxFilterState>({
        options: ['b', 'd']
    });
</script>

```

:::

## Used components

* [Form](../form)
  * [Input](../form/input)
* [Menu](../menu)
  * [Group](../menu/group)
  * [Item](../menu/item)
  * [Sub header](../menu/sub-header)

---

---
url: 'https://flux-ui.dev/components/filter/range.md'
---

# Filter range

The range filter constrains a data set to a numeric range with a pair of sliders, one for the lower bound and one for the upper. It writes the selected range to the filter state automatically.

::: render
render=../../code/components/filter/range/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterRange.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterRange
                icon="clone"
                label="Range"
                name="option"
                :max="1000"
                :min="100"
                :step="10"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterRange, FluxPane } from '@flux-ui/components';
    import type { FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';

    const filterState = ref<FluxFilterState>({
        option: [500, 750]
    });
</script>

```

:::

## Used components

* [Form](../form)
  * [Column](../form/column)
  * [Field](../form/field)
  * [Slider](../form/slider)

---

---
url: 'https://flux-ui.dev/components/filter/async-option.md'
---

# Filter option (async)

The async option filter lets users pick a single option from a set that is fetched on demand. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/async-option/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterAsyncOption.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterOptionAsync
                :fetch-options="fetchOptions"
                :fetch-relevant="fetchRelevant"
                :fetch-search="fetchSearch"
                icon="clone"
                label="Option"
                name="option"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterOptionAsync, FluxPane } from '@flux-ui/components';
    import type { FluxFilterOptionRow, FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';
    import dataset from '../../../../assets/select-dataset.json' with { type: 'json' };

    const filterState = ref<FluxFilterState>({
        option: '73c83353-de92-8110-9bce-c2a9e8c0de64'
    });

    async function fetchOptions(values: string[]): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.filter(o => values.includes(o.value));
    }

    async function fetchRelevant(): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.toSorted();
    }

    async function fetchSearch(searchQuery: string): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.filter(o => o.label.toLowerCase().includes(searchQuery.toLowerCase()));
    }
</script>

```

:::

## Used components

* [Form](../form)
  * [Input](../form/input)
* [Menu](../menu)
  * [Group](../menu/group)
  * [Item](../menu/item)
  * [Sub header](../menu/sub-header)

---

---
url: 'https://flux-ui.dev/components/filter/async-options.md'
---

# Filter options (async)

The async options filter lets users pick multiple options from a set that is fetched on demand. It writes the selection to the filter state automatically.

::: render
render=../../code/components/filter/async-options/preview.vue
:::

::: warning
This component can only be used within a [Filter](./index).
:::

## Snippet

::: code-group

```vue \[FilterAsyncOptions.vue]
<template>
    <FluxPane style="width: max-content">
        <FluxFilter v-model="filterState">
            <FluxFilterOptionsAsync
                :fetch-options="fetchOptions"
                :fetch-relevant="fetchRelevant"
                :fetch-search="fetchSearch"
                icon="clone"
                label="Options"
                name="options"/>
        </FluxFilter>
    </FluxPane>
</template>

<script
    lang="ts"
    setup>
    import { FluxFilter, FluxFilterOptionsAsync, FluxPane } from '@flux-ui/components';
    import type { FluxFilterOptionRow, FluxFilterState } from '@flux-ui/types';
    import { ref } from 'vue';
    import dataset from '../../../../assets/select-dataset.json' with { type: 'json' };

    const filterState = ref<FluxFilterState>({
        options: ['73c83353-de92-8110-9bce-c2a9e8c0de64', '92f99357-7fe5-71eb-74e2-55e057607e16']
    });

    async function fetchOptions(values: string[]): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.filter(o => values.includes(o.value));
    }

    async function fetchRelevant(): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.toSorted();
    }

    async function fetchSearch(searchQuery: string): Promise<FluxFilterOptionRow[]> {
        await new Promise(resolve => setTimeout(resolve, 300));

        return dataset.filter(o => o.label.toLowerCase().includes(searchQuery.toLowerCase()));
    }
</script>

```

:::

## Used components

* [Form](../form)
  * [Input](../form/input)
* [Menu](../menu)
  * [Group](../menu/group)
  * [Item](../menu/item)
  * [Sub header](../menu/sub-header)

---

---
url: 'https://flux-ui.dev/components/kanban.md'
---

# Kanban

A kanban board for organizing items across draggable columns. Items can be moved between columns and reordered within a column using drag and drop, or with the keyboard. The component is fully controlled. The parent is responsible for updating the data after a `move` event.

::: render
render=../../code/components/kanban/preview.vue
:::

::: tip Keyboard support
Tab to an item, press Space or Enter to grab it, use the arrow keys to move, Enter/Space to drop and Escape to cancel.

When `reorderable-columns` is enabled, Tab to a column header and use ←/→ to move the column left or right.
:::

## Move event

The `move` event contains everything needed to update the data:

## Examples

::: example Basic || A task board with draggable items.
example=../../code/components/kanban/basic.vue
:::

::: example Custom item || Using the default slot to render rich item content.
example=../../code/components/kanban/custom-item.vue
:::

::: example Disabled || A read-only board. Drag-and-drop is disabled.
example=../../code/components/kanban/disabled.vue
:::

::: example Validation || Use `can-move` to reject specific drops.
example=../../code/components/kanban/validation.vue
:::

::: example Reorderable columns || Drag a column header (or focus it and press the left/right arrow keys) to change column order.
example=../../code/components/kanban/reorder-columns.vue
:::

## Used components

* [Column](./column)
* [Item](./item)
* [Pane](../pane)

---

---
url: 'https://flux-ui.dev/components/kanban/column.md'
---

# Kanban column

A single column inside a [`FluxKanban`](./) board. Each column has a unique `column-id` that is referenced by its child items and included in the `move` event when an item is dropped on it. The header shows the `label`, an optional `icon` and a `count` badge, and can be extended with the `actions` slot for things like a quick-add button. Use the `empty` slot for an empty-state message and the `footer` slot for inline actions like adding a new item.

::: render
render=../../code/components/kanban/column/preview.vue
:::

## Examples

::: example Basic || A column with a label and a couple of items.
example=../../code/components/kanban/column/basic.vue
:::

::: example Actions || Adding an action button to the column header via the `actions` slot.
example=../../code/components/kanban/column/actions.vue
:::

::: example Header || Adding an `icon` and a `count` badge to the column header.
example=../../code/components/kanban/column/header.vue
:::

::: example Empty state || Showing a message in the `empty` slot when no items are present.
example=../../code/components/kanban/column/empty.vue
:::

::: example Footer || An inline "Add item" button rendered through the `footer` slot.
example=../../code/components/kanban/column/footer.vue
:::

## Used components

* [Item](./item)
* [Kanban](./)

---

---
url: 'https://flux-ui.dev/components/kanban/item.md'
---

# Kanban item

A draggable item inside a [`FluxKanbanColumn`](./column). The `item-id` uniquely identifies the item and the `column-id` must match the parent column. The kanban board uses both to compute drop targets and to populate the `move` event.

The component itself is intentionally unstyled. It only adds the interaction layer (drag handle, focus ring, drop indicator). The visual surface (padding, background, border, shadows) is up to you. Render any markup inside the default slot; the examples below all wrap their content in a `<div class="card">` with a `<style scoped>` block.

::: tip Keyboard support
An item is focusable. Press Space or Enter to pick it up, use ↑/↓ to reposition within the column, ←/→ to move to a sibling column, Enter/Space to drop and Escape to cancel.
:::

::: render
render=../../code/components/kanban/item/preview.vue
:::

## Examples

::: example Basic || A minimal item with just a title.
example=../../code/components/kanban/item/basic.vue
:::

::: example Rich content || An item with a title, description and a priority badge.
example=../../code/components/kanban/item/rich.vue
:::

## Used components

* [Column](./column)
* [Kanban](./)

---

---
url: 'https://flux-ui.dev/components/table.md'
---

# Table

The table presents data in rows and columns, giving users a structured way to scan and compare information. It is the low-level building block behind the [Data table](../data-table) and can be composed by hand for full control over headers, cells, groups and rows.

::: render
render=../../code/components/table/preview.vue
:::

::: info Accessible loading
While `is-loading` is set the table exposes `aria-busy` on the underlying `<table>`, so assistive technologies announce that the data is updating.
:::

## Examples

::: example Basic || A basic table.
example=../../code/components/table/basic.vue
:::

::: example Pane || A table inside a pane.
example=../../code/components/table/pane.vue
:::

::: example Caption || A table with an caption.
example=../../code/components/table/caption.vue
:::

::: example Caption on top || A table whose caption renders above the table instead of below it.
example=../../code/components/table/caption-top.vue
:::

::: example Sticky || A table with sticky headers.
example=../../code/components/table/sticky.vue
:::

::: example Sticky with bar || A table where the bar and headers stick together.
example=../../code/components/table/sticky-bar.vue
:::

::: example Pinned columns || A wide table with multiple columns pinned to the left and right edges.
example=../../code/components/table/pinned-columns.vue
:::

::: example Column sizing || Columns mixing a fixed width, a min/max range and a shrinking column.
example=../../code/components/table/column-sizing.vue
:::

::: example Numeric alignment || Right-aligned numeric columns with sortable numeric headers.
example=../../code/components/table/numeric.vue
:::

::: example Spanning cells || Section rows whose single cell spans every column.
example=../../code/components/table/spanning.vue
:::

::: example Spanning rows || A first column whose cell spans every row of its track through `rowspan`.
example=../../code/components/table/rowspan.vue
:::

::: example Footer totals || Line items with a footer that sums the amounts across spanning cells.
example=../../code/components/table/invoice.vue
:::

::: example Grouped rows || Rows organized under collapsible groups.
example=../../code/components/table/groups.vue
:::

::: example Sticky groups || Collapsible groups whose column header sticks while scrolling.
example=../../code/components/table/sticky-groups.vue
:::

::: example Stacked content || Cells that stack a primary and secondary line of content.
example=../../code/components/table/stacked.vue
:::

::: example Wrapping rows || A wrapping column whose siblings stay aligned and on a single line.
example=../../code/components/table/wrapping.vue
:::

::: example Consistent height || A short table that keeps a fixed height with filler rows.
example=../../code/components/table/fill.vue
:::

::: example Actions || A table with actions.
example=../../code/components/table/actions.vue
:::

::: example Loading || A table with a loading state.
example=../../code/components/table/loading.vue
:::

::: example Skeleton loading || A table whose `loading` slot replaces the spinner with skeleton rows.
example=../../code/components/table/loading-skeleton.vue
:::

::: example Hoverable || A table with rows that have a hoverable state.
example=../../code/components/table/hoverable.vue
:::

## Used components

* [Pane](../pane)
  * [Body](../pane/body)
* [Spinner](../spinner)
* [Table](../table)
  * [Cell](../table/cell)
  * [Row](../table/row)

---

---
url: 'https://flux-ui.dev/components/table/actions.md'
---

# Table actions

The table actions component provides a place to display actions related to a specific table row, such as editing, viewing, or deleting an item. It keeps row-level controls organized and easy to find without cluttering the data.

::: render
render=../../code/components/table/actions/preview.vue
:::

## Examples

::: example Basic || A basic table actions.
example=../../code/components/table/actions/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/table/bar.md'
---

# Table bar

The table bar renders a full-width row inside a table that spans all columns. It is useful for embedding inline toolbars, action bars, or notices directly within a table structure.

::: render
render=../../code/components/table/bar/preview.vue
:::

::: tip
This component is best used within a [Table](./index).
:::

## Snippet

::: code-group

```vue \[FluxTableBar.vue]
<template>
    <Preview>
        <FluxPane>
            <FluxTable>
                <template #header>
                    <FluxTableRow>
                        <FluxTableHeader>Name</FluxTableHeader>
                        <FluxTableHeader>Status</FluxTableHeader>
                    </FluxTableRow>
                </template>

                <FluxTableBar>
                    <FluxFlex
                        align="center"
                        :gap="9"
                        justify="center">
                        <FluxIcon name="circle-info"/>
                        <span>3 items match the current filter.</span>
                    </FluxFlex>
                </FluxTableBar>

                <FluxTableRow>
                    <FluxTableCell>Project Aurora</FluxTableCell>
                    <FluxTableCell><FluxBadge
                        color="success"
                        label="Active"/></FluxTableCell>
                </FluxTableRow>

                <FluxTableRow>
                    <FluxTableCell>Project Borealis</FluxTableCell>
                    <FluxTableCell><FluxBadge
                        color="success"
                        label="Active"/></FluxTableCell>
                </FluxTableRow>

                <FluxTableRow>
                    <FluxTableCell>Project Cinder</FluxTableCell>
                    <FluxTableCell><FluxBadge
                        color="warning"
                        label="Paused"/></FluxTableCell>
                </FluxTableRow>
            </FluxTable>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxBadge, FluxFlex, FluxIcon, FluxPane, FluxTable, FluxTableBar, FluxTableCell, FluxTableHeader, FluxTableRow } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/table/cell.md'
---

# Table cell

The table cell represents a single cell within the table. It holds individual pieces of data, ensuring information is displayed clearly and consistently across the table's layout.

::: render
render=../../code/components/table/cell/preview.vue
:::

::: warning
This component is best used within a [Row](../table/row).
:::

::: info Column formatting
`align`, `is-numeric` and `no-wrap` set on the column's [Header](./header) apply to every cell in that column. A cell's own `align` overrides the inherited value. Spanning cells (`colspan`) never inherit column formatting, and cells in the rows below a `rowspan` may resolve the wrong column, so set their formatting explicitly when it matters.
:::

## Examples

::: example Basic || A basic table cell.
example=../../code/components/table/cell/basic.vue
:::

::: example Column || A column table cell.
example=../../code/components/table/cell/column.vue
:::

::: example Custom || A table cell with a custom design.
example=../../code/components/table/cell/content.vue
:::

::: example Pinned || A headerless table whose first and last cells pin themselves through the `pinned` override.
example=../../code/components/table/cell/pinned.vue
:::

---

---
url: 'https://flux-ui.dev/components/table/group.md'
---

# Table group

The table group renders a full-width header row that gathers a set of rows under a shared label. It can optionally be made expandable, so its rows collapse and reveal when the header is clicked.

::: render
render=../../code/components/table/group/preview.vue
:::

::: tip
This component is best used within a [Table](./index). For dynamic data, combine it with the [Data table](../data-table)'s `group-by` prop and `#group` slot.
:::

## Examples

::: example Plain || Groups used as static section headers, without collapsing.
example=../../code/components/table/group/plain.vue
:::

::: example Icon || Group headers with an icon before their label.
example=../../code/components/table/group/icon.vue
:::

::: example Expandable || Collapsible groups with their open state bound through `v-model:is-expanded`.
example=../../code/components/table/group/expandable.vue
:::

::: example After slot || Summaries and actions rendered at the end of the group header.
example=../../code/components/table/group/after.vue
:::

---

---
url: 'https://flux-ui.dev/components/table/header.md'
---

# Table header

The table header defines the label for a column within the table. It helps users understand the meaning of the data below it and provides structure and clarity to the table's content.

::: render
render=../../code/components/table/header/preview.vue
:::

::: warning
This component is best used within a [Table](../table).
:::

::: info Accessible sorting
When `is-sortable` is set, the sort trigger is reachable with the keyboard and opens the sort flyout like any other [Menu](../menu). Set `data-type` to `numeric` or `date` so the flyout shows ordering icons that match the column's data instead of the alphabetical default.
:::

::: info Column sizing
Headers define the width of their column. A column with `width` gets that exact width. A column with `is-shrinking` hugs its content. Otherwise the column shares the available space, optionally bounded by `min-width` and/or `max-width`. When the combined minimum widths exceed the table width, the table scrolls horizontally.
:::

::: info Column formatting
`align`, `is-numeric` and `no-wrap` on the header apply to every cell in the column, so there is no need to repeat them per cell. A cell's own `align` overrides the header's; `is-numeric` and `no-wrap` can only be turned on per cell, not off. Spanning cells (`colspan`) never inherit column formatting.
:::

## Examples

::: example Basic || A basic table header.
example=../../code/components/table/header/basic.vue
:::

::: example Shrinking || A table header that shrinks to fit its cell group.
example=../../code/components/table/header/shrinking.vue
:::

::: example Sortable || A table header that can be sorted.
example=../../code/components/table/header/sortable.vue
:::

::: example Data type || Sortable headers whose flyout icons match the column's data type.
example=../../code/components/table/header/data-type.vue
:::

::: example Width || Columns with a fixed, minimum and maximum width.
example=../../code/components/table/header/width.vue
:::

## Used components

* [Flyout](../flyout)
* [Icon](../icon)
* [Separator](../separator)
* [Menu](../menu)
  * [Item](../menu/item)
  * [Group](../menu/group)

---

---
url: 'https://flux-ui.dev/components/table/row.md'
---

# Table row

The table row groups multiple cells together to form a single row of data. It organizes related information into a horizontal sequence, making it easy to scan and compare values across columns.

::: render
render=../../code/components/table/row/preview.vue
:::

::: warning
This component is best used within a [Table](../table).
:::

::: info Keyboard
Clickable rows form a single roving tab stop: `Tab` reaches the last-focused row, `ArrowUp`/`ArrowDown` move between clickable rows, `Home`/`End` jump to the first or last one, and `Enter`/`Space` activate the focused row. Interactive elements inside a row (buttons, links, inputs) keep their own place in the tab order.
:::

## Examples

::: example Basic || A basic table row.
example=../../code/components/table/row/basic.vue
:::

::: example Clickable || A clickable row that emits `row-click`, while ignoring clicks on the button inside a cell.
example=../../code/components/table/row/clickable.vue
:::

::: example Selected || Use `is-selected` to highlight a row as selected.
example=../../code/components/table/row/selected.vue
:::

::: example Colors || Use `color` to tint a row.
example=../../code/components/table/row/colors.vue
:::

---

---
url: 'https://flux-ui.dev/components/table/tree-cell.md'
---

# Table tree cell

The table tree cell renders a tree branch, a round marker and its content in a single cell. Place it instead of a [Cell](./cell) in the column that should show the hierarchy, and give that column a (usually empty) [Header](./header). It draws the guide lines automatically from the `level` of the surrounding tree cells, so all you provide is the depth and whether a node is expandable.

::: render
render=../../code/components/table/tree-cell/preview.vue
:::

::: tip Expansion stays in your app
The tree cell holds no expansion state. It only draws the marker and emits `toggle` when an expandable marker is clicked. Keep your own expanded/collapsed state, flatten your tree into the rows you want to render, and pass each node its `level` and `is-expanded`. Collapsing a node simply means rendering fewer rows.
:::

::: warning
This component is best used within a [Row](./row), as the first cell of a column that has a matching [Header](./header).
:::

## Examples

::: example File tree || A collapsible file tree whose expanded state lives in the page, driving which rows render.
example=../../code/components/table/tree-cell/preview.vue
:::

::: example Coloured markers || The same tree with a `color` per level, mixing `FluxColor` names with your own palette.
example=../../code/components/table/tree-cell/colored.vue
:::

::: example Custom colours || Passing arbitrary CSS colour strings, so each node carries its own hex value.
example=../../code/components/table/tree-cell/custom-color.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/ticks.md'
---

# Ticks

The ticks component displays visual tick marks along a slider track to help users understand the scale and spacing of values. It generates both major and minor ticks based on the slider's lower and upper bounds, placing them proportionally along the track.

::: render
render=../code/components/ticks/preview.vue
:::

## Examples

::: example Basic || A basic ticks track.
example=../code/components/ticks/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/timeline.md'
---

# Timeline

The timeline component serves as the main container for organizing and displaying a sequence of events or steps. It should always be used as the parent component of FluxTimelineItem, ensuring each item is properly aligned and visually connected within the timeline.

::: render
render=../../code/components/timeline/preview.vue
:::

## Examples

::: example Basic || A basic timeline.
example=../../code/components/timeline/basic.vue
:::

::: example Pane || A timeline inside a pane.
example=../../code/components/timeline/pane.vue
:::

---

---
url: 'https://flux-ui.dev/components/timeline/item.md'
---

# Timeline item

The timeline item represents a single event within the timeline. It aligns its content with the timeline's structure to illustrate the order and progression of events.

::: render
render=../../code/components/timeline/item/preview.vue
:::

::: warning
This component is best used within a [Timeline](../timeline).
:::

## Examples

::: example Basic || A basic timeline item.
example=../../code/components/timeline/item/basic.vue
:::

::: example Pane || A basic timeline item inside a pane.
example=../../code/components/timeline/item/pane.vue
:::

::: example Colored markers || Use the `color` prop to convey the meaning of each event.
example=../../code/components/timeline/item/colored.vue
:::

::: example With photo || Set `photo` to render an avatar as the marker instead of an icon.
example=../../code/components/timeline/item/photo.vue
:::

::: example Photo with icon || Combine `photo` and `icon` to overlay an activity icon on top of the avatar.
example=../../code/components/timeline/item/photo-icon.vue
:::

::: example Plain markers || Without `icon` or `photo` the item renders a minimal marker on the line.
example=../../code/components/timeline/item/plain.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/tree-view.md'
---

# Tree view

A standalone tree view component that renders a hierarchical list of nodes with expand/collapse support. Nodes emit `click` and `dblclick` events so the parent can react to user interaction. The tree is rendered inline (not in a popup) and includes connecting lines. Every node ends its guide line with a marker of the same size: nodes with children render it as the expand toggle holding the chevron, leaf nodes as a plain circle. Markers can be colored per node or per depth level.

::: render
render=../code/components/tree-view/preview.vue
:::

## Option object

Each entry in the `options` array (and nested `children` arrays) is a `FluxTreeViewOption`:

## Keyboard navigation

## Accessibility

The tree is a single composite widget: the `role="tree"` container is the only tab stop and exposes the highlighted node through `aria-activedescendant`, while each node carries `role="treeitem"` with `aria-level`, `aria-selected` and (when it has children) `aria-expanded`. Parent → child grouping is conveyed with `aria-owns` rather than nested `role="group"` wrappers, so the flat DOM stays valid for assistive tech. Set a descriptive `aria-label` to name the tree.

The highlight is tracked by node identity: when the visible set changes (for example a node above the highlight collapses), the highlight stays on the same node instead of jumping to whatever now occupies that position.

## Examples

::: example Basic || A tree view with per-level colors.
example=../code/components/tree-view/basic.vue
:::

::: example Expanded depth || With `expanded-depth`, the tree opens with more than just its roots visible. `2` shows the roots and their children.
example=../code/components/tree-view/expanded-depth.vue
:::

::: example Events || Responding to click and double-click events.
example=../code/components/tree-view/events.vue
:::

::: example Trailing || Rendering a badge after each node label with the `trailing` slot.
example=../code/components/tree-view/trailing.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/media.md'
---

# Media & people

The media and people components make faces and imagery feel at home, from avatars and personas to galleries and focal-point cropping.

---

---
url: 'https://flux-ui.dev/components/avatar.md'
---

# Avatar

The avatar displays an image, initials, or an icon to represent a user or entity. It renders the appropriate content based on the props you provide.

::: render
render=../code/components/avatar/preview.vue
:::

::: tip
To display a person's name and title along with their avatar, consider using the [Persona](./persona) component.
:::

::: tip
The `status-icon` prop works together with `status`: the icon replaces the status dot and takes the status color, so `status` must be set for the icon to appear.
:::

::: tip Accessibility
When a `src` fails to load, the avatar automatically falls back to its initials or icon, so a broken image is never shown. The `role="img"` attribute is only applied when `type` is `none`; for interactive avatars (`button`, `link`, `route`) the underlying element keeps its native role.
:::

## Examples

::: example Image with status || Avatars can include statuses to indicate conditions such as online status.
example=../code/components/avatar/image-with-status.vue
:::

::: example Status icon || Set a `status-icon` to replace the status dot with an icon, colored by the status, to convey richer presence states.
example=../code/components/avatar/status-with-icon.vue
:::

::: example Initials || In the absence of an image, avatars can default to using initials.
example=../code/components/avatar/initials.vue
:::

::: example Icon || When no image is available, you can use an icon as a fallback instead of initials.
example=../code/components/avatar/icon.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/avatar-group.md'
---

# Avatar group

The Avatar group component stacks multiple avatars into an overlapping row, optionally collapsing the overflow into a "+N" chip. It is useful for showing the members of a team, the participants of a conversation, or the assignees of a task. Avatars placed in the default slot inherit the group's `size`, so they are sized uniformly without extra configuration. Avatars stack from left to right, and the gap between them is cut out rather than painted, so the group blends into any background.

::: render
render=../code/components/avatar-group/preview.vue
:::

::: tip Accessibility
The group is exposed with `role="group"`; pass `aria-label` to describe it for assistive technology. When avatars overflow, the "+N" indicator carries a tooltip listing the names of the hidden avatars (taken from their `alt` or `fallback-initials`), so the collapsed members remain discoverable.
:::

## Examples

::: example Basic || A basic stack of avatars.
example=../code/components/avatar-group/basic.vue
:::

::: example Overflow || A stack that collapses the overflow into a "+N" chip.
example=../code/components/avatar-group/overflow.vue
:::

::: example Labelled || A labelled group whose "+N" indicator reveals the names of the hidden members on hover.
example=../code/components/avatar-group/labelled.vue
:::

::: example On a background || The gap between avatars is cut out, so the group works on any background colour.
example=../code/components/avatar-group/on-background.vue
:::

## Used components

* [Avatar](./avatar)

---

---
url: 'https://flux-ui.dev/components/focal-point/editor.md'
---

# Focal point editor

The focal point editor lets users set the focal point of an image by dragging or using the keyboard, with a live preview of the result. The chosen point is exposed through `v-model`.

::: render
render=../../code/components/focal-point/editor/preview.vue
:::

::: tip Accessibility
The editor is focusable and exposed as a 2D slider. Once focused, the focal point can be moved with the arrow keys (hold Shift for larger steps), and Home / End jump to the top-left and bottom-right corners. The current position is announced through `aria-valuetext`.
:::

## Examples

::: example Editor
example=../../code/components/focal-point/editor/editor.vue
:::

## Used components

* [Button](../button)
  * [Secondary](../button/secondary)
* [Layout](../layout)
  * [Spacer](../layout/spacer)
* [Pane](../pane)
  * [Body](../pane/body)
  * [Footer](../pane/footer)

---

---
url: 'https://flux-ui.dev/components/focal-point/image.md'
---

# Focal point image

The focal point image renders an image positioned around a given focal point, so the most important part stays visible when the image is cropped to its container.

::: render
render=../../code/components/focal-point/image/preview.vue
:::

## Examples

::: example Editor
example=../../code/components/focal-point/image/image.vue
:::

---

---
url: 'https://flux-ui.dev/components/gallery.md'
---

# Gallery

The Gallery component is used to display multiple media entities in a grid. It also allows the user to upload new media to it and control them further.

::: render
render=../../code/components/gallery/preview.vue
:::

## Examples

::: example Basic || A basic gallery.
example=../../code/components/gallery/basic.vue
:::

::: example Pending || A gallery with pending items
example=../../code/components/gallery/pending.vue
:::

::: example Edit || A gallery that can be edited.
example=../../code/components/gallery/edit.vue
:::

## Used components

* [Dropzone](../drop-zone)
* [Gallery](../gallery)
  * [Item](./item)
* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/gallery/item.md'
---

# Gallery Item

The gallery item represents a single image within the gallery. It displays the image in a consistent size and aspect ratio, ensuring a clean and uniform appearance across the grid. Gallery items are designed to showcase visual content clearly and maintain a cohesive layout within the gallery.

::: render
render=../../code/components/gallery/item/preview.vue
:::

::: tip
This component is best used within a [Gallery](../gallery).
:::

## Examples

::: example Basic || A basic gallery item.
example=../../code/components/gallery/item/basic.vue
:::

::: example Pending || A gallery item that is pending.
example=../../code/components/gallery/item/pending.vue
:::

::: example Delete || A gallery item that can be deleted.
example=../../code/components/gallery/item/delete.vue
:::

## Used components

* [Focal point](../focal-point/image)
* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/persona.md'
---

# Persona

The persona combines an avatar with a name and title to represent a user or entity. The avatar can show an image, initials, or an icon.

::: render
render=../code/components/persona/preview.vue
:::

::: tip
In compact mode the name and title are hidden, so the persona button exposes the `name` as its `aria-label` to keep it accessible.
:::

## Examples

::: example Basic || A basic persona.
example=../code/components/persona/basic.vue
:::

::: example Compact || A compact persona.
example=../code/components/persona/compact.vue
:::

::: example Flyout || A persona with a flyout.
example=../code/components/persona/flyout.vue
:::

## Used components

* [Avatar](./avatar)

---

---
url: 'https://flux-ui.dev/components/layout.md'
---

# Layout

The layout components organize and align content in a clear, structured way. Use them to build responsive layouts that stay consistent across screen sizes and content types.

---

---
url: 'https://flux-ui.dev/components/adaptive-group.md'
---

# Adaptive group

A group that coordinates multiple [`FluxAdaptiveSlot`](./adaptive-slot) items so they collapse in a predictable, priority-based order instead of the one with the widest default content collapsing first. The group observes its own width and the desired widths of each child, and decides which items remain in their default slot and which switch to their fallback.

Items collapse in ascending order of their `priority` prop. The lowest-priority item that is still default is the first to switch to its fallback when space runs out; the highest-priority item keeps its default slot the longest.

::: render
render=../code/components/adaptive-slot/preview.vue
:::

::: tip
The ordering is strict: if two items have the same priority, the one declared first in the template collapses first. Changing a priority at runtime is reactive; the group re-evaluates immediately.
:::

## Snippet

::: code-group

```vue \[FluxAdaptiveGroup.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 520px); resize: horizontal; overflow: auto">
            <FluxPaneBody>
                <FluxAdaptiveGroup :gap="9">
                    <FluxAdaptiveSlot :priority="2">
                        <FluxSecondaryButton
                            icon-leading="pen"
                            label="Edit"/>

                        <template #fallback>
                            <FluxSecondaryButton icon-leading="pen"/>
                        </template>
                    </FluxAdaptiveSlot>

                    <FluxAdaptiveSlot :priority="3">
                        <FluxSecondaryButton
                            icon-leading="copy"
                            label="Duplicate"/>

                        <template #fallback>
                            <FluxSecondaryButton icon-leading="copy"/>
                        </template>
                    </FluxAdaptiveSlot>

                    <FluxAdaptiveSlot :priority="1">
                        <FluxSecondaryButton
                            icon-leading="trash"
                            label="Delete"/>

                        <template #fallback>
                            <FluxSecondaryButton icon-leading="trash"/>
                        </template>
                    </FluxAdaptiveSlot>

                    <FluxAdaptiveSlot :priority="4">
                        <FluxPrimaryButton
                            icon-leading="circle-check"
                            label="Approve"/>

                        <template #fallback>
                            <FluxPrimaryButton icon-leading="circle-check"/>
                        </template>
                    </FluxAdaptiveSlot>
                </FluxAdaptiveGroup>
            </FluxPaneBody>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxAdaptiveGroup, FluxAdaptiveSlot, FluxPane, FluxPaneBody, FluxPrimaryButton, FluxSecondaryButton } from '@flux-ui/components';
</script>

```

:::

## Used components

* [Adaptive slot](./adaptive-slot)

---

---
url: 'https://flux-ui.dev/components/adaptive-slot.md'
---

# Adaptive slot

The adaptive slot shows its default content whenever it fits within the space the component is allocated by its parent layout. When the default content is wider than the available space, the fallback content is rendered instead. This is useful for toolbars where buttons should collapse to icon-only variants, or even disappear, as horizontal space shrinks.

Wrap multiple adaptive slots inside a [`FluxAdaptiveGroup`](./adaptive-group) to control the order in which they collapse.

::: render
render=../code/components/adaptive-slot/preview.vue
:::

::: tip
When used standalone (without a `FluxAdaptiveGroup`), the component measures its own allocated width. Multiple standalone slots in the same parent each decide independently; the one with the widest default content typically collapses first.
:::

::: warning
Place the component inside a layout where it is allowed to shrink below its natural width. In a standalone flex context the default `flex-shrink: 1` is enough; in a grid context use `minmax(0, auto)` or similar. Inside a `FluxAdaptiveGroup` this is handled automatically.
:::

## Examples

::: example Standalone || Two buttons that each decide on their own whether to show their label based on the space they are allocated.
example=../code/components/adaptive-slot/standalone.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/aspect-ratio.md'
---

# Aspect ratio

A layout component that ensures content maintains a consistent aspect ratio, providing a reliable way to preserve proportional dimensions across different layouts. It is particularly useful for scenarios like embedding media or designing responsive elements, where maintaining a specific shape is essential for visual harmony and adaptability.

::: render
render=../../code/components/layout/aspect-ratio/preview.vue
:::

## Examples

::: example Basic || A basic aspect ratio.
example=../../code/components/layout/aspect-ratio/basic.vue
:::

::: example Video placeholder || A 16:9 placeholder commonly used for video thumbnails.
example=../../code/components/layout/aspect-ratio/video.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/container.md'
---

# Container

The primary container which dynamically changes widths based on the viewport.

::: render
render=../../code/components/layout/container/preview.vue
:::

## Examples

::: example Basic || A basic container.
example=../../code/components/layout/container/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/divider.md'
---

# Divider

This component serves as a horizontal content divider, offering the flexibility to include custom content or default to displaying a simple line. The content alignment can be adjusted to the start, center, or end based on the configuration.

For a plain vertical separation between inline elements, use [Separator](./separator) instead.

::: render
render=../code/components/divider/preview.vue
:::

## Examples

::: example Clear || A standalone divider.
example=../code/components/divider/clear.vue
:::

::: example Button || A divider with a button at the end.
example=../code/components/divider/button.vue
:::

::: example Icon || A divider with a centered icon.
example=../code/components/divider/icon.vue
:::

---

---
url: 'https://flux-ui.dev/components/fader.md'
---

# Fader

The fader fades between multiple items on a set interval, for example to cycle through image slides in a header.

::: render
render=../code/components/fader/preview.vue
:::

::: tip Accessibility
The fader is exposed as a carousel (`role="group"` with `aria-roledescription="carousel"`) and each item as a slide. Inactive slides are marked `aria-hidden`. Autoplay pauses on hover by default (`pause-on-hover`), and you can pause it externally with `is-paused`. Autoplay only runs when there is more than one item.
:::

## Examples

::: example Basic || A simple and basic fader.
example=../code/components/fader/basic.vue
:::

::: example Autoplay || Autoplay advances the fader on the configured `interval`. With `pause-on-hover` it stops while the pointer is over it.
example=../code/components/fader/autoplay.vue
:::

::: example Manual navigation || Disable autoplay and drive the fader from your own controls. Slot bindings expose `next` and `previous`.
example=../code/components/fader/manual.vue
:::

## Used components

* [Fader item](./fader-item)

---

---
url: 'https://flux-ui.dev/components/fader-item.md'
---

# Fader item

A fader item is a single slide within a [Fader](./fader). Each item is shown in turn according to the fader's interval.

::: render
render=../code/components/fader-item/preview.vue
:::

::: tip
This component is best used within a [Fader](./fader).
:::

::: tip Accessibility
Each item is exposed as a slide (`aria-roledescription="slide"`). Items that are not currently visible are automatically marked `aria-hidden`, so assistive technology only announces the active slide.
:::

## Snippet

::: code-group

```vue \[FluxFaderItem.vue]
<template>
    <FluxAspectRatio
        :aspect-ratio="16 / 9"
        style="width: 100%;">
        <FluxFader :interval="3000">
            <FluxFaderItem>
                <img
                    src="/assets/demo/image-1.jpg"
                    alt="">
            </FluxFaderItem>

            <FluxFaderItem>
                <img
                    src="/assets/demo/image-2.jpg"
                    alt="">
            </FluxFaderItem>

            <FluxFaderItem>
                <img
                    src="/assets/demo/image-3.jpg"
                    alt="">
            </FluxFaderItem>
        </FluxFader>
    </FluxAspectRatio>
</template>

<script
    lang="ts"
    setup>
    import { FluxAspectRatio, FluxFader, FluxFaderItem } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/layout/flex.md'
---

# Flex

A primitive layout component that maps directly to CSS flexbox. Use it to compose any flex layout (horizontal or vertical, wrapping or not) with full control over alignment and justification.

::: render
render=../../../code/components/layout/flex/preview.vue
:::

::: tip
For controlling individual children inside a `FluxFlex` container (like making one child grow or shrink), use [`FluxFlexItem`](./item).
:::

## Available variants

* [Item](./item) (for controlling individual children inside a flex container)

### Stack

Specialised flex containers for stacking specific kinds of content:

* [Action](./action)
* [Badge](./badge)
* [Button](./button)
* [Info](./info)
* [Notice](./notice)
* [Tag](./tag)

## Examples

::: example Horizontal || A horizontal flex container.
example=../../../code/components/layout/flex/horizontal.vue
:::

::: example Vertical || A vertical flex container.
example=../../../code/components/layout/flex/vertical.vue
:::

::: example Align and justify || Combine `align` and `justify` to center content on both axes.
example=../../../code/components/layout/flex/align-justify.vue
:::

::: example Wrapping || Use `wrap` to allow children to flow onto multiple lines.
example=../../../code/components/layout/flex/wrap.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/flex/item.md'
---

# Flex item

A transparent helper for controlling the `flex-grow`, `flex-shrink`, and `flex-basis` of a child within a [`FluxFlex`](./) container. When you pass a single child, `FluxFlexItem` does not introduce an extra DOM element; the flex styles are merged onto the child directly.

::: render
render=../../../code/components/layout/flex/item/preview.vue
:::

## Examples

::: example Grow || Use `grow` to let an item take up the remaining space.
example=../../../code/components/layout/flex/item/grow.vue
:::

::: example Basis || Set an explicit `basis` to control the initial size of an item.
example=../../../code/components/layout/flex/item/basis.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/flex/action.md'
---

# Action stack

The action stack component is a horizontal container for action buttons with built-in keyboard navigation. It uses a focus zone to enable arrow key navigation between child elements, making it accessible for keyboard users.

::: render
render=../../../code/components/layout/flex/action/preview.vue
:::

## Examples

::: example Basic || A basic action stack.
example=../../../code/components/layout/flex/action/basic.vue
:::

## Used components

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/flex/badge.md'
---

# Badge stack

The badge stack arranges badges in a horizontal line with consistent spacing. It's ideal for displaying multiple labels or status indicators side-by-side in a clean and compact manner.

::: render
render=../../../code/components/layout/flex/badge/preview.vue
:::

## Examples

::: example Basic || A basic badge stack.
example=../../../code/components/layout/flex/badge/basic.vue
:::

## Used components

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/flex/button.md'
---

# Button stack

The button stack arranges buttons along a chosen axis. Whether stacked vertically or aligned horizontally, it ensures clear spacing and visual balance between related actions.

::: render
render=../../../code/components/layout/flex/button/preview.vue
:::

## Examples

::: example Horizontal || A horizontal button stack.
example=../../../code/components/layout/flex/button/horizontal.vue
:::

::: example Vertical || A vertical button stack.
example=../../../code/components/layout/flex/button/vertical.vue
:::

## Used components

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/flex/info.md'
---

# Info stack

The info stack displays multiple info components in a vertical stack. It provides a clear, readable way to present informational messages in sequence without overwhelming the layout.

::: render
render=../../../code/components/layout/flex/info/preview.vue
:::

## Examples

::: example Basic || A basic info stack.
example=../../../code/components/layout/flex/info/basic.vue
:::

## Used components

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/flex/notice.md'
---

# Notice stack

The notice stack organizes notices in a vertical flow. This helps group related alerts or system messages while maintaining structure and readability.

::: render
render=../../../code/components/layout/flex/notice/preview.vue
:::

## Examples

::: example Basic || A basic notice stack.
example=../../../code/components/layout/flex/notice/basic.vue
:::

## Used component

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/flex/tag.md'
---

# Tag stack

The tag stack arranges tags horizontally with uniform spacing. It keeps lists of tags neat, scannable, and visually organized even when several are displayed together.

::: render
render=../../../code/components/layout/flex/tag/preview.vue
:::

## Examples

::: example Basic || A basic tag stack.
example=../../../code/components/layout/flex/tag/basic.vue
:::

## Used component

* [Flex](./)

---

---
url: 'https://flux-ui.dev/components/layout/grid.md'
---

# Grid

The grid creates responsive layouts that adapt to any screen size. Its equal-width columns can be combined and rearranged to build complex page designs.

::: render
render=../../../code/components/layout/grid/preview.vue
:::

## Examples

::: example Basic || A basic grid.
example=../../../code/components/layout/grid/basic.vue
:::

::: example Responsive || Each column accepts breakpoint props (`xs`, `sm`, `md`, `lg`, `xl`) so the layout adapts to the viewport.
example=../../../code/components/layout/grid/responsive.vue
:::

::: tip
The class `column-example` is used in the documentation to display the columns.
:::

---

---
url: 'https://flux-ui.dev/components/layout/grid/column.md'
---

# Grid column

The grid column is used to arrange content within a grid layout. It defines how elements are positioned across the available columns, helping maintain clear alignment and consistent spacing. Using grid columns ensures that content stays organized and visually balanced across different screen sizes.

::: render
render=../../../code/components/layout/grid/column/preview.vue
:::

::: warning
This component only works properly inside a [Grid](../grid).
:::

## Examples

::: example Basic || A basic grid.
example=../../../code/components/layout/grid/column/basic.vue
:::

::: tip
The class `column-example` is used in the documentation to display the columns.
:::

---

---
url: 'https://flux-ui.dev/components/item.md'
---

# Item

An item is a flexible list entry used to display structured content such as a media element, text, and actions. It is composed of several sub-components that each handle a specific area of the item.

::: render
render=../../code/components/item/preview.vue
:::

## Examples

::: example Clickable || Wrap an item in a clickable pane to turn it into an interactive list entry. The whole row highlights on hover.
example=../../code/components/item/clickable.vue
:::

::: example Complete || An item composed of media, content and actions stacked together.
example=../../code/components/item/complete.vue
:::

::: example Notifications || A notification feed with a leading icon, message, timestamp and a dismiss action.
example=../../code/components/item/notifications.vue
:::

::: example Settings || A settings list where each row pairs a description with a switch.
example=../../code/components/item/settings.vue
:::

::: example Control || With is-control the whole row becomes the label for its form control. Click anywhere to toggle.
example=../../code/components/item/control.vue
:::

::: example Selectable || A multi-select list where the whole row toggles the checkbox, thanks to is-control.
example=../../code/components/item/selectable.vue
:::

::: example Integrations || Connected services with a status badge and a toggle to connect or disconnect.
example=../../code/components/item/integrations.vue
:::

::: example Transactions || A transaction list with a directional icon and a trailing amount.
example=../../code/components/item/transactions.vue
:::

::: example Downloads || Active downloads with an inline progress bar and a cancel action.
example=../../code/components/item/downloads.vue
:::

## Snippet

::: code-group

```vue \[FluxItem.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 420px)">
            <FluxItemStack>
                <FluxItem
                    v-for="person in people"
                    :key="person.name">
                    <FluxItemMedia
                        is-center
                        :size="40">
                        <FluxAvatar
                            :alt="person.name"
                            :fallback-icon="person.avatar ? undefined : 'user'"
                            :src="person.avatar"
                            :size="40"/>
                    </FluxItemMedia>

                    <FluxItemContent is-center>
                        <strong>{{ person.name }}</strong>
                        <span style="font-size: .875rem; opacity: .6">{{ person.role }}</span>
                    </FluxItemContent>
                </FluxItem>
            </FluxItemStack>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxAvatar, FluxItem, FluxItemContent, FluxItemMedia, FluxItemStack, FluxPane } from '@flux-ui/components';

    const people = [
        {name: 'Bas Milius', role: 'Engineer', avatar: 'https://avatars.githubusercontent.com/u/978257?v=4'},
        {name: 'Jane Doe', role: 'Designer', avatar: null},
        {name: 'John Doe', role: 'Product manager', avatar: null}
    ];
</script>

```

:::

## Available sub-components

* [Content](./content)
* [Media](./media)
* [Actions](./actions)

## Used components

* [Flex](../layout/flex/)

---

---
url: 'https://flux-ui.dev/components/item/actions.md'
---

# Item actions

The item actions area holds buttons or other controls that act on the item, such as edit or delete buttons.

::: render
render=../../code/components/item/actions/preview.vue
:::

::: tip
This component is best used within an [Item](./index).
:::

## Examples

::: example Buttons || Actions are not limited to icon buttons. Use regular buttons for primary choices.
example=../../code/components/item/actions/buttons.vue
:::

## Snippet

::: code-group

```vue \[FluxItemActions.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 480px)">
            <FluxItem>
                <FluxItemMedia
                    is-center
                    :size="40">
                    <FluxAvatar
                        alt="Bas Milius"
                        :size="40"
                        src="https://avatars.githubusercontent.com/u/978257?v=4"/>
                </FluxItemMedia>

                <FluxItemContent is-center>
                    <strong>Bas Milius</strong>
                    <span style="font-size: .875rem; opacity: .6">Engineer</span>
                </FluxItemContent>

                <FluxItemActions is-center>
                    <FluxAction
                        icon="pen"
                        aria-label="Edit"/>
                    <FluxAction
                        is-destructive
                        icon="trash"
                        aria-label="Remove"/>
                </FluxItemActions>
            </FluxItem>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxAction, FluxAvatar, FluxItem, FluxItemActions, FluxItemContent, FluxItemMedia, FluxPane } from '@flux-ui/components';
</script>

```

:::

## Used components

* [Action bar](../action-bar)

---

---
url: 'https://flux-ui.dev/components/item/content.md'
---

# Item content

The item content area holds the main textual or inline content of an item, such as a title, description, or metadata.

::: render
render=../../code/components/item/content/preview.vue
:::

::: tip
This component is best used within an [Item](./index).
:::

## Examples

::: example Rich content || Combine a title, description and inline metadata within the content area.
example=../../code/components/item/content/rich.vue
:::

::: example Title variations || Content can be just a title, or a title with a supporting description.
example=../../code/components/item/content/states.vue
:::

::: example Centered || Use `is-center` to vertically center the content next to a taller media element.
example=../../code/components/item/content/centered.vue
:::

## Snippet

::: code-group

```vue \[FluxItemContent.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 420px)">
            <FluxItem>
                <FluxItemMedia
                    is-center
                    :size="40">
                    <FluxAvatar
                        alt="Bas Milius"
                        :size="40"
                        src="https://avatars.githubusercontent.com/u/978257?v=4"/>
                </FluxItemMedia>

                <FluxItemContent is-center>
                    <strong>Bas Milius</strong>
                    <span style="font-size: .875rem; opacity: .6">Engineer</span>
                </FluxItemContent>
            </FluxItem>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxAvatar, FluxItem, FluxItemContent, FluxItemMedia, FluxPane } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/item/media.md'
---

# Item media

The item media area holds a visual element such as an avatar, icon, or image that accompanies the item content.

::: render
render=../../code/components/item/media/preview.vue
:::

::: tip
This component is best used within an [Item](./index).
:::

## Examples

::: example Variants || The media area can hold an avatar, a boxed icon or a raw image.
example=../../code/components/item/media/variants.vue
:::

::: example Sizes || Control the size of the media area with the `size` prop.
example=../../code/components/item/media/sizes.vue
:::

::: example Alignment || Use `is-center` to vertically center the media next to multi-line content.
example=../../code/components/item/media/alignment.vue
:::

## Snippet

::: code-group

```vue \[FluxItemMedia.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 420px)">
            <FluxItem>
                <FluxItemMedia
                    is-center
                    :size="48">
                    <FluxAvatar
                        alt="Project icon"
                        fallback-icon="rocket"
                        :size="48"/>
                </FluxItemMedia>

                <FluxItemContent is-center>
                    <strong>Project Aurora</strong>
                    <span style="font-size: .875rem; opacity: .6">Created last week</span>
                </FluxItemContent>
            </FluxItem>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxAvatar, FluxItem, FluxItemContent, FluxItemMedia, FluxPane } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/item/stack.md'
---

# Item stack

The item stack renders a vertical list of [Items](./index) with no gap between them, creating a cohesive grouped list appearance.

::: render
render=../../code/components/item/stack/preview.vue
:::

## Examples

::: example Rich list || A stack of items with media, content and actions forms a cohesive list.
example=../../code/components/item/stack/rich.vue
:::

## Snippet

::: code-group

```vue \[FluxItemStack.vue]
<template>
    <Preview>
        <FluxPane style="width: min(100%, 420px)">
            <FluxItemStack>
                <FluxItem
                    v-for="item in items"
                    :key="item.label">
                    <FluxItemContent is-center>
                        <strong>{{ item.label }}</strong>
                        <span style="font-size: .875rem; opacity: .6">{{ item.value }}</span>
                    </FluxItemContent>
                </FluxItem>
            </FluxItemStack>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxItem, FluxItemContent, FluxItemStack, FluxPane } from '@flux-ui/components';

    const items = [
        {label: 'Status', value: 'Active'},
        {label: 'Created', value: 'January 1, 2025'},
        {label: 'Updated', value: 'March 7, 2026'}
    ];
</script>

```

:::

## Used components

* [Flex](../layout/flex/)

---

---
url: 'https://flux-ui.dev/components/overflow-bar.md'
---

# Overflow bar

The overflow bar is a layout component that shows as many of its child items as possible within the available space. Items that do not fit are hidden and passed to the `overflow` slot, where you can render them in a flyout or dropdown. This is particularly useful in toolbars and filter bars.

::: render
render=../code/components/overflow-bar/preview.vue
:::

## Examples

::: example With flyout || Hidden items can be revealed in a flyout menu through the `overflow` slot.
example=../code/components/overflow-bar/with-flyout.vue
:::

## Used components

* [Dynamic view](./dynamic-view)

---

---
url: 'https://flux-ui.dev/components/separator.md'
---

# Separator

The separator component is a visual divider used to separate content on a page. It has the ability to be oriented along the x-axis or y-axis, depending on the value of its axis property.

::: render
render=../code/components/separator/preview.vue
:::

## Examples

::: example Horizontal || A horizontal separator.
example=../code/components/separator/horizontal.vue
:::

::: example Vertical || A vertical separator.
example=../code/components/separator/vertical.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/spacer.md'
---

# Spacer

A component that fills remaining space in its parent container, helpful in creating evenly divided button rows in responsive layouts. Spacers are invisible elements and are made visible for demo purposes.

::: render
render=../../code/components/layout/spacer/preview.vue
:::

## Examples

::: tip
The class `spacer-example` is used in the documentation to display the columns.
:::

::: example Horizontal || A horizontal spacer.
example=../../code/components/layout/spacer/horizontal.vue
:::

::: example Vertical || A vertical spacer.
example=../../code/components/layout/spacer/vertical.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/spacing.md'
---

# Spacing

The spacing component adds a div within its parent flex container with a predefined size. It works in both column and row flex containers. The sizes are predefined. Spacings are invisible elements and are made visible for demo purposes.

::: render
render=../../code/components/layout/spacing/preview.vue
:::

## Examples

::: tip
The class `spacing-example` is used in the documentation to display the columns.
:::

::: example Horizontal || A horizontal spacing.
example=../../code/components/layout/spacing/horizontal.vue
:::

::: example Vertical || A vertical spacing.
example=../../code/components/layout/spacing/vertical.vue
:::

---

---
url: 'https://flux-ui.dev/components/layout/split-view.md'
---

# Split view

A resizable container that splits its space between two or more `FluxSplitViewPane` children. Drag the handle between panes with mouse, touch, or keyboard to resize. Optionally persist sizes via `remember-key`.

::: render
render=../../../code/components/layout/split-view/preview.vue
:::

::: tip
Each pane is configured via props on `FluxSplitViewPane`. See the [pane reference](./pane).
:::

::: tip
Each resize handle is exposed as a focusable `role="separator"` with a descriptive `aria-label` and a percentage-based `aria-valuenow` / `aria-valuetext`, so the split ratio is announced to assistive technologies. Give each pane a stable `:key` when toggling panes with `v-if` so the remaining panes keep their sizes.
:::

## Examples

::: example Horizontal || A horizontal split with two panes.
example=../../../code/components/layout/split-view/horizontal.vue
:::

::: example Vertical || A vertical split.
example=../../../code/components/layout/split-view/vertical.vue
:::

::: example Persisted || Use `remember-key` to keep pane sizes between sessions.
example=../../../code/components/layout/split-view/persisted.vue
:::

::: example Nested || Nest split views to build complex layouts.
example=../../../code/components/layout/split-view/nested.vue
:::

## Keyboard

| Key                                      | Action                                       |
|------------------------------------------|----------------------------------------------|
| `Arrow Left` / `Arrow Up`                | Shrink the pane before the focused handle    |
| `Arrow Right` / `Arrow Down`             | Grow the pane before the focused handle      |
| `Shift + Arrow`                          | Larger step (64px instead of 16px)           |
| `Home`                                   | Collapse the pane to its `minSize`           |
| `End`                                    | Expand the pane to its `maxSize`             |

---

---
url: 'https://flux-ui.dev/components/layout/split-view/pane.md'
---

# Split view pane

A child of `FluxSplitView`. Configure the initial size, min, max, and whether the trailing handle is interactive.

::: tip
Panes without an explicit `default-size` evenly share the remaining space.
:::

---

---
url: 'https://flux-ui.dev/components/surfaces.md'
---

# Overlays & surfaces

The overlay and surface components layer content above the page, from panes and flyouts to overlays, slide-overs and windows.

---

---
url: 'https://flux-ui.dev/components/flyout.md'
---

# Flyout

A flyout provides a hidden interactable pane that can be toggled open or closed by an opener element. Flyouts can be positioned vertically or horizontally and support configurable dimensions for enhanced flexibility.

::: render
render=../code/components/flyout/preview.vue
:::

::: tip
The flyout pane is exposed as a `role="dialog"` and traps focus while open. Provide a `label` so assistive technology can announce the pane.
:::

## Examples

::: example Menu || Flyouts are great for rendering hidden menus.
example=../code/components/flyout/menu.vue
:::

::: example Information || More information about an entity can also be shown within a flyout.
example=../code/components/flyout/information.vue
:::

## Used components

* [Pane](./pane)

---

---
url: 'https://flux-ui.dev/components/overlay.md'
---

# Overlay

Overlays can be used to reveal larger contents or options that are hidden behind a button or a similar component. The content is animated on top of the document and the rest of the interface is blocked.

::: render
render=../code/components/overlay/preview.vue
:::

::: warning Requires FluxRoot
This overlay renders through a parent [`<FluxRoot>`](./root). Without one in your app, nothing appears and no error is thrown.
:::

## Examples

::: example Basic || A basic overlay.
example=../code/components/overlay/basic.vue
:::

::: example Tabs || An overlay with a sticky header and tab bar.
example=../code/components/overlay/tabs.vue
:::

::: example Re-authenticatie || A re-authentication overlay.
example=../code/components/overlay/authenticate.vue
:::

## Router-driven

Pair the overlay with [Vue Router](../guide/introduction/installation/vue-router) to open it through navigation. Define an `overlay` named view on every route that should appear inside the overlay, and render a single `<RouterView name="overlay"/>` from your top-level layout.

The layout watches `route.matched` for the first record that exposes the `overlay` view. When such a record is matched the `<RouterView>` renders inside the overlay; otherwise the overlay stays empty and the transition closes it.

::: code-group

```ts \[router.ts]
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
    {
        path: '/projects',
        component: () => import('./views/Projects.vue'),
        children: [
            {
                name: 'projects-create',
                path: 'create',
                components: {
                    overlay: () => import('./views/ProjectsCreate.vue')
                }
            },
            {
                name: 'projects-edit',
                path: 'edit/:id',
                components: {
                    overlay: () => import('./views/ProjectsEdit.vue')
                }
            }
        ]
    }
];

export const router = createRouter({
    history: createWebHistory(),
    routes
});

```

:::

::: tip
Push to one of the named routes (e.g. `router.push({name: 'projects-create'})`) to open the overlay, and call `router.back()` from inside the overlay to close it. This keeps the URL in sync with what's on screen and makes the overlay deep-linkable.
:::

---

---
url: 'https://flux-ui.dev/components/pane.md'
---

# Pane

A pane component is a container used to display content in a visually distinct section of a user interface. It serves as a way to separate and organize information. A pane is built with other Pane elements that each have their own purpose.

::: render
render=../../code/components/pane/preview.vue
:::

## Examples

::: example Basic || A basic pane.
example=../../code/components/pane/basic.vue
:::

::: example Loading || A pane with a loading state.
example=../../code/components/pane/loading.vue
:::

::: example Tag || A pane with a tag.
example=../../code/components/pane/tag.vue
:::

## Used components

* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/pane/body.md'
---

# Pane body

The pane body is the main content area of a pane. It provides comfortable padding and space for displaying text, forms, controls, or any other user interface elements.

::: render
render=../../code/components/pane/body/preview.vue
:::

## Examples

::: example Basic || A basic pane body.
example=../../code/components/pane/body/basic.vue
:::

::: example Multiple || Multiple pane bodies.
example=../../code/components/pane/body/multiple.vue
:::

---

---
url: 'https://flux-ui.dev/components/pane/clickable.md'
---

# Clickable pane

A clickable pane is a pressable variant of the [Pane](./index) component. It can act as a button, a link, or a router link, making it suitable for navigable card-style UI elements.

::: render
render=../../code/components/pane/clickable/preview.vue
:::

::: tip
This component is best used within a [Pane group](./group).
:::

## Examples

::: example As link || A clickable pane that opens an external URL in a new tab.
example=../../code/components/pane/clickable/with-link.vue
:::

::: example Disabled || A disabled clickable pane blocks interaction and dims its content.
example=../../code/components/pane/clickable/disabled.vue
:::

::: example Variants || The `variant` prop switches between the default, flat and well styles.
example=../../code/components/pane/clickable/variants.vue
:::

::: example With tag || Use the `tag` prop to render a corner label on the pane.
example=../../code/components/pane/clickable/tag.vue
:::

::: example Loading || Add `is-loading` to show a spinner while an action is in progress.
example=../../code/components/pane/clickable/loading.vue
:::

## Used components

* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/pane/clickable-header.md'
---

# Clickable pane header

The clickable pane header is a pressable variant of the [Pane header](./header). The entire header acts as a button, link or router link depending on the `type` prop, making it ideal for a [Layer pane](./layer-pane) section that navigates to a detail view. A trailing chevron signals that the header is navigable.

::: render
render=../../code/components/pane/clickable-header/preview.vue
:::

::: tip
Because the whole header is a single interactive element, it can't contain interactive elements such as buttons. If you need trailing actions, use the regular [Pane header](./header) instead.
:::

## Examples

::: example Basic || A clickable pane header that acts as a link.
example=../../code/components/pane/clickable-header/basic.vue
:::

::: example Layer pane || A clickable header as the entry point of a layer pane section.
example=../../code/components/pane/clickable-header/layer-pane.vue
:::

::: example Colors || Use the layer pane `color` prop to convey meaning. The header and hover state adapt to the color.
example=../../code/components/pane/clickable-header/colors.vue
:::

::: example With avatar || Place an avatar in the `before` slot to build a profile or account entry point.
example=../../code/components/pane/clickable-header/with-avatar.vue
:::

::: example Disabled || A disabled header blocks interaction and dims its content.
example=../../code/components/pane/clickable-header/disabled.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/pane/footer.md'
---

# Pane footer

The pane footer is designed for actions associated with the pane, such as buttons or links. It provides a subtle background and a dividing border to visually separate actions from the main content. This helps users easily identify the controls that finalize or continue a task.

::: render
render=../../code/components/pane/footer/preview.vue
:::

## Examples

::: example Basic || A basic pane footer.
example=../../code/components/pane/footer/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/pane/group.md'
---

# Pane group

The pane group is used to visually connect multiple panes in a vertical stack. Instead of adding spacing, it applies a subtle 1px border between each pane to create clear separation while maintaining a seamless, continuous layout.

::: render
render=../../code/components/pane/group/preview.vue
:::

## Examples

::: example Basic || A basic grouped pane.
example=../../code/components/pane/group/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/pane/header.md'
---

# Pane header

The pane header provides a structured title area for the pane. It supports optional icons and styled text to clearly communicate the purpose of the pane.

::: render
render=../../code/components/pane/header/preview.vue
:::

## Examples

::: example Basic || A basic pane header.
example=../../code/components/pane/header/basic.vue
:::

::: example Icon || A pane header with an icon.
example=../../code/components/pane/header/icon.vue
:::

::: example Sub title || A pane header with an sub title.
example=../../code/components/pane/header/subtitle.vue
:::

## Used components

* [Icon](../icon)

---

---
url: 'https://flux-ui.dev/components/pane/layer-pane.md'
---

# Layer pane

A layer pane groups related content in a structured panel. Place a [Pane header](./header) or [Pane footer](./footer) directly inside it to frame the primary content with a contrasting tinted band.

::: render
render=../../code/components/layer-pane/preview.vue
:::

## Examples

::: example Basic || A layer pane with a header and a single pane.
example=../../code/components/layer-pane/basic.vue
:::

::: example Colors || Use the `color` prop to convey meaning, such as severity or status.
example=../../code/components/layer-pane/colors.vue
:::

::: example With footer || A header at the top and a footer at the bottom of the layer pane.
example=../../code/components/layer-pane/with-footer.vue
:::

::: example With buttons || A layer pane containing action buttons.
example=../../code/components/layer-pane/with-buttons.vue
:::

::: example With button group || A segmented button group as a view switcher in the pane header.
example=../../code/components/layer-pane/with-button-group.vue
:::

::: example With items || A header with a trailing action, above a list of items with avatars and badges.
example=../../code/components/layer-pane/with-items.vue
:::

::: example With icon || A [Pane header](./header) with an icon for a prominent section heading.
example=../../code/components/layer-pane/with-pane-header.vue
:::

## Used components

* [Pane](../)
  * [Body](./body)
  * [Header](./header)
  * [Footer](./footer)

---

---
url: 'https://flux-ui.dev/components/pane/media.md'
---

# Pane media

The pane media is used to display an image element within a pane. It ensures the media is sized and positioned appropriately, maintaining a clean visual hierarchy. Pane media is helpful for panes that include supporting images, thumbnails, or promotional graphics.

::: render
render=../../code/components/pane/media/preview.vue
:::

## Examples

::: example Full || A media pane with a full image.
example=../../code/components/pane/media/full.vue
:::

::: example Inset || A media pane with whitespace around the media.
example=../../code/components/pane/media/inset.vue
:::

::: example Aspect ratio || Use `aspect-ratio` to control the shape of the media area.
example=../../code/components/pane/media/aspect-ratio.vue
:::

::: example Focal point || Use `image-focal-point` to keep the subject in frame when the media is cropped.
example=../../code/components/pane/media/focal-point.vue
:::

---

---
url: 'https://flux-ui.dev/components/slide-over.md'
---

# Slide over

The slide over is a modal-like surface that slides in from the edge of the view to show additional content without disrupting the current workflow. It is often used to reveal the details or options for an entity.

::: render
render=../code/components/slide-over/preview.vue
:::

::: warning Requires FluxRoot
This slide over renders through a parent [`<FluxRoot>`](./root). Without one in your app, nothing appears and no error is thrown.
:::

## Examples

::: example Basic || A basic slide over.
example=../code/components/slide-over/basic.vue
:::

::: example Tabs || A slide over with tabs.
example=../code/components/slide-over/tabs.vue
:::

## Router-driven

Pair the slide over with [Vue Router](../guide/introduction/installation/vue-router) to open detail views through navigation. Define an `over` named view on every route that should appear inside the slide over, and render a single `<RouterView name="over"/>` from your top-level layout.

The layout watches `route.matched` for the first record that exposes the `over` view. When such a record is matched the `<RouterView>` renders inside the slide over; otherwise the slide over stays empty and the transition closes it. The matched route's `fullPath` is forwarded to the `view-key` prop so transitions are scoped to the active resource.

::: code-group

```ts \[router.ts]
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
    {
        path: '/orders',
        component: () => import('./views/Orders.vue'),
        children: [
            {
                name: 'order',
                path: ':id',
                components: {
                    over: () => import('./views/Order.vue')
                },
                children: [
                    {
                        name: 'order-buyer',
                        path: 'buyer',
                        component: () => import('./views/OrderBuyer.vue')
                    },
                    {
                        name: 'order-payment',
                        path: 'payment',
                        component: () => import('./views/OrderPayment.vue')
                    }
                ]
            }
        ]
    }
];

export const router = createRouter({
    history: createWebHistory(),
    routes
});

```

:::

::: tip
Push to one of the named routes (e.g. `router.push({name: 'order', params: {id: 42}})`) to open the slide over, and call `router.back()` from inside it to close. The slide over also supports nested children (such as tabs), each with their own URL.
:::

---

---
url: 'https://flux-ui.dev/components/window.md'
---

# Window

The window displays one of several slots at a time, letting users move between them. Use it for filters and submenus that do not need to be visible all at once.

::: render
render=../code/components/window/preview.vue
:::

## Examples

::: example Basic || A basic window.
example=../code/components/window/basic.vue
:::

---

---
url: 'https://flux-ui.dev/components/feedback.md'
---

# Feedback

The feedback components keep people informed about what is happening, from alerts, notices and snackbars to tooltips and guided tours.

---

---
url: 'https://flux-ui.dev/components/attention/alert.md'
---

# Alert

This function displays an alert with the specified properties and waits for the alert to be closed before resolving the promise.

::: render
render=../../code/components/attention/alert/preview.vue
:::

::: tip
Alerts can interrupt the user by taking over the entire screen. Consider using a [Notice](./notice) or [Snackbar](./snackbar) for less intrusive notifications.
:::

::: warning Requires FluxRoot
Alerts render through a parent [`<FluxRoot>`](../root). Without one in your app, nothing appears and no error is thrown.
:::

## Functional API

Alerts can only be shown from code. An [Overlay](../overlay) should be used if you want
to show an alert from within your template.

::: render
render=../../code/components/attention/alert/functional.vue
:::

::: code-group

```ts [Example]
showAlert({
    icon: 'circle-exclamation',
    title: 'Title',
    message: 'Hello world'
});
```

```ts [Signature]
function showAlert(spec: FluxAlertObject): Promise<void> {
}
```

```ts [Options]
type FluxAlertObject = {
    readonly id: number;
    readonly icon?: FluxIconName;
    readonly message: string;
    readonly title: string;

    onClose(): void;
};
```

:::

## Used components

* [Button](../button)
* [Overlay](../overlay)
* [Pane](../pane)
  * [Body](../pane/body)
  * [Footer](../pane/footer)
  * [Header](../pane/header)
* [Spacer](../layout/spacer)

---

---
url: 'https://flux-ui.dev/components/attention/confirm.md'
---

# Confirm

This function displays a confirm with the specified properties and waits for the confirm to be closed before resolving the promise.

::: render
render=../../code/components/attention/confirm/preview.vue
:::

::: warning Requires FluxRoot
Confirms render through a parent [`<FluxRoot>`](../root). Without one in your app, nothing appears and no error is thrown.
:::

## Functional API

Confirms can only be shown from code. An [Overlay](../overlay) should be used if you want
to show a confirm from within your template.

::: render
render=../../code/components/attention/confirm/functional.vue
:::

::: code-group

```ts [Example]
const result = await showConfirm({
    icon: 'circle-exclamation',
    title: 'Title',
    message: 'Are you sure?'
});
```

```ts [Declaration]
declare function showConfirm(spec: FluxConfirmObject): Promise<void>;
```

```ts [Options]
type FluxConfirmObject = {
    readonly id: number;
    readonly icon?: FluxIconName;
    readonly message: string;
    readonly title: string;

    onCancel(): void;
    onConfirm(): void;
};
```

:::

## Used components

* [Button](../button)
* [Overlay](../overlay)
* [Pane](../pane)
  * [Body](../pane/body)
  * [Footer](../pane/footer)
  * [Header](../pane/header)
* [Spacer](../layout/spacer)

---

---
url: 'https://flux-ui.dev/components/info.md'
---

# Info

The info component is used to display short, informative messages that provide additional context or guidance to the user.

::: render
render=../code/components/info/preview.vue
:::

## Examples

::: example Basic || A basic info display.
example=../code/components/info/basic.vue
:::

::: example Multiple || Multiple info's to display.
example=../code/components/info/multiple.vue
:::

::: example Colors || Use the `color` prop to convey intent.
example=../code/components/info/colors.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/attention/notice.md'
---

# Notice

A UI element designed to inform or alert users about important statuses, events, or actions. It can include an icon, a message, and an optional title, ensuring that critical information is effectively communicated and stands out within the user interface.

::: render
render=../../code/components/attention/notice/preview.vue
:::

::: tip
For temporary notifications that auto-dismiss or need less prominence, consider using the [Snackbar](./snackbar) component. Snackbars are ideal for brief messages.
:::

## Examples

::: example Basic || Notices can display the result of an action that the user performed. The color of the notice depends on whether the result of that action is positive or negative.
example=../../code/components/attention/notice/basic.vue
:::

::: example Loading || Notices may also indicate that something is loading.
example=../../code/components/attention/notice/loading.vue
:::

::: example Closeable || Add `is-closeable` to let users dismiss a notice. The `close` event fires when the close button is clicked.
example=../../code/components/attention/notice/closeable.vue
:::

::: example With action || Use the `end` slot to render trailing content such as a button next to the message.
example=../../code/components/attention/notice/action.vue
:::

::: example Centered || The `is-center` prop horizontally centers the contents of the notice.
example=../../code/components/attention/notice/centered.vue
:::

::: example Severity colors || The `color` prop conveys the severity of the message.
example=../../code/components/attention/notice/colors.vue
:::

## Severity examples

Colors such as `success`, `error`, `warning`, `info`, and `gray` help convey the severity of the message. For example:

* `danger`: Failed to save data. Please try again.
* `info`: New updates are available.
* `success`: Data saved successfully.
* `warning`: You have unsaved changes.
* `gray`: We've updated the invoice filter, see what's new.

## Accessibility

The notice exposes its severity to assistive technology. A `danger` or `warning` notice uses `role="alert"` with `aria-live="assertive"` so it is announced immediately, while all other colors use `role="status"` with `aria-live="polite"`.

## Used components

* [Icon](../icon)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/attention/prompt.md'
---

# Prompt

This function displays a prompt with the specified properties and waits for the input to be entered before resolving the promise.

::: render
render=../../code/components/attention/prompt/preview.vue
:::

::: warning Requires FluxRoot
Prompts render through a parent [`<FluxRoot>`](../root). Without one in your app, nothing appears and no error is thrown.
:::

## Functional API

Prompts can only be shown from code. An [Overlay](../overlay) should be used if you want
to show a prompt from within your template.

::: render
render=../../code/components/attention/prompt/functional.vue
:::

::: code-group

```ts [Example]
const result = await showPrompt({
    icon: 'circle-exclamation',
    title: 'Title',
    message: 'What is your name?',
    fieldLabel: "Name"
});
```

```ts [Declaration]
declare function showPrompt(spec: FluxPromptObject): Promise<void>;
```

```ts [Options]
type FluxPromptObject = {
    readonly id: number;
    readonly icon?: FluxIconName;
    readonly message: string;
    readonly title: string;
    readonly fieldLabel: string;
    readonly fieldPlaceholder?: string;
    readonly fieldType?: InputType;

    onCancel(): void;
    onConfirm(text: string): void;
};
```

:::

## Used components

* [Button](../button)
* [Form](../form)
  * [Field](../form/field)
  * [Input](../form/input)
* [Overlay](../overlay)
* [Pane](../pane)
  * [Body](../pane/body)
  * [Footer](../pane/footer)
  * [Header](../pane/header)
* [Spacer](../layout/spacer)

---

---
url: 'https://flux-ui.dev/components/attention/snackbar.md'
---

# Snackbar

The snackbar notifies the user about a task the system has performed or will perform. It can also include actions the user can select.

::: render
render=../../code/components/attention/snackbar/preview.vue
:::

::: tip
For notifications that need prominence, consider using the [Notice](./notice) component.
:::

::: warning Requires FluxRoot
By default snackbars render through a parent [`<FluxRoot>`](../root). Without one in your app, nothing appears and no error is thrown. Set `is-rendered` to render a snackbar inline instead.
:::

## Functional API

Snackbars can be part of your template and controlled with `v-if`, but they also have an api that you can use within scripts.

::: render
render=../../code/components/attention/snackbar/functional.vue
:::

::: code-group

```ts [Example]
showSnackbar({
    color: 'success',
    duration: 3000,
    icon: 'circle-check',
    message: 'Changes saved successfully.'
});
```

```ts [Declaration]
declare function showSnackbar(options: FluxSnackbarObject): Promise<void>;
```

```ts [Options]
export type FluxSnackbarObject = {
    readonly id: number;
    readonly actions?: Record<string, string>;
    readonly color?: FluxColor;
    readonly duration?: number;
    readonly icon?: FluxIconName;
    readonly isCloseable?: boolean;
    readonly isLoading?: boolean;
    readonly isRendered?: boolean;
    readonly message?: string;
    readonly progressIndeterminate?: boolean;
    readonly progressMax?: number;
    readonly progressMin?: number;
    readonly progressStatus?: string;
    readonly progressValue?: number;
    readonly subMessage?: string;
    readonly title?: string;

    onAction?(actionKey: string): void;
    onClose?(): void;
};
```

:::

By default a snackbar dismisses itself after `duration` milliseconds (6000 by default). Hovering the snackbar pauses this timer and moving the pointer away resumes it, so the message stays readable while the user is interacting with it.

## Accessibility

Snackbars are announced to assistive technology through a live region. A `danger` snackbar uses `role="alert"` with `aria-live="assertive"` so it is announced immediately; all other colors use `role="status"` with `aria-live="polite"` to avoid interrupting the user.

## Examples

::: example Global || Snackbars render globally by-default.
example=../../code/components/attention/snackbar/global.vue
:::

::: example Actions || Actions can be added to the snackbar to request for input.
example=../../code/components/attention/snackbar/actions.vue
:::

## Used components

* [Action](../action)
* [Icon](../icon)
* [Progress bar](../progress-bar)
* [Spinner](../spinner)

---

---
url: 'https://flux-ui.dev/components/tooltip.md'
---

# Tooltip

The tooltip component can be used to display additional information when the user hovers an element. It tries to position the tooltip within the viewport. When the content needs to be complex, a slot can be used.

::: render
render=../code/components/tooltip/preview.vue
:::

::: warning Requires FluxRoot
This tooltip renders through a parent [`<FluxRoot>`](./root). Without one in your app, nothing appears and no error is thrown.
:::

## Examples

::: example Basic || A basic tooltip.
example=../code/components/tooltip/basic.vue
:::

::: example Content || A tooltip that uses the content slot.
example=../code/components/tooltip/content.vue
:::

---

---
url: 'https://flux-ui.dev/components/tour.md'
---

# Tour

The Tour component guides users through a sequence of steps, highlighting a target element with a spotlight and showing a popover next to it. Steps are declared with [Tour Item](#tour-item) components. It is controlled through `v-model:active` and `v-model:step`. While active, the rest of the page is dimmed and not interactive and Escape skips the tour.

::: render
render=../code/components/tour/preview.vue
:::

::: tip
Each step's `target` is a CSS selector or a function returning an element. Make sure the target exists in the DOM when its step becomes active.
:::

::: tip
While a tour is active the popover acts as a `role="dialog"` and traps focus, so keyboard users stay within the current step. The step body is announced through an `aria-live` region and the title is linked via `aria-labelledby`.
:::

## Tour Item

Each step of the tour is a `FluxTourItem`. It targets an element through the `target` prop, optionally shows a `title`, and renders its default slot as the step content.

| Prop       | Type                                       | Description                                                                 |
|------------|--------------------------------------------|-----------------------------------------------------------------------------|
| `target`   | `string \| (() => HTMLElement \| null)`    | A CSS selector or getter for the element this step highlights.               |
| `title`    | `string`                                   | The optional title shown at the top of the step.                            |
| `position` | `FluxTourPosition`                         | The optional position of the popover relative to the target. Defaults to `bottom`. |

The default slot holds the step content.

## Examples

::: example Basic || A three-step product tour.
example=../code/components/tour/preview.vue
:::

::: example Positions || Control where each popover appears with the position prop.
example=../code/components/tour/positions.vue
:::

::: example Custom content || Render any component inside a step through its default slot.
example=../code/components/tour/custom.vue
:::

::: example Rich onboarding || Combine progress, avatars and actions for a richer tour.
example=../code/components/tour/rich.vue
:::

## Used components

* [Pane](./pane/)
* [Button](./button/)

---

---
url: 'https://flux-ui.dev/components/primitives.md'
---

# Primitives

The primitive components are the low-level building blocks that the rest of the library builds on, from the root provider and icons to typography and pressable surfaces.

---

---
url: 'https://flux-ui.dev/components/boxed-icon.md'
---

# Boxed icon

This component displays a single customizable Font Awesome icon, rendered as SVG in a box.

::: render
render=../code/components/boxed-icon/preview.vue
:::

## Examples

::: example Standalone
example=../code/components/boxed-icon/standalone.vue
:::

::: example Rounded || Set `rounded` to draw the box as a circle.
example=../code/components/boxed-icon/rounded.vue
:::

::: example Pane
example=../code/components/boxed-icon/pane.vue
:::

## Used components

* [Icon](./icon)

---

---
url: 'https://flux-ui.dev/components/icon.md'
---

# Icon

This component displays a single customizable Font Awesome icon, rendered as SVG by default. It is commonly used in various Flux components, including [Buttons](./button), and can be easily styled with CSS. It can also render icons with the Font Awesome webfont. See [Font Awesome](../guide/introduction/font-awesome#using-the-icon-font).

Please refer to [Font Awesome](../guide/introduction/font-awesome) to read more about the usage of icons.

There is also a [Boxed icon](./boxed-icon) component available.

::: render
render=../code/components/icon/preview.vue
:::

## Examples

::: example Colored
example=../code/components/icon/colored.vue
:::

## Snippet

```vue
<FluxIcon name="rocket"/>
```

---

---
url: 'https://flux-ui.dev/components/link.md'
---

# Link

The link component is an inline link used to navigate to another page within the application or to open one in a new tab. It scales with the surrounding text and supports a leading and trailing icon.

::: render
render=../code/components/link/preview.vue
:::

## Examples

::: example Basic || A basic link.
example=../code/components/link/basic.vue
:::

::: example Icon || A link with a leading and trailing icon.
example=../code/components/link/icon.vue
:::

::: example Primary || A link that uses the primary color.
example=../code/components/link/primary.vue
:::

::: example New tab || A link that opens a new tab.
example=../code/components/link/outside.vue
:::

## Used components

* [Icon](./icon)
* [Pressable](./pressable)

---

---
url: 'https://flux-ui.dev/components/pressable.md'
---

# Pressable

A polymorphic base component that renders as different element types based on the `component-type` prop. It can render as a Vue Router link, anchor tag, button, or div. This component is primarily used internally by other Flux components like [Button](./button/) to provide flexible navigation and interaction behavior.

::: render
render=../code/components/pressable/preview.vue
:::

## Examples

::: example Route || Renders as a router-link for internal navigation with Vue Router.
example=../code/components/pressable/route.vue
:::

::: example Link || Renders as an anchor tag for external links.
example=../code/components/pressable/link.vue
:::

::: example Button || Renders as a button element for click actions.
example=../code/components/pressable/button.vue
:::

---

---
url: 'https://flux-ui.dev/components/prose.md'
---

# Prose

The Prose component turns plain HTML into rich, readable prose. Everything you drop inside it, headings, paragraphs, lists, blockquotes, code, tables and images, is styled with a consistent type scale and vertical rhythm, so you can write an article without reaching for custom CSS.

By default Prose renders a `div`. Set `tag` to render a different wrapper such as an `article`, or use `as-child` to merge the styling onto the single child element without any wrapper at all.

For long-form reading, add the `container` prop to cap the content at a comfortable measure and center it. The width is driven by the `--flux-prose-container` custom property (default `90ch`), so you can set it to `72ch`, `78ch`, `84ch` or any value you like.

In container mode the content is laid out on a break-out grid, so individual elements can reach past the measure. Mark an element with `data-prose-wide` to break out to a wider track, or `data-prose-full` for a full-bleed element that spans the whole container. The gutter and the extra width of the wide track are set through the `--flux-prose-gutter` (default `24px`) and `--flux-prose-wide` (default `12ch`) custom properties.

Because Prose only styles its own HTML elements, you can drop a Flux component straight into an article without a wrapper: it keeps its own styling and still flows in the vertical rhythm.

Use [Text](/components/text) instead when you need a single styled piece of inline text, such as a label, a metric or a caption. Prose is for flowing document content, Text is for individual strings.

::: render
render=../code/components/prose/preview.vue
:::

::: tip
Outside of Prose, Flux keeps only light element defaults (heading sizes, link and monospace styling). The rich prose styling (vertical rhythm, decorated blockquotes, list markers and table borders) applies only within `FluxProse`.
:::

## Examples

::: example Headings || The six heading levels, each with its own size and weight.
example=../code/components/prose/headings.vue
:::

::: example Paragraphs || Body copy flows with a comfortable line height and automatic spacing between blocks.
example=../code/components/prose/paragraph.vue
:::

::: example Lists || Ordered and unordered lists get markers, indentation and nested styling.
example=../code/components/prose/lists.vue
:::

::: example Blockquote || A quote is set off with an accent border and italics.
example=../code/components/prose/blockquote.vue
:::

::: example Code || Inline code renders as a chip, while a pre block becomes a scrollable code block.
example=../code/components/prose/code.vue
:::

::: example Table || Tables get borders, padding and a subtle header background.
example=../code/components/prose/table.vue
:::

::: example Break-out || In container mode, mark an element with data-prose-wide or data-prose-full to break it out of the reading measure.
example=../code/components/prose/breakout.vue
:::

::: example Embedded component || Drop a Flux component straight into an article. Prose only styles its own HTML elements, so the component keeps its own styling while flowing in the vertical rhythm.
example=../code/components/prose/embed.vue
:::

::: example Full article || Everything together: headings, body copy, lists, a blockquote, inline and block code, a keyboard shortcut, a table, an image, and an embedded Flux pane.
example=../code/components/prose/article.vue
:::

## Used components

* [Text](/components/text)

---

---
url: 'https://flux-ui.dev/components/root.md'
---

# Root

Some Flux features render into a shared root element instead of inline where you use them. `<FluxRoot>` provides that element and hosts the providers for [tooltips](./tooltip), [overlays](./overlay), [slide-overs](./slide-over), [snackbars](./attention/snackbar) and the programmatic [alerts](./attention/alert), [confirms](./attention/confirm) and [prompts](./attention/prompt). Wrap your application in a single `<FluxRoot>` near its entry point.

::: warning
Without a `<FluxRoot>` in your app these features silently do nothing: the call succeeds and the component mounts, but nothing is rendered and no error is thrown.
:::

## Providers

FluxRoot internally renders the following provider components. These are not used directly, but are required for certain features to work:

* **FluxOverlayProvider** renders stacked [alerts](./attention/alert), [confirms](./attention/confirm) and [prompts](./attention/prompt) from the global store, and is the mount target that [overlays](./overlay) and [slide-overs](./slide-over) teleport into.
* **FluxSnackbarProvider** renders [snackbars](./attention/snackbar) with transition animations.
* **FluxTooltipProvider** renders [tooltips](./tooltip) with intelligent positioning relative to their trigger element.

::: tip
These providers are automatically included when you use FluxRoot. You do not need to import or configure them separately.
:::

## Snippet

```vue [App.vue]
<template>
    <FluxRoot>
        <!-- Your application -->
    </FluxRoot>
</template>

<script
    setup
    lang="ts">
    import { FluxRoot } from '@flux-ui/components';
</script>
```

---

---
url: 'https://flux-ui.dev/components/text.md'
---

# Text

The Text component renders inline or block text styled with the Flux type scale. It keeps typography consistent across your app, so you don't have to reach for custom CSS to set a size, weight, color, or tabular figures.

::: render
render=../code/components/text/preview.vue
:::

::: tip
By default Text renders a `span` and inherits the surrounding font size. Set the `size` prop to opt into the type scale, or use `tag` to render a different element such as a `p`.
:::

## Examples

::: example Basic || A simple piece of text, inheriting the surrounding font size.
example=../code/components/text/basic.vue
:::

::: example Sizes || The size prop maps onto the Flux type scale, from small captions up to display numbers.
example=../code/components/text/sizes.vue
:::

::: example Weights || Adjust the emphasis of text with the weight prop.
example=../code/components/text/weights.vue
:::

::: example Colors || Use a semantic keyword like muted, or any FluxColor.
example=../code/components/text/colors.vue
:::

::: example Numbers || Combine tabular figures with a display size for metrics and KPIs.
example=../code/components/text/numbers.vue
:::

---

---
url: 'https://flux-ui.dev/components/utilities.md'
---

# Utilities

The utility components are behavioural helpers with no visual output of their own, from sharing a disabled state across nested components to rendering a dynamic view.

---

---
url: 'https://flux-ui.dev/components/disabled.md'
---

# Disabled

The disabled component provides a shared disabled state to all child components within it. Instead of applying visual or interactive changes itself, it exposes the disabled value through Vue's injection system. Any nested Flux component can read this state and adjust its own appearance and behavior accordingly. This allows entire sections of the UI to be disabled at once without needing to set the disabled prop individually on each component.

::: render
render=../code/components/disabled/preview.vue
:::

## Examples

::: example Basic || An entire section disabled through a single wrapper.
example=../code/components/disabled/basic.vue
:::

::: example Toggle a section || Bind the shared state to your own toggle.
example=../code/components/disabled/toggle.vue
:::

---

---
url: 'https://flux-ui.dev/components/dynamic-view.md'
---

# Dynamic view

The dynamic view component renders a single `VNode`. Pass it a node — built with `h()`, captured from a slot, or stored in a ref — and it renders that node in place, swapping to a new one whenever the `vnode` prop changes. It is useful when the content to render is decided in your script rather than written directly in the template.

::: render
render=../code/components/dynamic-view/preview.vue
:::

## Examples

::: example Basic || Render a VNode created with h().
example=../code/components/dynamic-view/basic.vue
:::

::: example Switching the view || Swap the rendered VNode reactively.
example=../code/components/dynamic-view/dynamic.vue
:::

---

---
url: 'https://flux-ui.dev/components/transitions.md'
---

# Transitions

The transition components are ready-made wrappers for animating content in and out, so views, overlays and windows enter and leave with a consistent motion.

---

---
url: 'https://flux-ui.dev/components/transitions/breakthrough.md'
---

# Breakthrough

::: render
render=../../code/components/transitions/breakthrough/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxBreakthroughTransition.vue]
<template>
    <Preview>
        <FluxBreakthroughTransition>
            <FluxPane
                v-if="visible"
                style="height: 150px; width: 75%;"/>
        </FluxBreakthroughTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxBreakthroughTransition, FluxPane } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/fade.md'
---

# Fade

::: render
render=../../code/components/transitions/fade/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxFadeTransition.vue]
<template>
    <Preview>
        <FluxFadeTransition>
            <FluxPane
                v-if="visible"
                style="height: 150px; width: 75%;"/>
        </FluxFadeTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxFadeTransition, FluxPane } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/overlay.md'
---

# Overlay

::: render
render=../../code/components/transitions/overlay/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxOverlayTransition.vue]
<template>
    <Preview :class="$style.overlayPreview">
        <div :class="$style.overlayShade"/>

        <FluxOverlayTransition>
            <div
                v-if="visible"
                :class="[$style.overlay, $style.isCurrent]">
                <FluxPane/>
            </div>
        </FluxOverlayTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxOverlayTransition, FluxPane } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

<style
    lang="scss"
    module>
    .overlayPreview {
        overflow: hidden;
    }

    .overlayPreview :local(.overlay) {
        position: absolute;
        height: unset;
        width: unset;
        border-radius: var(--radius);

        :local(.pane) {
            height: 150px;
            width: 75%;
        }
    }

    .isCurrent,
    .overlayTransitionLeaveActive {
        pointer-events: auto;
    }

    .overlayShade {
        position: absolute;
        height: unset;
        width: unset;
        inset: 0;

        &:not(:has(+ .overlay:not(.overlayTransitionLeaveActive))) {
            opacity: 0;
        }
    }
</style>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/route.md'
---

# Route

::: render
render=../../code/components/transitions/route/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxRouteTransition.vue]
<template>
    <Preview>
        <FluxRouteTransition>
            <FluxPane
                v-if="visible"
                style="height: 150px; width: 75%;"/>
        </FluxRouteTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxPane, FluxRouteTransition } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/slide-over.md'
---

# Slide over

::: render
render=../../code/components/transitions/slide-over/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxSlideOverTransition.vue]
<template>
    <Preview :class="$style.slideOverPreview">
        <div :class="$style.overlayShade"/>

        <FluxSlideOverTransition>
            <div
                v-if="visible"
                :class="[$style.overlay, $style.slideOver, $style.isCurrent]">
                <FluxPane/>
            </div>
        </FluxSlideOverTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxPane, FluxSlideOverTransition } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

<style
    lang="scss"
    module>
    .slideOverPreview {
        overflow: clip;
    }

    .slideOverPreview :local(.slideOver) {
        position: absolute;
        height: unset;
        width: unset;
        border-radius: var(--radius);

        :local(.pane) {
            height: 100%;
            width: 50%;
        }
    }

    .isCurrent,
    .slideOverTransitionLeaveActive {
        pointer-events: auto;
    }

    .overlayShade {
        position: absolute;
        height: unset;
        width: unset;
        inset: 0;

        &:not(:has(+ .overlay:not(.slideOverTransitionLeaveActive))) {
            opacity: 0;
        }
    }
</style>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/tooltip.md'
---

# Tooltip

::: render
render=../../code/components/transitions/tooltip/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxTooltipTransition.vue]
<template>
    <Preview>
        <FluxTooltipTransition>
            <FluxPane
                v-if="visible"
                style="height: 150px; width: 75%;"/>
        </FluxTooltipTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxPane, FluxTooltipTransition } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/vertical-window.md'
---

# Vertical window

::: render
render=../../code/components/transitions/vertical-window/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxVerticalWindowTransition.vue]
<template>
    <Preview :class="$style.verticalWindowTransitionPreview">
        <FluxVerticalWindowTransition :is-back="visible">
            <FluxPane v-if="visible">A</FluxPane>
            <FluxPane v-else>B</FluxPane>
        </FluxVerticalWindowTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxPane, FluxVerticalWindowTransition } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

<style
    lang="scss"
    module>
    .verticalWindowTransitionPreview {
        overflow: clip;

        :local(.pane) {
            display: flex;
            height: 150px;
            width: 150px;
            align-items: center;
            justify-content: center;
            color: var(--foreground-secondary);
            font-size: 42px;
            font-weight: 700;
        }
    }
</style>

```

:::

---

---
url: 'https://flux-ui.dev/components/transitions/window.md'
---

# Window

::: render
render=../../code/components/transitions/window/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxWindowTransition.vue]
<template>
    <Preview :class="$style.windowTransitionPreview">
        <FluxWindowTransition :is-back="visible">
            <FluxPane v-if="visible">A</FluxPane>
            <FluxPane v-else>B</FluxPane>
        </FluxWindowTransition>
    </Preview>
</template>

<script
    lang="ts"
    setup>
    import { useInterval } from '@basmilius/common';
    import { FluxPane, FluxWindowTransition } from '@flux-ui/components';
    import { ref } from 'vue';

    const visible = ref(true);

    useInterval(1500, () => {
        visible.value = !visible.value;
    });
</script>

<style
    lang="scss"
    module>
    .windowTransitionPreview {
        overflow: clip;

        :local(.pane) {
            display: flex;
            height: 150px;
            width: 150px;
            align-items: center;
            justify-content: center;
            color: var(--foreground-secondary);
            font-size: 42px;
            font-weight: 700;
        }
    }
</style>

```

:::

---

---
url: 'https://flux-ui.dev/flow.md'
---
# Flux Flow

Flux Flow is a collection of declarative building blocks for displaying node based flows: automations, pipelines, decision trees and agent workflows. You compose a flow from plain Vue markup, positioning cards on a pannable canvas and wiring them together with connectors, without reaching for a heavyweight graph library.

The toolkit is display oriented. A full editor (dragging nodes, drawing connections) is intentionally out of scope, but the primitives are shaped so an editor can be layered on top later.

::: render
render=../code/flow/components/flow/preview.vue
:::

## Highlights

* **Declarative.** Write nodes and connectors as Vue markup; connectors reference nodes by id, so cards stay free of wiring props.
* **Opinionated cards.** A base `FluxFlowCard` plus `Trigger`, `Condition` and `Action` variants give you a Flux styled node surface in a single line, always headed by its type icon.
* **Small nodes too.** A `FluxFlowPill` heads a flow with a single named trigger, a `FluxFlowTerminal` opens and closes it, a `FluxFlowStep` marks the steps running down its trunk, a `FluxFlowJunction` knots lines together and a `FluxFlowNote` annotates the canvas.
* **Named branches.** A `FluxFlowPort` marks a point inside a card, so the branches of a condition leave it at the outcome they belong to, and a `FluxFlowGate` says out loud whether they meet on `and`, `or` or `xor`.
* **Layout that is not yours to do by hand.** A `FluxFlowChain` places a run of steps and wires it up, a `FluxFlowGraph` does the same for a flow that forks and merges, `useFlowLayout` turns a branching graph into coordinates, and a `FluxFlowGroup` or a `FluxFlowLane` frames the part of the canvas that belongs together.
* **Runnable.** Connectors accept a `progress-color` and `progress-value`, so you can visualize a flow while it runs.
* **Read only viewport.** Drag to pan, `ctrl`/`cmd` + scroll to zoom, and the canvas fits its content on mount.
* **Controls that stay put.** A `FluxFlowPanel` pins anything to a corner of the viewport, `FluxFlowControls` puts the zoom and fullscreen buttons there, and a `FluxFlowMinimap` maps the whole flow with the viewport drawn on it.

Head straight for [Examples](./examples) to see complete flows, or start with [Flow](./components/flow) for the canvas itself.

---

---
url: 'https://flux-ui.dev/flow/introduction/installation.md'
---
# Installation

To start using Flux Flow in your Vue application, you'll need to add it to your project alongside `@flux-ui/components`, which provides the shared primitives (icons, tags, badges) that the flow cards build on.

## Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [bun]
bun add @flux-ui/flow @flux-ui/components
```

```shell [pnpm]
pnpm install @flux-ui/flow @flux-ui/components
```

```shell [yarn]
yarn add @flux-ui/flow @flux-ui/components
```

```shell [npm]
npm install @flux-ui/flow @flux-ui/components
```

:::

## Step 2

Once the installation is complete, add the following lines to your `main.ts` file:

```ts [main.ts]
import '@flux-ui/flow/style.css'
import '@flux-ui/components/style.css'
```

## Step 3

Make sure the icons used by your flow cards are registered with Font Awesome, then import the components you want to use:

```vue [Flow.vue]
<template>
    <FluxFlow> <!-- [!code focus:11] -->
        <FluxFlowNode id="trigger" :x="0" :y="0">
            <FluxFlowTriggerCard title="Order Placed"/>
        </FluxFlowNode>

        <FluxFlowNode id="ship" :x="0" :y="240">
            <FluxFlowActionCard title="Create Shipment"/>
        </FluxFlowNode>

        <FluxFlowConnection from="trigger" to="ship"/>
    </FluxFlow>
</template>

<script
    setup
    lang="ts">
    import { FluxFlow, FluxFlowActionCard, FluxFlowConnection, FluxFlowNode, FluxFlowTriggerCard } from '@flux-ui/flow' // [!code focus:2]
</script>
```

::: tip
By default `FluxFlow` sizes its own height to its content, so it drops inline without a wrapper. Add `interactive` for a fixed-size, pannable canvas instead (give that a sized parent).
:::

---

---
url: 'https://flux-ui.dev/flow/components/flow.md'
---

# Flow

`FluxFlow` is the root of a flow: a shared coordinate space that connectors use to route between nodes. By default it lays its content out naturally, sizes its own height, and scrolls horizontally when the content is wider than its container, so it drops inline without a fixed-height wrapper.

Add `interactive` to opt into a pannable and zoomable viewport that fills its container instead: drag or scroll with two fingers to pan, and pinch or hold `ctrl`/`cmd` while scrolling to zoom towards the cursor.

::: render
render=../../code/flow/components/flow/preview.vue
:::

::: tip
Everything inside a flow, both `FluxFlowNode` and `FluxFlowConnection`, is written declaratively. Connectors reference nodes by id, so cards stay free of wiring props.
:::

## Examples

::: example Branching || A condition that fans out to two labeled branches. Branching is just more connectors, each referencing a node by id.
example=../../code/flow/components/flow/branching.vue
:::

::: example Axis || Two branches sitting further apart than the row below them is deep. Without `axis` each connector would take the shorter way out, leaving the card sideways and crossing back over it; naming the axis keeps every line running with the flow.
example=../../code/flow/components/flow/axis.vue
:::

::: example Background || Opt into a `dots` or `grid` backdrop with the `background` prop; it is transparent by default.
example=../../code/flow/components/flow/background.vue
:::

::: example Interactive || With `interactive` the flow fills its container as a pannable, zoomable canvas, starting at 100% from the top of the flow. Drag or scroll with two fingers to pan, and pinch or hold `ctrl`/`cmd` while scrolling to zoom.
example=../../code/flow/components/flow/interactive.vue
:::

::: example Start point || Point `start` at a node id to open the interactive viewport centered on that card instead of the top of the flow.
example=../../code/flow/components/flow/start.vue
:::

::: tip
On an interactive canvas, controls inside a card (a toggle, a button, a link, a text field) keep working: a press that starts on one never begins a pan. Add `data-nopan` to any other element that should grab the pointer for itself instead of panning the canvas.
:::

::: tip
An interactive canvas is reachable with the keyboard: tab to it, then pan with the arrow keys (hold `shift` to cover three times the ground), zoom with `+` and `-`, and press `0` to fit the whole flow in view. A field or a button inside a card keeps every key it is given.
:::

::: tip
An interactive canvas pans up to 300px past the viewport and then stops, so it always has room to move, even when the flow is smaller than its container. A two-finger scroll that runs into that edge hands the page its scroll back, so a flow embedded halfway down a page never traps it.
:::

For flows built out in full, from routing rules to a running deploy pipeline, see [Examples](../examples).

## Used components

* [Node](./node)
* [Connection](./connection)
* [Card](./card)
* [Controls](./controls)
* [Minimap](./minimap)

---

---
url: 'https://flux-ui.dev/flow/components/node.md'
---

# Node

`FluxFlowNode` positions a piece of content on the flow canvas. Give it a unique `id` and an `x` / `y` position in flow coordinates; the node measures its rendered size and registers it with the flow, so connectors can anchor to its edges.

A node renders whatever you place in its default slot. In practice that is a [Card](./card), but any markup works.

A card and a pill each mark their icon with a `data-flow-anchor` attribute, which is what a connector with `from-align="start"` or `to-align="start"` lands on. Put the attribute on an element of your own to give custom node content the same anchor; without one, a `start` connector falls back to 30px from the corner.

::: render
render=../../code/flow/components/node/preview.vue
:::

::: tip
Connectors reference a node by its `id`, never through props on the node or the card, so the wiring of a flow stays in one place: the connectors.
:::

## Used components

* [Flow](./flow)
* [Card](./card)

---

---
url: 'https://flux-ui.dev/flow/components/chain.md'
---

# Chain

`FluxFlowChain` positions a run of nodes and wires them together. Give it a starting point and it hands every [Node](./node) inside it a position, so a straight sequence of steps no longer needs a coordinate per card.

A link keeps its own `id`, so connectors from outside the chain reference it exactly as they always have.

::: render
render=../../code/flow/components/chain/preview.vue
:::

::: tip
Absolute `x` and `y` on a node stay the source of truth for positions. A chain only fills them in for the nodes it holds; give a node its own `x` and `y` and it keeps them, stepping out of the layout while staying in the markup.
:::

## Examples

::: example Mixed sizes || A terminal, a pill and a card are all different widths. With `align="center"` their middles land on one line, so the connectors run dead straight through the whole run.
example=../../code/flow/components/chain/mixed.vue
:::

::: example Horizontal || Set `direction="horizontal"` to run the chain from left to right. Links line up on their middles across the run, the same way they do vertically.
example=../../code/flow/components/chain/horizontal.vue
:::

::: example Your own connector || A `FluxFlowConnection` written between two links replaces the automatic one, so a labelled or colored connector never doubles up with a plain one. A side branch stays outside the chain and references the link by id.
example=../../code/flow/components/chain/branch.vue
:::

::: example Labelled connectors || A connector that carries a label or an icon gets a wider segment, so the badge sits clear of both cards with a stretch of line on either side. Tune it with `label-gap` when your labels run long.
example=../../code/flow/components/chain/labelled.vue
:::

::: tip
A chain only claims the pairs it can see: a connector between two links has to sit inside the chain, in the same direction, to replace the automatic one. Set `:auto-connect="false"` to draw every connector yourself.
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Connection](./connection)
* [Card](./card)

## See also

* [useFlowLayout](../composables/useFlowLayout) for a graph that branches instead of running in a line.

---

---
url: 'https://flux-ui.dev/flow/components/graph.md'
---

# Graph

`FluxFlowGraph` places a branching flow for you. It reads the connectors written inside it as the graph they describe, lays the nodes out in layers, and hands each one its position, so a [Node](./node) inside a graph carries no `x` and no `y`.

It is the branching counterpart of a [Chain](./chain): a chain places a straight run, a graph places anything that forks and merges. The layout runs on the sizes the cards measured for themselves, so a 300px card and a pill in the same layer still line up.

Two shapes are on offer. By default the graph stacks in layers, which suits a pipeline: everything at the same depth sits on the same row. Name a `trunk` instead and those ids run straight down a column while everything hanging off them walks out to the right, which suits a numbered rule list, where each rule should stay with its own fan-out rather than share a row with the next rule.

::: render
render=../../code/flow/components/graph/preview.vue
:::

::: tip
Name the axis on the surrounding [Flow](./flow) that matches the graph's `direction`, so every connector runs with the flow instead of taking the shorter way out.
:::

::: tip
A graph reads its connectors before it lays anything out, so it also knows whether any of them carries a badge and leaves the layers further apart when one does, exactly as a [Chain](./chain) does for its run. Set `layer-gap` yourself to take that over.
:::

::: tip
A trunk places the nodes; the connectors are still yours. Give the ones that run sideways into a card a `to-align="start"` so they land on its icon rather than halfway down it, and give a branch a `from-side="bottom"` so it drops out of the card above rather than leaving its right edge and doubling back.
:::

::: tip
A node lands one layer past its furthest source, and every layer is centred against the widest one. An edge that would close a cycle is cut rather than followed, so a graph that is not a tree still lays out; give such a connector its own `from-side` and `to-side` to send it around the diagram.
:::

## Examples

::: example Horizontal || Set `direction` to `horizontal` to stack the layers left to right, and match it with `axis` on the flow.
example=../../code/flow/components/graph/horizontal.vue
:::

::: example Fanning out and merging || Three checks run off one trigger and come back together on the step that needs all of them. The layer is laid out on what each node actually measures, so pills of three different widths sit evenly spaced and the layers above and below stay centred on them.
example=../../code/flow/components/graph/branches.vue
:::

::: example Running back || A connector that would close a cycle is cut out of the layout rather than followed, so the three steps still stack in order. Give it a `from-side` and a `to-side` on the off axis and it loops around the diagram instead of cutting back across it.
example=../../code/flow/components/graph/cycle.vue
:::

::: example Keeping a node in place || A node that carries its own `x` and `y` is left where it is and takes no part in the layout, which is how an annotation stands beside a flow without pushing a layer aside.
example=../../code/flow/components/graph/pinned.vue
:::

::: example A running pipeline || The [running pipeline](../examples) from the examples, with every coordinate taken out. Each stage still swaps its icon and tint off one clock, spins while it runs and carries a `FluxBadge` naming its state, and the connectors still fill towards the stage they feed; the graph is what decides where the pill and the three cards land. The stages are written with a `v-for`, and the graph reads straight through it.
example=../../code/flow/components/graph/pipeline.vue
:::

::: example Routing rules || The [routing rules](../examples) from the examples, with every coordinate taken out. Naming the trigger and the two steps as the `trunk` runs them straight down a column and walks each rule out to the right, so a rule stays with its own fan-out. Every rule is as tall as what it does, and the next step clears the branch above it.
example=../../code/flow/components/graph/routing.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Connection](./connection)
* [Card](./card)

---

---
url: 'https://flux-ui.dev/flow/components/connection.md'
---

# Connection

`FluxFlowConnection` draws a line between two nodes. It references them by `from` and `to`, resolves their positions from the flow, and routes a path between the nearest edges. Because connectors are declared separately from the nodes, all of a flow's wiring lives in one place.

By default the connector picks the most natural pair of sides based on where the nodes sit: stacked nodes connect bottom to top, side by side nodes connect right to left. Override `from-side` / `to-side` when you need an explicit route, for example the two branches out of a condition. Both branches then leave the same edge in the same spot; `from-align` / `to-align` move either end to the start or the end of its side to pull them apart, aligned on the icon of the node they touch.

For a branch that belongs to something written inside the node, a [Port](./port) is the sharper tool: `from-port` / `to-port` land the connector on the row that names the outcome.

A connector may also point at the node it left. Give `from` and `to` the same id and it loops out of one side and back into that same side, which is how a retry says it runs the step again. Name both `from-side` and `to-side` and the loop routes around the node from the one to the other instead.

::: render
render=../../code/flow/components/connection/preview.vue
:::

## Examples

::: example Types || Four connector shapes: `smoothstep` (the default, orthogonal with rounded corners), `step` (the same route with sharp corners), `bezier` and `straight`.
example=../../code/flow/components/connection/types.vue
:::

::: example Progress || A connector with a `progress-value` fills from the source towards the target, which is useful for visualizing a running flow. The fill animates as the value changes and respects reduced motion.
example=../../code/flow/components/connection/progress.vue
:::

::: example Colors || Give a connector a `color`, a FluxColor or any CSS color, to categorize it.
example=../../code/flow/components/connection/colors.vue
:::

::: example Explicit sides || Override `from-side` and `to-side` to route a connector out of a specific edge, for example the two branches of a condition.
example=../../code/flow/components/connection/sides.vue
:::

::: example Loop || Point `from` and `to` at the same node and the connector loops out of one side and back into it. It uses the side a connector running against the flow would take, so a retry and a step back read alike; `from-side` moves it elsewhere.
example=../../code/flow/components/connection/loop.vue
:::

::: example Loop between two sides || Name both `from-side` and `to-side` and the loop travels from the one to the other: two adjacent sides turn a corner, two opposite ones wrap the node along the axis they do not use.
example=../../code/flow/components/connection/loop-sides.vue
:::

::: example Alignment || A side is not one point: `from-align` and `to-align` move a connector to the `start` or `end` of the side it uses, which pulls two branches out of the same edge apart. `start` lands on the node's own icon, wherever that sits, so a card and a pill each anchor on their own; `end` mirrors that margin to the far corner. A node too narrow for the margin keeps its connector centered.
example=../../code/flow/components/connection/alignment.vue
:::

::: example Label placement || A badge rides the middle of the connector. On a connector that bends that middle can land on a bend, or on the leg two branches share, so `label-placement` moves it to the leg leaving the source or the leg entering the target instead.
example=../../code/flow/components/connection/label-placement.vue
:::

::: example Icons || An `icon` next to a `label` rides along in the badge. An `icon` on its own drops the badge and stands on the line itself, which keeps a connector that only needs a symbol light. Both break the line the same way, and both follow the connector's `color`.
example=../../code/flow/components/connection/icons.vue
:::

::: example Line styles || Connectors are solid by default; set `dashed` or `dotted` for other styles. A connector leaves its source with a port dot and reaches its target with an arrow head; `marker-start` and `marker-end` swap either for the other shape, or drop it entirely.
example=../../code/flow/components/connection/dashed.vue
:::

::: example Animated || Add `animated` to a dashed or dotted connector to travel its pattern towards the target, which reads as work in flight. It respects reduced motion.
example=../../code/flow/components/connection/animated.vue
:::

::: example Markers || Both ends carry their own marker. Give a two-way connector a head on each end, or strip them both for a bare line.
example=../../code/flow/components/connection/markers.vue
:::

::: example Marker shapes || Six shapes to end a connector with. `chevron` and `arrow` point at the target; `dot`, `diamond` and `square` read as ports; `bar` caps the line off.
example=../../code/flow/components/connection/marker-shapes.vue
:::

## Waypoints

A connector routes itself, which is what you want until it runs straight over the card between its two ends. Give it `waypoints` and it runs through the points you name instead. They are plain flow coordinates, the same space as the `x` / `y` of a node, so a route is written where you can read it off the canvas.

Every shape honours them: `straight` becomes a polyline, `smoothstep` rounds each corner the way it rounds its own, `step` turns those same corners sharply, and `bezier` becomes a single smooth curve through the points. The label rides the middle of the whole route, and both endpoints still leave and reach their node along the side they use.

::: example Three shapes, one detour || The same two waypoints in all three shapes. The endpoints are unaffected: waypoints only shape the run between them, and the label rides the middle of that run.
example=../../code/flow/components/connection/waypoints.vue
:::

::: tip
The canvas sizes itself to the nodes it holds, not to the connectors. Keep waypoints inside that area, or give the [Flow](./flow) enough `padding` to cover the detour.
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Port](./port)

---

---
url: 'https://flux-ui.dev/flow/components/port.md'
---

# Port

`FluxFlowPort` marks a named point inside a [Node](./node). Put one next to the row it belongs to and reference it from a connector with `from-port` or `to-port`: the connector lands on the node's edge at the height of that row, instead of on the node's icon.

That turns a condition card into a real branching point. Every outcome gets its own row and its own port, so the two branches leave the card where their outcome is written rather than both leaving from the same corner.

A port renders nothing and takes no space of its own: it is a zero sized marker riding the middle of the row it sits in, so adding one never moves the content around it. Only the connector shows where it is.

::: render
render=../../code/flow/components/port/preview.vue
:::

::: tip
The port fixes where along the side the connector lands, `side` fixes which edge. A connector that names a port therefore ignores `from-align` / `to-align`, and a `from-port` that no port answers to falls back to the node's own anchor.
:::

## Examples

::: example Named branches || Every outcome of a condition gets a row and a port, so each branch leaves the card at its own answer.
example=../../code/flow/components/port/branches.vue
:::

::: example Sides || Leave `side` out and the port takes the edge it sits closest to, which is the right one for a port at the end of a row. Name a `side` for the rest, for example a port in a footer that should leave through the bottom of the card.
example=../../code/flow/components/port/sides.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Connection](./connection)

---

---
url: 'https://flux-ui.dev/flow/components/card.md'
---

# Card

`FluxFlowCard` is the node surface: a header carrying the type icon and title, a body and an optional footer. It is a plain element, so it renders inside a [Node](./node) or on its own.

A card always shows an icon, so every node on the canvas reads as a type at a glance. Each variant brings its own icon, tint and type name; `icon`, `color` and `label` override them.

::: render
render=../../code/flow/components/card/preview.vue
:::

## Variants

`FluxFlowTriggerCard`, `FluxFlowConditionCard` and `FluxFlowActionCard` are thin wrappers around `FluxFlowCard` that preset the three common automation node types. Each default is overridable with the `label`, `icon` and `color` props.

* **`FluxFlowTriggerCard`** — type "Trigger", icon `bolt`, color `info`.
* **`FluxFlowConditionCard`** — type "Condition", icon `code-branch`, color `warning`.
* **`FluxFlowActionCard`** — type "Action", icon `play`, color `primary`.

::: example Variants || The three node variants. Override `label`, `icon` and `color` to fit your own node types.
example=../../code/flow/components/card/variants.vue
:::

::: example Colors || The badge accepts any FluxColor, so you can style a card for any kind of node.
example=../../code/flow/components/card/colors.vue
:::

## Rich content

The card body is a plain vertical stack, so you are not limited to text. Drop in any component from Flux or Flux Statistics: a [`FluxDescriptionList`](../../components/description-list/) for compact key/value data, a `FluxStatisticsLegend` for a color coded breakdown, a chart, badges, anything you need.

::: example Rich content || A card mixing plain text, a FluxDescriptionList and a FluxStatisticsLegend.
example=../../code/flow/components/card/content.vue
:::

::: example Header || The `header` slot fills the trailing end of the header, beside the title. Keep it to one small thing that qualifies the node; anything larger belongs in the body or the footer.
example=../../code/flow/components/card/header.vue
:::

## Interactive content

Nothing about the body is read only. Because it is plain markup, interactive controls, buttons and animated values work exactly as they would anywhere else, so a card can double as a small control surface for its node.

::: example Toggle || A FluxToggle drives the node's state; the badge and accent border follow it.
example=../../code/flow/components/card/toggle.vue
:::

::: example Approval || A FluxAvatar identifies the reviewer and a FluxSecondaryButton in the footer resolves the step.
example=../../code/flow/components/card/approval.vue
:::

::: example Live progress || A FluxStatisticsMeter reflects a running job by animating its value while the card stays active.
example=../../code/flow/components/card/progress.vue
:::

::: example Loading || Set `isLoading` to swap the type icon for a spinner in the same tinted tile, so a running step reads as busy without moving anything on the canvas.
example=../../code/flow/components/card/loading.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)

---

---
url: 'https://flux-ui.dev/flow/components/pill.md'
---

# Pill

`FluxFlowPill` is a compact node: a tinted icon and a label on a raised pill. Where a [Card](./card) describes a step in full, a pill names one, which makes it a natural head for a flow, the trigger that everything below hangs off.

::: render
render=../../code/flow/components/pill/preview.vue
:::

## Examples

::: example In a flow || A pill starts the flow and connects to the rest of the canvas like any other node.
example=../../code/flow/components/pill/flow.vue
:::

::: example Loading || Set `isLoading` to swap the leading icon for a spinner in the same tinted tile. A chain of pills walks itself: the running stage spins, finished ones flip to a check.
example=../../code/flow/components/pill/loading.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)

---

---
url: 'https://flux-ui.dev/flow/components/step.md'
---

# Step

`FluxFlowStep` is a small marker that names a step. Place it in its own [Node](./node) and wire it up like any other node, so the trunk of a flow runs straight through it while each step branches off to the side.

A single character keeps the marker square. Give it a word and it widens to fit, which suits a flow whose steps are named rather than numbered.

::: render
render=../../code/flow/components/step/preview.vue
:::

## Examples

::: example Numbered steps || The trunk runs from marker to marker; every marker points at the step it numbers.
example=../../code/flow/components/step/flow.vue
:::

::: example Values || Digits, letters and words all sit in the same marker.
example=../../code/flow/components/step/values.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)

---

---
url: 'https://flux-ui.dev/flow/components/terminal.md'
---

# Terminal

`FluxFlowTerminal` is the start and the end of a flow: the capsule a classic flowchart opens and closes with. Place it in its own [Node](./node) and connect it like any other node.

Where a [Pill](./pill) names a step on a raised surface, a terminal is one solid tinted capsule, so an endpoint never reads as another step in the chain.

::: render
render=../../code/flow/components/terminal/preview.vue
:::

::: tip
An endpoint has nothing before or after it, so drop the marker on that side of its connector: `marker-start="none"` on the line leaving a start, `marker-end="none"` on the line reaching an end.
:::

## Examples

::: example In a flow || A start terminal heads the flow and an end terminal closes it, with the steps in between.
example=../../code/flow/components/terminal/flow.vue
:::

::: example Colors || A terminal accepts any FluxColor, which is enough to tell a clean finish from a failed one.
example=../../code/flow/components/terminal/colors.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)

---

---
url: 'https://flux-ui.dev/flow/components/junction.md'
---

# Junction

`FluxFlowJunction` is the knot in a flow: the point where several lines meet, or where one line splits into many. Place it in its own [Node](./node) and wire it up like any other node, so three connectors reaching it and one leaving it read as a single merge instead of three lines crossing.

It is a connection point, not a step, so it carries no label. A [Step](./step) numbers a stage of the flow; a junction only says the wiring comes together here.

::: render
render=../../code/flow/components/junction/preview.vue
:::

## Examples

::: example Merging sources || Three sources land on one junction, and a single connector carries them into the step that consumes them. Dropping the marker on the connectors that meet keeps the junction itself the only shape at that point.
example=../../code/flow/components/junction/flow.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)

---

---
url: 'https://flux-ui.dev/flow/components/gate.md'
---

# Gate

`FluxFlowGate` is the diamond of a flow: the point where several lines have to agree, or where exactly one of many branches is taken. It says out loud what a [Junction](./junction) leaves implicit, which is why it carries its rule (`and`, `or` or `xor`) in the shape itself.

Place it in its own [Node](./node) and wire it up like any other node. Its four points sit on the sides a connector attaches to, so lines land on the diamond rather than next to it.

::: render
render=../../code/flow/components/gate/preview.vue
:::

::: tip
Reach for a [Junction](./junction) when lines simply come together, and for a gate when the way they come together is part of the flow.
:::

## Examples

::: example One branch only || An `xor` gate splits a payment into the two routes it can take. The branches leave through the top and bottom points of the diamond, so neither line has to share a corner with the other. Dropping the marker on the line that arrives keeps the diamond the only shape at that point.
example=../../code/flow/components/gate/flow.vue
:::

::: example Any one of them || An `or` gate lets three conditions feed the same action. Two of them land on the top and bottom points and the third runs straight into the left one, so the gate takes three lines without any of them crossing.
example=../../code/flow/components/gate/any-of.vue
:::

::: example Gates in sequence || Both conditions have to hold before an order ships, and only then does the shipping method split in two. A gate can hand off to another gate directly, with no card in between.
example=../../code/flow/components/gate/chained.vue
:::

::: example Without a tint || Left without a `color`, the diamond is drawn in the same gray as a plain connector. Use it when the gate is only wiring and the steps around it carry the emphasis.
example=../../code/flow/components/gate/plain.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Card](./card)
* [Connection](./connection)
* [Pill](./pill)

---

---
url: 'https://flux-ui.dev/flow/components/group.md'
---

# Group

`FluxFlowGroup` draws a labelled frame behind a set of nodes: a retry block, a stage of a pipeline, the part of a flow that runs on one machine. It names the nodes it encloses by id and measures the frame from them, so it follows along when they move.

A group is a backdrop, not a node. It renders behind every card on the canvas, never takes a pointer, and nothing anchors a connector to it.

::: render
render=../../code/flow/components/group/preview.vue
:::

::: tip
An id that matches no node is skipped without a word, so a group survives a card that is only rendered under a condition.
:::

## Examples

::: example Two stages || A frame per stage, each in its own tint. The frames grow with the cards inside them, so a chain that gains a step keeps its group.
example=../../code/flow/components/group/flow.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Chain](./chain)
* [Card](./card)

---

---
url: 'https://flux-ui.dev/flow/components/lane.md'
---

# Lane

`FluxFlowLane` is the swimlane of a flow: a band with a titled gutter that says who owns the part of the canvas standing on it. Client and server, the two teams a handover runs between, the machine a stage runs on.

A lane is a backdrop and nothing more. It never positions its content: the nodes keep their own absolute `x` and `y`, and the lane is the strip they happen to stand on.

::: render
render=../../code/flow/components/lane/preview.vue
:::

::: tip
The pair of props you give picks the axis: `y` and `height` make a row, `x` and `width` make a column. The other axis is not yours to set, since a lane always spans the whole flow.
:::

## Examples

::: example Columns || `x` and `width` turn the band on its side, so a handover between two teams reads left to right with the title above each column. The steps inside a column are placed by a [Chain](./chain), which lines up pills of different widths that a lane would not.
example=../../code/flow/components/lane/columns.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Card](./card)

---

---
url: 'https://flux-ui.dev/flow/components/note.md'
---

# Note

`FluxFlowNote` is an annotation on the canvas: the remark that explains why a step is there, or what the person reading the flow has to know about it.

A note is a full node rather than a decoration, so it gets an `id` through its [Node](./node) like everything else and you hang it off the step it belongs to with a connector. A dashed line without markers reads as a remark rather than as a step in the flow.

::: render
render=../../code/flow/components/note/preview.vue
:::

## Examples

::: example Annotating a flow || Two notes hang off the steps they explain. Dashed connectors without markers keep them out of the flow itself.
example=../../code/flow/components/note/flow.vue
:::

## Used components

* [Flow](./flow)
* [Node](./node)
* [Connection](./connection)

---

---
url: 'https://flux-ui.dev/flow/components/panel.md'
---

# Panel

`FluxFlowPanel` pins its content to a corner of the viewport instead of to the canvas. Everything else written inside a [Flow](./flow) lives in the world and travels with it; a panel sits above that world and stays where it is while the flow pans and zooms underneath.

Write it anywhere inside the flow. Where it sits in your markup makes no difference: the corner is the `position` prop.

::: render
render=../../code/flow/components/panel/preview.vue
:::

::: tip
A panel takes its own presses back, so a button or a field inside one never starts a pan. It is also transparent to the pointer everywhere it does not cover, so the canvas below keeps the rest of the surface.
:::

::: tip
[Controls](./controls) and [Minimap](./minimap) are panels with something ready-made in them. Reach for `FluxFlowPanel` directly when you need a corner of the viewport for something else.
:::

## Used components

* [Flow](./flow)

---

---
url: 'https://flux-ui.dev/flow/components/controls.md'
---

# Controls

`FluxFlowControls` is the button bar of an interactive canvas: zoom out, the current zoom level, zoom in, and take the flow fullscreen. Write it anywhere inside a [Flow](./flow) and it pins itself to a corner of the viewport, so it stays put while the flow pans and zooms behind it.

It renders nothing on a flow without `interactive`, since there is nothing there to zoom.

The zoom level sits between the two zoom buttons and is a button of its own: it opens a flyout holding 200%, 150%, 100%, 75%, 50% and fit view. A level zooms about the middle of the viewport, so what is being looked at stays where it is, and a level the flow cannot reach is left out of the list: a canvas capped with `max-zoom` never offers one.

Fullscreen hands the whole screen to the flow, panels and all, and leaves the zoom and the position alone: the flow only gains room. The button sits apart from the zoom buttons, and it is left out entirely on a browser that does not allow fullscreen.

::: render
render=../../code/flow/components/controls/preview.vue
:::

::: tip
The buttons carry an icon and no text of their own, so every name the bar holds is a prop rather than a fixed string: set `fit-label`, `fullscreen-label`, `exit-fullscreen-label`, `zoom-in-label`, `zoom-label` and `zoom-out-label` to the language of your application. The zoom levels are percentages, which need no translating.
:::

## Examples

::: example Corner || Point `position` at the corner the bar belongs in. It is the same prop a [Panel](./panel) takes, so controls and a panel of your own line up on the same grid.
example=../../code/flow/components/controls/position.vue
:::

## Used components

* [Flow](./flow)
* [Panel](./panel)

---

---
url: 'https://flux-ui.dev/flow/components/minimap.md'
---

# Minimap

`FluxFlowMinimap` is the whole flow at a glance: a block per node and a frame around the part of it currently on screen. Click or drag on the map to move the viewport there, which is how you cross a flow that reaches well past its container without panning your way over.

It renders nothing on a flow without `interactive`, since a flow that shows all of itself has nothing to map.

::: render
render=../../code/flow/components/minimap/preview.vue
:::

::: tip
The map fits the nodes, not the whole world, so panning past the flow does not shrink every block. The frame is allowed to run off the edge of the map: that is what tells you the viewport sits beside the flow rather than on it.
:::

::: tip
Blocks are drawn in one flat gray. A minimap says where things are, not what they are; the color of a card belongs on the card.
:::

## Used components

* [Flow](./flow)
* [Panel](./panel)

---

---
url: 'https://flux-ui.dev/flow/composables/useFlowLayout.md'
---
# useFlowLayout

`useFlowLayout` turns a graph into a drawing. Hand it your nodes and edges and it returns a position per node id plus the connections between them, ready to bind to `FluxFlowNode` and `FluxFlowConnection`. Where a [Chain](../components/chain) places a run of steps in a line, this places a graph that branches and comes back together.

It is a plain function: no component, no DOM and no reactivity. Nodes are laid out in layers, every node lands one layer past its furthest source, and every layer is centred against the widest one, so a straight stretch of the graph stays straight.

## Usage

```ts
import { useFlowLayout } from '@flux-ui/flow';

const {positions, connections} = useFlowLayout(
    [{id: 'intake'}, {id: 'verify'}, {id: 'score'}],
    [{from: 'intake', to: 'verify'}, {from: 'verify', to: 'score'}]
);

// positions:   { intake: {x: 0, y: 0}, verify: {x: 0, y: 150}, … }
// connections: [{from: 'intake', to: 'verify', fromSide: 'bottom', toSide: 'top'}, …]
```

Both are meant to be spread straight onto the components:

```vue
<FluxFlowNode
    v-for="node of nodes"
    :key="node.id"
    :id="node.id"
    v-bind="positions[node.id]">
    <FluxFlowActionCard :title="node.title"/>
</FluxFlowNode>

<FluxFlowConnection
    v-for="wire of connections"
    :key="`${wire.from} ${wire.to}`"
    v-bind="wire"/>
```

::: render
render=../../code/flow/composables/useFlowLayout/preview.vue
:::

::: tip
The function runs without a DOM, so it cannot measure a card. Nodes without a `width` and `height` of their own fall back to `nodeWidth` and `nodeHeight`; pass the size your cards actually have to keep the gaps even.
:::

::: tip
The sides come with the connections, so you never name them yourself. Binding a bare `from` and `to` instead leaves each connector picking the shortest axis between the two cards, and in a layer wider than it is deep that is the wrong one. Setting [`axis`](../components/flow) on the surrounding `FluxFlow` fixes that for hand placed nodes too.
:::

## Example

::: example Left to right || A release pipeline laid out with `direction: 'horizontal'`. The retry edge closes a cycle, which the layout cuts open instead of following, so the run still lands in four layers.
example=../../code/flow/composables/useFlowLayout/horizontal.vue
:::

## Options

### direction (`'vertical'`)

The axis the layers stack on. `vertical` runs top to bottom, `horizontal` runs left to right.

### layerGap (`60`)

The space, in pixels, between two layers.

### nodeGap (`45`)

The space, in pixels, between two nodes inside one layer.

### nodeWidth (`300`) and nodeHeight (`90`)

The size assumed for a node that does not carry one, since the function runs without a DOM.

### x (`0`) and y (`0`)

The top-left corner the layout starts from.

## Cycles

Only directed acyclic graphs lay out in layers, but a graph that loops back on itself is not an error here. An edge that would close a cycle is cut rather than followed, so a retry or a rollback still produces a usable layout instead of an empty one.

A cut edge runs against the flow, and its connection says so: it leaves and enters on the off axis, looping around the diagram instead of cutting back across it. You do not have to work out which edge that was.

Edges to a node that was never given, and edges from a node to itself, are dropped. They are missing from `connections` too, so iterating over it never leaves a connector pointing at nothing.

## Type declarations

```ts
type FluxFlowLayoutNode = {
    readonly id: string;
    readonly width?: number;
    readonly height?: number;
};

type FluxFlowLayoutEdge = {
    readonly from: string;
    readonly to: string;
};

type FluxFlowLayoutOptions = {
    readonly x?: number;
    readonly y?: number;
    readonly direction?: 'horizontal' | 'vertical';
    readonly layerGap?: number;
    readonly nodeGap?: number;
    readonly nodeWidth?: number;
    readonly nodeHeight?: number;
};

type FluxFlowLayoutConnection = {
    readonly from: string;
    readonly to: string;
    readonly fromSide: 'top' | 'right' | 'bottom' | 'left';
    readonly toSide: 'top' | 'right' | 'bottom' | 'left';
};

type FluxFlowLayoutResult = {
    readonly positions: Record<string, { readonly x: number; readonly y: number }>;
    readonly connections: readonly FluxFlowLayoutConnection[];
};

declare function useFlowLayout(
    nodes: readonly FluxFlowLayoutNode[],
    edges: readonly FluxFlowLayoutEdge[],
    options?: FluxFlowLayoutOptions
): FluxFlowLayoutResult;
```

---

---
url: 'https://flux-ui.dev/flow/examples.md'
---

# Examples

The component pages each cover one building block in isolation. This page does the opposite: complete flows, built the way you would build them in an app. Every example is runnable, so open the Code tab to see the whole thing, positions and wiring included.

## Automations

::: example Routing rules || A trigger pill heads the flow, numbered markers run down the trunk, and every condition fans out to a labeled branch. This is the shape most automation builders end up with.
example=../code/flow/examples/routing.vue
:::

::: example Onboarding || A chain places the run of steps and wires it up, and a group frames the two that belong together. Only the branch that leaves the chain carries a coordinate of its own.
example=../code/flow/examples/onboarding.vue
:::

::: example Deploy pipeline || A CI/CD flow: a push builds an image, tests gate the release, and the outcome branches to a deploy or an alert. Colored and dashed connectors separate the happy path from the failure path.
example=../code/flow/examples/deploy.vue
:::

::: example Knowledge graph || Data sources feeding structured skills that compile into an output. It combines card rows, colored and dashed connectors and endpoint markers into one dense canvas.
example=../code/flow/examples/knowledge.vue
:::

::: example Branching on ports || A fraud check whose two outcomes each carry their own port, so a branch leaves the card at the answer it belongs to. Terminals open and close the run, and a note explains the manual step.
example=../code/flow/examples/ports.vue
:::

## Live flows

Nothing about a card is read only. Because the body is plain markup, controls inside it keep working on the canvas, which lets a flow double as the control surface for the process it draws.

::: example Enable and disable || A FluxToggle in the trigger card switches the automation on and off; the downstream cards and connectors follow its state.
example=../code/flow/examples/enable.vue
:::

::: example Approval step || A FluxSecondaryButton in a card footer resolves an approval, which activates the next node and fills its connector.
example=../code/flow/examples/approval.vue
:::

::: example Run on demand || A FluxPrimaryButton kicks off a run: a FluxStatisticsMeter animates the build while the connectors fill from stage to stage.
example=../code/flow/examples/live.vue
:::

::: example Running pipeline || A nightly sync walks its own stages: the step that is busy carries a spinner in place of its icon, its connector fills while it runs, and a finished stage flips to a check and a Done badge.
example=../code/flow/examples/running.vue
:::

## Used components

* [Flow](./components/flow)
* [Node](./components/node)
* [Chain](./components/chain)
* [Connection](./components/connection)
* [Group](./components/group)
* [Port](./components/port)
* [Card](./components/card)
* [Pill](./components/pill)
* [Step](./components/step)
* [Terminal](./components/terminal)
* [Note](./components/note)

---

---
url: 'https://flux-ui.dev/application.md'
---
# Flux Application

Flux Application is a collection of components designed for building modern, route-driven application shells. It provides a complete layout system with a multi-level context menu, sticky top bar, hero header, and right side panel, giving you everything you need to ship a polished application interface without reinventing the layout.

The package builds on Vue Router and uses [named views](https://router.vuejs.org/guide/essentials/named-views.html) to render context-specific menus next to each route, so every level of a nested route tree can contribute its own navigation.

---

---
url: 'https://flux-ui.dev/application/introduction/installation.md'
---
# Installation

To start using Flux Application in your Vue application, you'll need to add it to your project. This section provides step-by-step instructions on how to install Flux Application, ensuring you can quickly integrate its components into your development workflow.

::: tip
Flux Application relies on [Vue Router](../../guide/introduction/installation/vue-router) for its named-view based context menus. Make sure Vue Router is installed and configured in your project before using the components.
:::

## Plain installation

::: tip
This is the most recommended way to use Flux Application. Use this form of installation if you don't need to customize the style of Flux Application or if you simply need to use the components without the source code.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/application @flux-ui/components
```

```shell [PNPM]
pnpm install @flux-ui/application @flux-ui/components
```

```shell [Yarn]
yarn add @flux-ui/application @flux-ui/components
```

```shell [NPM]
npm install @flux-ui/application @flux-ui/components
```

:::

### Step 2

Once the installation is complete, you need to add the following line to your `main.ts` file:

```ts [main.ts]
import '@flux-ui/application/style.css'
import '@flux-ui/components/style.css'
```

### Step 3

Import the components you want to use, like this:

```vue [App.vue]
<template>
    <FluxApplication> <!-- [!code focus:13] -->
        <template #menu>
            <FluxApplicationMenu>
                <!-- Menu items. -->
            </FluxApplicationMenu>
        </template>

        <FluxApplicationContent>
            <FluxApplicationHero
                title="Welcome"
                subtitle="Your application starts here."/>
        </FluxApplicationContent>
    </FluxApplication>
</template>

<script
    setup
    lang="ts">
    import { FluxApplication, FluxApplicationContent, FluxApplicationHero, FluxApplicationMenu } from '@flux-ui/application' // [!code focus]
</script>
```

## Vite-preset installation

::: tip
Only use this form of installation if you need more control of Flux Application and need the Flux Application source code injected into your own project.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [Bun]
bun add @flux-ui/application @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [PNPM]
pnpm install @flux-ui/application @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [Yarn]
yarn add @flux-ui/application @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [NPM]
npm install @flux-ui/application @flux-ui/components sass-embedded @basmilius/vite-preset
```

:::

### Step 2

Once the installation is complete, you need to configure your `vite.config.ts` file to use Flux Application.

::: tip
For more information on the vite-preset package, please refer to [@basmilius/vite-preset](https://github.com/basmilius/packages/tree/main/packages/vite-preset).
:::

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { flux, fluxApplication, preset } from '@basmilius/vite-preset'

export default defineConfig({
    plugins: [
        vue(),
        preset(),
        flux(),
        fluxApplication()
    ]
});
```

### Step 3

Import the components you want to use as shown in step 3 of the plain installation.

---

---
url: 'https://flux-ui.dev/application/components/application.md'
---

# Application

The application component provides the overall layout structure for the application interface. It defines regions for the menu sidebar, the main content, and an optional side panel. This component also manages the collapsed state of the menu and the active context level, and shares that state with child components through [`useApplicationInjection`](../composables/useApplicationInjection).

## Snippet

::: code-group

```vue \[FluxApplication.vue]
<template>
    <FluxApplication>
        <template #menu>
            <FluxApplicationMenu>
                <!-- Menu items. -->
            </FluxApplicationMenu>
        </template>

        <FluxApplicationTop title="Page title"/>

        <FluxApplicationContent>
            <!-- Your application content here. -->
        </FluxApplicationContent>

        <template #side>
            <FluxApplicationSide>
                <!-- Side bar content. -->
            </FluxApplicationSide>
        </template>
    </FluxApplication>
</template>

<script
    setup
    lang="ts">
    import { FluxApplication, FluxApplicationContent, FluxApplicationMenu, FluxApplicationSide, FluxApplicationTop } from '@flux-ui/application';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/application/components/content.md'
---

# Application content

The application content component is the main `<main>` region of the application. It accepts a `layout` prop that controls the maximum width and spacing of the content. The selected layout is also published back into the `FluxApplication` injection, so other components such as [Application top](./top) can adjust their tab bar width to match.

The available layouts are `default`, `dashboard`, `full`, `medium` and `narrow`.

## Snippet

::: code-group

```vue \[FluxApplicationContent.vue]
<template>
    <FluxApplicationContent layout="default">
        <!-- Your application content here. -->
    </FluxApplicationContent>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationContent } from '@flux-ui/application';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/application/components/hero.md'
---

# Application hero

The application hero introduces a page with a clear title and optional subtitle. It is the recommended starting point of any [Application content](./content) area and supports four positional slots (`start`, `before`, `after` and `end`) for adding contextual elements like back buttons, badges, breadcrumbs, or actions.

::: render
render=../../code/application/hero/preview.vue
:::

## Examples

::: example With actions || Render action buttons next to the title using the `end` slot.
example=../../code/application/hero/with-actions.vue
:::

---

---
url: 'https://flux-ui.dev/application/components/menu.md'
---

# Application menu

The application menu is the sidebar of `FluxApplication`. It hosts the main menu and any number of context menu panels that slide in horizontally as the user navigates deeper into the route tree. When more than one level is visible, page indicator dots are rendered at the bottom so the user can jump to any level directly.

The collapsed state of the menu is shared with the rest of the application through [`useApplicationInjection`](../../composables/useApplicationInjection).

## Snippet

::: code-group

```vue \[FluxApplicationMenu.vue]
<template>
    <FluxApplicationMenu>
        <template #header>
            <!-- Optional header (e.g. a logo). -->
        </template>

        <!-- Main menu items. -->

        <template #context>
            <FluxApplicationMenuContextStack/>
        </template>

        <template #footer>
            <!-- Optional footer (e.g. an account menu item). -->
        </template>
    </FluxApplicationMenu>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenu, FluxApplicationMenuContextStack } from '@flux-ui/application';
</script>

```

:::

## Used components

* [Application menu](./)
  * [Account](./account)
  * [Context](./context)
  * [Context stack](./context-stack)
  * [Promo](./promo)
  * [Toggle](./toggle)

---

---
url: 'https://flux-ui.dev/application/components/menu/account.md'
---

# Application menu account

The application menu account renders the current user as the last item of the menu footer. Provide a `label` and optionally an avatar through `image-src` or the `avatar` slot. When the `switcher` slot is provided, the item becomes clickable and reveals a flyout with the slot content, a perfect place for an account switcher.

## Snippet

::: code-group

```vue \[FluxApplicationMenuAccount.vue]
<template>
    <FluxApplicationMenuAccount
        label="Bas Milius"
        image-alt="Bas Milius"
        image-src="https://avatars.githubusercontent.com/u/978257?v=4">
        <template #switcher>
            <FluxMenu>
                <FluxMenuItem
                    icon-leading="user"
                    label="Profile"/>

                <FluxMenuItem
                    icon-leading="gear"
                    label="Settings"/>

                <FluxMenuItem
                    icon-leading="arrow-right-from-bracket"
                    label="Sign out"/>
            </FluxMenu>
        </template>
    </FluxApplicationMenuAccount>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenuAccount } from '@flux-ui/application';
    import { FluxMenu, FluxMenuItem } from '@flux-ui/components';
</script>

```

:::

## Used components

* [Flyout](../../../components/flyout)
* [Menu](../../../components/menu)
  * [Item](../../../components/menu/item)
* [Pane](../../../components/pane)

---

---
url: 'https://flux-ui.dev/application/components/menu/context.md'
---

# Application menu context

The application menu context is the header of a context menu panel. It renders the title and subtitle of the current context together with a back button that either navigates to the parent level (when the user has drilled down through the context stack) or follows the route passed via `to`/`href` (when the user opened the context directly).

The component automatically registers its title and subtitle in the parent `FluxApplication`, so other components, such as the breadcrumbs in the top bar, can reflect the current context.

## Snippet

::: code-group

```vue \[FluxApplicationMenuContext.vue]
<template>
    <FluxApplicationMenuContext
        title="Project Aurora"
        subtitle="Settings"
        :to="{name: 'projects'}"/>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenuContext } from '@flux-ui/application';
</script>

```

:::

## Used components

* [Button](../../../components/button)
  * [Secondary](../../../components/button/secondary)

---

---
url: 'https://flux-ui.dev/application/components/menu/context-stack.md'
---

# Application menu context stack

The application menu context stack renders a context menu panel for every matched route record that exposes a named view. Each panel slides in horizontally as the user drills deeper into the route tree.

To use it, expose a `menu` named view on every route that should contribute a context menu:

```ts [router.ts]
const routes: RouteRecordRaw[] = [
    {
        path: '/projects/:id',
        components: {
            default: () => import('./views/ProjectOverview.vue'),
            menu: () => import('./views/ProjectMenu.vue') // [!code focus]
        }
    }
];
```

The matched menu components are then rendered through `<FluxApplicationMenuContextStack>` in the order of their depth in `route.matched`.

## Snippet

::: code-group

```vue \[FluxApplicationMenuContextStack.vue]
<template>
    <FluxApplicationMenu>
        <!-- Main menu items. -->

        <template #context>
            <FluxApplicationMenuContextStack name="menu"/>
        </template>
    </FluxApplicationMenu>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenu, FluxApplicationMenuContextStack } from '@flux-ui/application';
</script>

```

:::

## Used components

* [Application menu](./)
* [Menu](../../../components/menu)

---

---
url: 'https://flux-ui.dev/application/components/menu/promo.md'
---

# Application menu promo

The application menu promo is a small content block that you can drop inside the menu sidebar to highlight a feature, advertise a plan upgrade, or surface contextual help.

::: render
render=../../../code/application/menu/promo/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxApplicationMenuPromo.vue]
<template>
    <Preview>
        <FluxApplicationMenuPromo icon="sparkles">
            <strong>Upgrade to Pro</strong>
            <p>Unlock advanced analytics and unlimited projects.</p>
        </FluxApplicationMenuPromo>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenuPromo } from '@flux-ui/application';
</script>

```

:::

## Used components

* [Icon](../../../components/icon)

---

---
url: 'https://flux-ui.dev/application/components/menu/toggle.md'
---

# Application menu toggle

The application menu toggle is the button that collapses or expands the menu sidebar. It is rendered automatically by [Application top](../top), but you can also place it inside the menu itself, for example as a footer item, to give the user an alternative way to collapse the menu.

The toggle reads its state from [`useApplicationInjection`](../../composables/useApplicationInjection), so it always reflects the current menu state.

## Snippet

::: code-group

```vue \[FluxApplicationMenuToggle.vue]
<template>
    <FluxApplicationMenuToggle/>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationMenuToggle } from '@flux-ui/application';
</script>

```

:::

## Used components

* [Menu](../../../components/menu)
  * [Item](../../../components/menu/item)

---

---
url: 'https://flux-ui.dev/application/components/section.md'
---

# Application section

The application section groups related content under an optional `<h2>` header. Use it to break the content of a page into clearly labelled blocks. The header can also display a small piece of meta information through the `info` prop and an action through the `end` slot.

::: render
render=../../code/application/section/preview.vue
:::

## Snippet

::: code-group

```vue \[FluxApplicationSection.vue]
<template>
    <Preview>
        <FluxApplicationSection
            title="Recent projects"
            info="3 active">
            <template #end>
                <FluxSecondaryButton
                    label="View all"/>
            </template>

            <FluxPane>
                <FluxPaneBody>
                    Project content goes here.
                </FluxPaneBody>
            </FluxPane>
        </FluxApplicationSection>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationSection } from '@flux-ui/application';
    import { FluxPane, FluxPaneBody, FluxSecondaryButton } from '@flux-ui/components';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/application/components/side.md'
---

# Application side

The application side renders an `<aside>` panel on the right-hand side of the application. Use it for secondary information that complements the current view, for example a chat, a context panel, or a help drawer. Place it inside the `side` slot of [Application](./application).

::: tip Accessibility
The panel renders as an `<aside>` landmark, so assistive technology lists it among the page's regions. Pass an `aria-label` to give it a distinct, meaningful name when the page has more than one complementary region.
:::

## Snippet

::: code-group

```vue \[FluxApplicationSide.vue]
<template>
    <FluxApplicationSide>
        <!-- Side panel content. -->
    </FluxApplicationSide>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationSide } from '@flux-ui/application';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/application/components/top.md'
---

# Application top

The application top is the sticky header of the application. It hosts the menu toggle, an optional icon and title, and two slots (`start` and `end`) for additional content. When the user scrolls, the top bar gains a subtle elevation so it visually separates from the content below.

The component also exposes a `tabs` slot. When provided, a `FluxTabBar` is rendered below the title so the user can switch between the views of the current page. The tab bar width follows the layout published by [Application content](./content).

## Snippet

::: code-group

```vue \[FluxApplicationTop.vue]
<template>
    <FluxApplicationTop
        icon="house"
        title="Dashboard">
        <template #end>
            <FluxPrimaryButton
                icon-leading="plus"
                label="New"/>
        </template>

        <template #tabs>
            <FluxTabBarItem
                label="Overview"
                :to="{name: 'dashboard.overview'}"/>

            <FluxTabBarItem
                label="Activity"
                :to="{name: 'dashboard.activity'}"/>
        </template>
    </FluxApplicationTop>
</template>

<script
    setup
    lang="ts">
    import { FluxApplicationTop } from '@flux-ui/application';
    import { FluxPrimaryButton, FluxTabBarItem } from '@flux-ui/components';
</script>

```

:::

## Used components

* [Menu](./menu/)
  * [Toggle](./menu/toggle)
* [Icon](../../components/icon)
* [Layout](../../components/layout)
  * [Spacer](../../components/layout/spacer)
* [Tab bar](../../components/tab-bar)
* Transitions
  * [Fade](../../components/transitions/fade)
  * [Route](../../components/transitions/route)

---

---
url: 'https://flux-ui.dev/application/composables/useApplicationContextMenu.md'
---
# useApplicationContextMenu

This composable inspects the current route tree for routes that expose a named view and reports whether a context menu should be rendered. Use it to conditionally render UI that depends on whether the current route has its own context menu, for example a back button in a custom top bar.

## Usage

```ts
import { useApplicationContextMenu } from '@flux-ui/application';

const {hasContextMenu, contextMenuKey} = useApplicationContextMenu();
```

## Type declarations

```ts
declare function useApplicationContextMenu(name?: string): UseApplicationContextMenu;

type UseApplicationContextMenu = {
    readonly contextMenuKey: ComputedRef<string | undefined>;
    readonly hasContextMenu: ComputedRef<boolean>;
};
```

## Parameters

---

---
url: 'https://flux-ui.dev/application/composables/useApplicationInjection.md'
---
# useApplicationInjection

This composable provides access to the [Application](../components/application) context. It must be used within a `FluxApplication` component tree.

::: warning
This composable will throw an error if used outside of a [`FluxApplication`](../components/application) component.
:::

## Usage

```ts
import { useApplicationInjection } from '@flux-ui/application';

const application = useApplicationInjection();
```

## Type declarations

```ts
declare function useApplicationInjection(): FluxApplicationInjection;

type FluxApplicationInjection = {
    readonly activeContext: ComputedRef<FluxApplicationContextInfo | undefined>;
    readonly contexts: ComputedRef<readonly FluxApplicationContextInfo[]>;
    readonly isMenuCollapsed: Ref<boolean>;
    readonly layout: Ref<FluxApplicationLayout>;
    readonly showDesktopMenuToggle: Ref<boolean>;
    readonly totalLevels: ComputedRef<number>;
    readonly viewIndex: Ref<number>;
    goToChild(): void;
    goToCurrent(): void;
    goToLevel(index: number): void;
    goToMain(): void;
    goToParent(): void;
    pushContext(info: FluxApplicationContextInfo): void;
    removeContext(id: symbol): void;
};

type FluxApplicationContextInfo = {
    readonly id: symbol;
    readonly title: string;
    readonly subtitle?: string;
    readonly to?: FluxTo;
    readonly entryTo?: FluxTo;
    readonly href?: string;
    readonly type?: FluxPressableType;
};

type FluxApplicationLayout =
    | 'default'
    | 'dashboard'
    | 'full'
    | 'medium'
    | 'narrow';
```

## Used by

* [Application](../components/application)
* [Content](../components/content)
* [Menu](../components/menu/)
  * [Context](../components/menu/context)
  * [Toggle](../components/menu/toggle)
* [Top](../components/top)

---

---
url: 'https://flux-ui.dev/application/composables/useApplicationMenu.md'
---
# useApplicationMenu

This composable is a higher-level wrapper around [`useApplicationInjection`](./useApplicationInjection) that exposes convenience methods and computed properties for working with the application menu: opening and closing it, navigating between menu levels, and inspecting the current state.

::: warning
This composable will throw an error if used outside of a [`FluxApplication`](../components/application) component.
:::

## Usage

```ts
import { useApplicationMenu } from '@flux-ui/application';

const menu = useApplicationMenu();

menu.open();
menu.toggle();
menu.showMainMenu();
menu.showContextMenu();
```

## Type declarations

```ts
declare function useApplicationMenu(): UseApplicationMenu;

type UseApplicationMenu = {
    readonly activeContext: ComputedRef<FluxApplicationContextInfo | undefined>;
    readonly canGoBack: ComputedRef<boolean>;
    readonly canGoForward: ComputedRef<boolean>;
    readonly contexts: ComputedRef<readonly FluxApplicationContextInfo[]>;
    readonly isMainMenuVisible: ComputedRef<boolean>;
    readonly isMenuCollapsed: Ref<boolean>;
    readonly layout: Ref<FluxApplicationLayout>;
    readonly totalLevels: ComputedRef<number>;
    readonly viewIndex: Ref<number>;
    close(): void;
    goToChild(): void;
    goToCurrent(): void;
    goToLevel(index: number): void;
    goToMain(): void;
    goToParent(): void;
    open(): void;
    showContextMenu(): void;
    showMainMenu(): void;
    toggle(): void;
    toggleMainMenu(): void;
};
```

## Used by

* [Application menu](../components/menu)

---

---
url: 'https://flux-ui.dev/statistics.md'
---
# Flux Statistics

Flux Statistics is a collection of components designed for building data-rich dashboards and reporting interfaces. It provides ready-made building blocks for displaying KPIs, metrics, charts, and progress indicators, helping you present data in a clear, structured, and visually consistent way.

---

---
url: 'https://flux-ui.dev/statistics/introduction/installation.md'
---
# Installation

To start using Flux Statistics in your Vue application, you'll need to add it to your project. This section provides step-by-step instructions on how to install Flux Statistics, ensuring you can quickly integrate its components into your development workflow.

## Plain installation

::: tip
This is the most recommended way to use Flux Statistics. Use this form of installation if you don't need to customize the style of Flux Statistics or if you simply need to use the components without the source code.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [bun]
bun add @flux-ui/statistics @flux-ui/components
```

```shell [pnpm]
pnpm install @flux-ui/statistics @flux-ui/components
```

```shell [yarn]
yarn add @flux-ui/statistics @flux-ui/components
```

```shell [npm]
npm install @flux-ui/statistics @flux-ui/components
```

:::

### Step 2

Once the installation is complete, you need to add the following line to your `main.ts` file:

```ts [main.ts]
import '@flux-ui/statistics/style.css'
import '@flux-ui/components/style.css'
```

### Step 3

Import the components you want to use, like this:

```vue [Dashboard.vue]
<template>
    <FluxStatisticsGrid :md="3"> <!-- [!code focus:13] -->
        <FluxStatisticsKpi
            icon="users"
            title="Total users"
            value="12,430"
            :change="{color: 'success', icon: 'arrow-trend-up', value: '+8.2%'}"/>

        <FluxStatisticsKpi
            icon="cart-shopping"
            title="Orders"
            value="3,821"
            :change="{color: 'danger', icon: 'arrow-trend-down', value: '-1.4%'}"/>
    </FluxStatisticsGrid>
</template>

<script
    setup
    lang="ts">
    import { FluxStatisticsGrid, FluxStatisticsKpi } from '@flux-ui/statistics' // [!code focus:2]
</script>
```

## Vite-preset installation

::: tip
Only use this form of installation if you need more control of Flux Statistics and need the Flux Statistics source code injected into your own project.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [bun]
bun add @flux-ui/statistics @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [pnpm]
pnpm install @flux-ui/statistics @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [yarn]
yarn add @flux-ui/statistics @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [npm]
npm install @flux-ui/statistics @flux-ui/components sass-embedded @basmilius/vite-preset
```

:::

### Step 2

Once the installation is complete, you need to configure your `vite.config.ts` file to use Flux Statistics.

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { flux, fluxStatistics, preset } from '@basmilius/vite-preset'

export default defineConfig({
    plugins: [
        vue(),
        preset(),
        flux(),
        fluxStatistics()
    ]
});
```

### Step 3

Import the components you want to use as shown in step 3 of the plain installation.

---

---
url: 'https://flux-ui.dev/statistics/introduction/colors.md'
---
# Chart colors

Flux Statistics provides two pre-defined color palettes for use in charts.

## CHART\_COLORS

A set of four CSS custom properties designed for themed chart colors. These colors adapt to the current theme.

```ts
import { CHART_COLORS } from '@flux-ui/statistics';

// ['var(--chart-1)', 'var(--chart-2)', 'var(--chart-3)', 'var(--chart-4)']
```

## CHART\_COLORFUL\_COLORS

A vibrant palette of 17 colors spanning the full spectrum. These are fixed hex color values from the Flux color system.

```ts
import { CHART_COLORFUL_COLORS } from '@flux-ui/statistics';

// [red500, orange500, amber500, yellow500, lime500, green500, emerald500,
//  teal500, cyan500, sky500, blue500, indigo500, violet500, purple500,
//  fuchsia500, pink500, rose50]
```

## Usage

```vue
<template>
    <FluxStatisticsBarChart
        :data="chartData"
        :colors="CHART_COLORFUL_COLORS"/>
</template>

<script
    setup
    lang="ts">
    import { CHART_COLORFUL_COLORS } from '@flux-ui/statistics';
</script>
```

---

---
url: 'https://flux-ui.dev/statistics/introduction/types.md'
---
# Chart types

Flux Statistics exposes a set of library-agnostic TypeScript types in `@flux-ui/types`. Each chart component accepts data shaped to its own Flux type rather than ECharts options, which lets the visual layer change underneath without touching consumer code.

This page lists every public type with a short description and a minimal example.

## Shared types

### `FluxStatisticsChartColor`

A color specifier accepted by every series, slice, and node. Use one of the named Flux colors (resolved against the active theme) or any hex value.

```ts
type FluxStatisticsChartColor = FluxColor | `#${string}`;
// FluxColor = 'gray' | 'primary' | 'danger' | 'info' | 'success' | 'warning'
```

```ts
const themed: FluxStatisticsChartColor = 'success';   // var(--success-600)
const branded: FluxStatisticsChartColor = '#10b981';  // raw hex
```

### `FluxStatisticsChartCategoryPoint`

A data point that carries its own X-axis label. Cartesian charts accept either bare numbers or category points.

```ts
interface FluxStatisticsChartCategoryPoint {
    readonly label?: string;
    readonly value: number;
}
```

```ts
const dataA: number[] = [12, 24, 18, 32];

const dataB: FluxStatisticsChartCategoryPoint[] = [
    { label: 'Q1', value: 12 },
    { label: 'Q2', value: 24 },
    { label: 'Q3', value: 18 },
    { label: 'Q4', value: 32 }
];
```

## Cartesian series

Used by [Line](../components/charts/line), [Area](../components/charts/area), and [Bar](../components/charts/bar) charts. The three series types are aliases of the same shape; each chart applies its own visual defaults.

### `FluxStatisticsChartCartesianSeries`

```ts
interface FluxStatisticsChartCartesianSeries {
    readonly name?: string;
    readonly data: readonly (number | FluxStatisticsChartCategoryPoint)[];
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}

type FluxStatisticsChartLineSeries = FluxStatisticsChartCartesianSeries;
type FluxStatisticsChartAreaSeries = FluxStatisticsChartCartesianSeries;
type FluxStatisticsChartBarSeries  = FluxStatisticsChartCartesianSeries;
```

```ts
import type { FluxStatisticsChartLineSeries } from '@flux-ui/types';

const series: FluxStatisticsChartLineSeries[] = [
    {
        name: 'Revenue',
        color: 'success',
        icon: 'money-bill',
        data: [4200, 5800, 6400, 7100, 7900, 8800]
    },
    {
        name: 'Costs',
        color: 'danger',
        data: [3100, 3400, 3600, 3900, 4200, 4500]
    }
];
```

When a series has an `icon`, the auto-legend and the shared tooltip both render it.

## Mixed series

Used by the [Mixed chart](../components/charts/mixed) to combine line, area, and bar series in one plot.

### `FluxStatisticsChartMixedSeries`

```ts
interface FluxStatisticsChartMixedSeries extends FluxStatisticsChartCartesianSeries {
    readonly type: 'line' | 'area' | 'bar';
}
```

```ts
import type { FluxStatisticsChartMixedSeries } from '@flux-ui/types';

const series: FluxStatisticsChartMixedSeries[] = [
    { name: 'Revenue', type: 'bar', data: [42, 58, 64, 71] },
    { name: 'Forecast', type: 'area', data: [40, 56, 66, 74] },
    { name: 'Orders', type: 'line', data: [12, 18, 22, 26] }
];
```

## Pie family slices

Used by the [Pie](../components/charts/pie), [Donut](../components/charts/donut), and [Polar area](../components/charts/polar-area) charts. All three accept a `slices` prop instead of `series`.

### `FluxStatisticsChartPieSlice`

```ts
interface FluxStatisticsChartPieSlice {
    readonly label: string;
    readonly value: number;
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartPieSlice } from '@flux-ui/types';

const slices: FluxStatisticsChartPieSlice[] = [
    { label: 'Active', value: 68, color: 'success', icon: 'circle-check' },
    { label: 'Trialing', value: 22, color: 'info', icon: 'hourglass-clock' },
    { label: 'Churned', value: 10, color: 'danger', icon: 'circle-xmark' }
];
```

## Radar series

Used by the [Radar chart](../components/charts/radar). Each series is one ring with one value per indicator. Indicators are passed separately via the `indicators` prop.

### `FluxStatisticsChartRadarSeries`

```ts
interface FluxStatisticsChartRadarSeries {
    readonly name?: string;
    readonly values: readonly number[];
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

### `FluxStatisticsChartRadarIndicator`

```ts
interface FluxStatisticsChartRadarIndicator {
    readonly name: string;
    readonly max?: number;
}
```

```ts
import type {
    FluxStatisticsChartRadarIndicator,
    FluxStatisticsChartRadarSeries
} from '@flux-ui/types';

const indicators: FluxStatisticsChartRadarIndicator[] = [
    { name: 'Speed', max: 100 },
    { name: 'Quality', max: 100 },
    { name: 'Accuracy', max: 100 },
    { name: 'Focus', max: 100 }
];

const series: FluxStatisticsChartRadarSeries[] = [
    { name: 'Q1', values: [82, 65, 73, 91] },
    { name: 'Q2', values: [70, 60, 64, 80] }
];
```

The order of `values` must match the order of `indicators`.

## Scatter series

Used by the [Scatter chart](../components/charts/scatter). Each point is an `{x, y}` coordinate on a 2D plane.

### `FluxStatisticsChartScatterPoint`

```ts
interface FluxStatisticsChartScatterPoint {
    readonly x: number;
    readonly y: number;
}
```

### `FluxStatisticsChartScatterSeries`

```ts
interface FluxStatisticsChartScatterSeries {
    readonly name?: string;
    readonly data: readonly FluxStatisticsChartScatterPoint[];
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartScatterSeries } from '@flux-ui/types';

const series: FluxStatisticsChartScatterSeries[] = [{
    name: 'Products',
    data: [
        { x: 15, y: 3.2 }, { x: 28, y: 3.9 }, { x: 42, y: 4.3 }, { x: 68, y: 4.6 }
    ]
}];
```

## Bubble series

Used by the [Bubble chart](../components/charts/bubble). Extends a scatter point with a third numeric dimension `size`, encoded as the bubble radius.

### `FluxStatisticsChartBubblePoint`

```ts
interface FluxStatisticsChartBubblePoint extends FluxStatisticsChartScatterPoint {
    readonly size: number;
}
```

### `FluxStatisticsChartBubbleSeries`

```ts
interface FluxStatisticsChartBubbleSeries {
    readonly name?: string;
    readonly data: readonly FluxStatisticsChartBubblePoint[];
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartBubbleSeries } from '@flux-ui/types';

const series: FluxStatisticsChartBubbleSeries[] = [{
    name: 'Market cap',
    data: [
        { x: 12, y: 8, size: 24 },
        { x: 22, y: 14, size: 18 },
        { x: 32, y: 26, size: 12 },
        { x: 42, y: 18, size: 30 }
    ]
}];
```

## Candlestick series

Used by the [Candlestick chart](../components/charts/candlestick). Each point holds named OHLC values plus an optional X-axis label. `positiveColor` and `negativeColor` override the default success/danger colors.

### `FluxStatisticsChartCandlestickPoint`

```ts
interface FluxStatisticsChartCandlestickPoint {
    readonly label?: string;
    readonly open: number;
    readonly close: number;
    readonly low: number;
    readonly high: number;
}
```

### `FluxStatisticsChartCandlestickSeries`

```ts
interface FluxStatisticsChartCandlestickSeries {
    readonly name?: string;
    readonly data: readonly FluxStatisticsChartCandlestickPoint[];
    readonly positiveColor?: FluxStatisticsChartColor;
    readonly negativeColor?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartCandlestickSeries } from '@flux-ui/types';

const series: FluxStatisticsChartCandlestickSeries[] = [{
    name: 'Price',
    data: [
        { label: '2026-01-01', open: 102, close: 105, low: 100, high: 108 },
        { label: '2026-01-02', open: 105, close: 109, low: 103, high: 110 },
        { label: '2026-01-03', open: 109, close: 107, low: 106, high: 112 }
    ]
}];
```

## Box plot series

Used by the [Box plot chart](../components/charts/box-plot). Each point is a five-number summary (min, Q1, median, Q3, max).

### `FluxStatisticsChartBoxPlotPoint`

```ts
interface FluxStatisticsChartBoxPlotPoint {
    readonly label?: string;
    readonly min: number;
    readonly q1: number;
    readonly median: number;
    readonly q3: number;
    readonly max: number;
}
```

### `FluxStatisticsChartBoxPlotSeries`

```ts
interface FluxStatisticsChartBoxPlotSeries {
    readonly name?: string;
    readonly data: readonly FluxStatisticsChartBoxPlotPoint[];
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartBoxPlotSeries } from '@flux-ui/types';

const series: FluxStatisticsChartBoxPlotSeries[] = [{
    name: 'Latency',
    data: [
        { label: 'API', min: 54, q1: 66, median: 82, q3: 88, max: 120 },
        { label: 'DB',  min: 22, q1: 30, median: 38, q3: 44, max: 60 }
    ]
}];
```

## Heatmap series

Used by the [Heatmap chart](../components/charts/heatmap). Each point holds named `x`, `y`, and `value` fields. `x` and `y` are either numeric indices or strings matching the `xLabels`/`yLabels` props.

### `FluxStatisticsChartHeatmapPoint`

```ts
interface FluxStatisticsChartHeatmapPoint {
    readonly x: string | number;
    readonly y: string | number;
    readonly value: number;
}
```

### `FluxStatisticsChartHeatmapSeries`

```ts
interface FluxStatisticsChartHeatmapSeries {
    readonly name?: string;
    readonly data: readonly FluxStatisticsChartHeatmapPoint[];
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartHeatmapSeries } from '@flux-ui/types';

const days = ['Mon', 'Tue', 'Wed'];
const weeks = ['W1', 'W2', 'W3', 'W4'];

const series: FluxStatisticsChartHeatmapSeries[] = [{
    data: days.flatMap(day =>
        weeks.map(week => ({ x: week, y: day, value: Math.round(Math.random() * 100) }))
    )
}];
```

## Treemap nodes

Used by the [Treemap chart](../components/charts/treemap). Nodes are recursive. Pass the root level via the `nodes` prop and nest deeper levels through `children`.

### `FluxStatisticsChartTreemapNode`

```ts
interface FluxStatisticsChartTreemapNode {
    readonly name: string;
    readonly value?: number;
    readonly color?: FluxStatisticsChartColor;
    readonly children?: readonly FluxStatisticsChartTreemapNode[];
}
```

```ts
import type { FluxStatisticsChartTreemapNode } from '@flux-ui/types';

const nodes: FluxStatisticsChartTreemapNode[] = [
    {
        name: 'Media',
        value: 1800,
        color: 'primary',
        children: [
            { name: 'Photos', value: 1100 },
            { name: 'Videos', value: 600 }
        ]
    },
    {
        name: 'Documents',
        value: 540,
        color: 'info'
    }
];
```

## Gauge series

Used by the [Radial bar chart](../components/charts/radial-bar). Each entry produces a concentric gauge ring. `radius` is optional. The chart spreads rings automatically when omitted.

### `FluxStatisticsChartGaugeSeries`

```ts
interface FluxStatisticsChartGaugeSeries {
    readonly name: string;
    readonly value: number;
    readonly radius?: number;
    readonly color?: FluxStatisticsChartColor;
    readonly icon?: FluxIconName;
}
```

```ts
import type { FluxStatisticsChartGaugeSeries } from '@flux-ui/types';

const series: FluxStatisticsChartGaugeSeries[] = [
    { name: 'API', value: 94, color: 'success', icon: 'server' },
    { name: 'Database', value: 82, color: 'info', icon: 'database' },
    { name: 'Storage', value: 68, color: 'warning', icon: 'hard-drive' }
];
```

## Escape-hatch: `advancedOptions`

Every chart component exposes an optional `advancedOptions: EChartsOption` prop. The Flux types cover the common cases. When you need something the typed surface doesn't expose (a custom `visualMap`, a non-standard `axisPointer`, a swapped axis), reach for `advancedOptions`. The object is deep-merged on top of the Flux defaults, while series and palette overrides always win.

```vue
<template>
    <FluxStatisticsBarChart
        :advanced-options="advancedOptions"
        :series="series"/>
</template>

<script setup lang="ts">
    import type { EChartsOption } from 'echarts/core';
    import type { FluxStatisticsChartBarSeries } from '@flux-ui/types';
    import { FluxStatisticsBarChart } from '@flux-ui/statistics';

    const series: FluxStatisticsChartBarSeries[] = [{
        name: 'Orders',
        data: [4200, 3100, 1800, 1500]
    }];

    const advancedOptions: EChartsOption = {
        xAxis: {
            type: 'value',
            axisLabel: { color: 'var(--foreground-secondary)' }
        },
        yAxis: {
            type: 'category',
            data: ['NL', 'DE', 'BE', 'FR']
        }
    };
</script>
```

::: tip
Treat `advancedOptions` as the exception, not the rule. Anything you can express with the Flux types stays portable if the underlying chart library is ever swapped out.
:::

## Color resolution

When a `color` is set on a series, slice, or node, Flux resolves it as follows:

| Input | Resolved to |
|---|---|
| `'primary'` (any `FluxColor`) | `var(--primary-600)` |
| `'#10b981'` (any hex) | `'#10b981'` |
| omitted | next color from `CHART_COLORS` (see [Chart colors](./colors)) |

The same color flows into the rendered chart, the [Legend](../components/legend/) (whether manual or auto-generated), and the tooltip, so series stay visually consistent across all three surfaces.

---

---
url: 'https://flux-ui.dev/statistics/components/change.md'
---

# Change

The change component displays a value indicator, typically used to show a trend or delta compared to a previous period. It supports a color and optional icon to convey direction at a glance.

::: render
render=../../code/statistics/components/change/preview.vue
:::

::: tip
This component is best used inside a [KPI](./kpi) or [Metric](./metric) via the `change` prop.
:::

## Examples

::: example Positive || A positive change indicator with a trend-up icon.
example=../../code/statistics/components/change/positive.vue
:::

::: example Negative || A negative change indicator with a trend-down icon.
example=../../code/statistics/components/change/negative.vue
:::

::: example Neutral || A neutral change indicator without an upward or downward trend.
example=../../code/statistics/components/change/neutral.vue
:::

## Used components

* [Icon](../../components/icon)

---

---
url: 'https://flux-ui.dev/statistics/components/charts.md'
---

# Charts

Flux Statistics includes several chart types built on top of [Apache ECharts](https://echarts.apache.org/). Each chart accepts a `series` prop compatible with the ECharts API and an optional `options` prop for customization.

## Available charts

* [Area](./area)
* [Bar](./bar)
* [Box plot](./box-plot)
* [Bubble](./bubble)
* [Candlestick](./candlestick)
* [Donut](./donut)
* [Heatmap](./heatmap)
* [Line](./line)
* [Mixed](./mixed)
* [Pie](./pie)
* [Polar area](./polar-area)
* [Radar](./radar)
* [Radial bar](./radial-bar)
* [Scatter](./scatter)
* [Treemap](./treemap)

::: tip
Charts are best used inside a [Chart pane](../chart-pane) which provides a consistent header and legend area.
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/area.md'
---

# Area chart

The area chart renders a smooth area chart with a gradient fill. It uses sparkline mode by default, hiding axes and labels to present a clean, compact visualization.

::: render
render=../../../code/statistics/components/charts/area/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Multiple series || Comparing two data series in a single area chart.
example=../../../code/statistics/components/charts/area/multi-series.vue
:::

::: example Single series || A single area series for tracking cumulative growth.
example=../../../code/statistics/components/charts/area/single-series.vue
:::

::: example With icons || An area chart whose series carry icons that surface in the legend and tooltip.
example=../../../code/statistics/components/charts/area/with-icons.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/area/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/area/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/bar.md'
---

# Bar chart

The bar chart renders vertical grouped bars with rounded corners. It supports multiple series and shared tooltips.

::: render
render=../../../code/statistics/components/charts/bar/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Multiple series || A grouped bar chart comparing two data series side by side.
example=../../../code/statistics/components/charts/bar/multi-series.vue
:::

::: example Single series || A single series bar chart with a fixed color.
example=../../../code/statistics/components/charts/bar/single-series.vue
:::

::: example Horizontal || A horizontal bar chart configured through `advancedOptions`.
example=../../../code/statistics/components/charts/bar/horizontal.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/bar/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/bar/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/box-plot.md'
---

# Box plot chart

The box plot summarizes the statistical distribution of a dataset using the five-number summary: minimum, lower quartile, median, upper quartile, and maximum. It is the preferred chart type for showing spread, skewness, and outliers across categories.

::: render
render=../../../code/statistics/components/charts/box-plot/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Basic || A box plot comparing distributions across several categories.
example=../../../code/statistics/components/charts/box-plot/basic.vue
:::

::: example Multi category || A wider box plot with more categories on the X axis.
example=../../../code/statistics/components/charts/box-plot/multi-category.vue
:::

::: example Tight distribution || A box plot showing tightly clustered distributions.
example=../../../code/statistics/components/charts/box-plot/tight-distribution.vue
:::

::: example Wide spread || A box plot with wide whiskers showing large variance per route.
example=../../../code/statistics/components/charts/box-plot/wide-spread.vue
:::

::: example Single category || A focused single-category box plot.
example=../../../code/statistics/components/charts/box-plot/single-category.vue
:::

::: example With tooltip || Enable the hover tooltip listing min, quartiles, and max.
example=../../../code/statistics/components/charts/box-plot/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/box-plot/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/bubble.md'
---

# Bubble chart

The bubble chart extends a scatter chart with a third numeric dimension encoded in the radius of each marker. It is ideal for visualizing three-variable relationships such as price, volume, and market cap.

::: render
render=../../../code/statistics/components/charts/bubble/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Three dimensions || A bubble chart visualizing three variables at once.
example=../../../code/statistics/components/charts/bubble/three-dimensions.vue
:::

::: example Multiple series || Two grouped bubble series for category comparison.
example=../../../code/statistics/components/charts/bubble/multi-series.vue
:::

::: example Compact || A more compact bubble chart with smaller markers.
example=../../../code/statistics/components/charts/bubble/compact.vue
:::

::: example With icons || A bubble chart whose series carry icons in the legend.
example=../../../code/statistics/components/charts/bubble/with-icons.vue
:::

::: example Dense || A bubble chart with many randomly distributed points.
example=../../../code/statistics/components/charts/bubble/dense.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/bubble/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/bubble/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/candlestick.md'
---

# Candlestick chart

The candlestick chart renders OHLC (open, high, low, close) data points using a green-on-success / red-on-danger color scheme. It is purpose-built for financial price data, but works equally well for any range-over-time series.

::: render
render=../../../code/statistics/components/charts/candlestick/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example OHLC || A typical candlestick chart with daily OHLC values.
example=../../../code/statistics/components/charts/candlestick/ohlc.vue
:::

::: example Short range || A short-range candlestick chart for intraday data.
example=../../../code/statistics/components/charts/candlestick/short-range.vue
:::

::: example Volatile || A candlestick chart showing a more volatile price series.
example=../../../code/statistics/components/charts/candlestick/volatile.vue
:::

::: example Bull run || A predominantly green candlestick series trending upward.
example=../../../code/statistics/components/charts/candlestick/bull-run.vue
:::

::: example Custom colors || A candlestick chart with branded up and down colors.
example=../../../code/statistics/components/charts/candlestick/custom-colors.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/candlestick/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/candlestick/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/donut.md'
---

# Donut chart

The donut chart renders a hollow pie chart. Tooltips and the legend are hidden by default; use a [Legend](../legend/) to display series labels alongside the chart.

::: render
render=../../../code/statistics/components/charts/donut/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example In a chart pane || A donut chart inside a chart pane with matching colors and a legend.
example=../../../code/statistics/components/charts/donut/in-chart-pane.vue
:::

::: example With icons || A donut chart whose slices carry icons that surface in the legend and tooltip.
example=../../../code/statistics/components/charts/donut/with-icons.vue
:::

::: example Minimal || A focused two-slice donut chart without a legend.
example=../../../code/statistics/components/charts/donut/minimal.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/donut/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/heatmap.md'
---

# Heatmap chart

The heatmap chart visualizes a two-dimensional matrix of values as a grid of colored tiles. It works well for activity calendars, density maps, and any data with two categorical axes and a single numeric value.

::: render
render=../../../code/statistics/components/charts/heatmap/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Activity calendar || A weekly activity heatmap that resembles a contribution graph.
example=../../../code/statistics/components/charts/heatmap/activity-calendar.vue
:::

::: example Single series || A simpler one-series heatmap with custom color ranges.
example=../../../code/statistics/components/charts/heatmap/single-series.vue
:::

::: example Custom colors || A heatmap configured with a custom color scale.
example=../../../code/statistics/components/charts/heatmap/custom-colors.vue
:::

::: example Cohort retention || A retention heatmap that fades as cohorts decay over time.
example=../../../code/statistics/components/charts/heatmap/sparse.vue
:::

::: example Punchcard || A weekly punchcard heatmap highlighting peak working hours.
example=../../../code/statistics/components/charts/heatmap/punchcard.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/heatmap/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/line.md'
---

# Line chart

The line chart renders a smooth line chart in sparkline mode, hiding axes and labels for a compact presentation.

::: render
render=../../../code/statistics/components/charts/line/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Single series || A single series line chart tracking one metric over time.
example=../../../code/statistics/components/charts/line/single-series.vue
:::

::: example With labels || A line chart with month names on the X-axis through the `labels` prop.
example=../../../code/statistics/components/charts/line/with-labels.vue
:::

::: example With icons || A line chart whose series carry icons that surface in the legend and tooltip.
example=../../../code/statistics/components/charts/line/with-icons.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/line/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/line/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/mixed.md'
---

# Mixed chart

The mixed chart combines multiple chart types in the same plot. Each series declares its own `type` (`line`, `bar`, or `area`), making it ideal for pairing a primary metric with a derived series such as volume against price, or actual against target.

::: render
render=../../../code/statistics/components/charts/mixed/preview.vue
:::

::: tip
Set `series[].type` on each series to mix chart types in a single plot.
:::

## Examples

::: example Line and bar || A bar chart of revenue with an overlaid line for orders.
example=../../../code/statistics/components/charts/mixed/line-and-bar.vue
:::

::: example Area and line || An area chart of total users layered with a line for active users.
example=../../../code/statistics/components/charts/mixed/area-and-line.vue
:::

::: example Three series || A combination of bar, line, and area series in one chart.
example=../../../code/statistics/components/charts/mixed/three-series.vue
:::

::: example With icons || A mixed chart whose series carry icons that surface in the legend and tooltip.
example=../../../code/statistics/components/charts/mixed/with-icons.vue
:::

::: example Area with line || An area for open pipeline value layered with a line for closed-won deals.
example=../../../code/statistics/components/charts/mixed/area-with-line.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/mixed/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/mixed/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/pie.md'
---

# Pie chart

The pie chart renders a standard pie chart. Tooltips and the legend are hidden by default; use a [Legend](../legend/) to display series labels alongside the chart.

::: render
render=../../../code/statistics/components/charts/pie/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example In a chart pane || A pie chart inside a chart pane with matching colors and a legend.
example=../../../code/statistics/components/charts/pie/in-chart-pane.vue
:::

::: example Few slices || A focused pie chart with three categorical slices.
example=../../../code/statistics/components/charts/pie/few-slices.vue
:::

::: example Minimal || A simple two-slice pie chart without a legend.
example=../../../code/statistics/components/charts/pie/minimal.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/pie/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/polar-area.md'
---

# Polar area chart

The polar area chart is a variation of the pie chart where each segment has the same angle but a different radius based on its value. It places more emphasis on magnitude than a regular pie or donut.

::: render
render=../../../code/statistics/components/charts/polar-area/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Basic || A simple polar area chart with five segments.
example=../../../code/statistics/components/charts/polar-area/basic.vue
:::

::: example Custom colors || A polar area chart with explicit segment colors.
example=../../../code/statistics/components/charts/polar-area/custom-colors.vue
:::

::: example Many segments || A polar area chart with a larger set of segments.
example=../../../code/statistics/components/charts/polar-area/many-segments.vue
:::

::: example With icons || A polar area chart whose slices carry icons that surface in the legend and tooltip.
example=../../../code/statistics/components/charts/polar-area/with-icons.vue
:::

::: example Few segments || A focused polar area chart with three segments.
example=../../../code/statistics/components/charts/polar-area/few-segments.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/polar-area/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/radar.md'
---

# Radar chart

The radar chart compares multiple variables across one or more series on a circular grid. It is well suited for showing the shape of a feature set, skill profile, or scorecard.

::: render
render=../../../code/statistics/components/charts/radar/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane) to provide a consistent header.
:::

## Examples

::: example Single series || A single series radar chart showing one profile.
example=../../../code/statistics/components/charts/radar/single-series.vue
:::

::: example Multiple series || Two profiles overlaid on the same radar chart for comparison.
example=../../../code/statistics/components/charts/radar/multi-series.vue
:::

::: example With fill || A radar chart with a more pronounced filled area.
example=../../../code/statistics/components/charts/radar/with-fill.vue
:::

::: example With icons || A radar chart whose rings carry icons that surface in the legend.
example=../../../code/statistics/components/charts/radar/with-icons.vue
:::

::: example Many axes || A radar chart with a wider scorecard spanning eight indicators.
example=../../../code/statistics/components/charts/radar/many-axes.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/radar/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/radial-bar.md'
---

# Radial bar

The radial bar chart renders one or more percentage values as concentric circular rings. It is the circular counterpart of the [Meter](../meter) widget and works well as a single-value gauge or a small dashboard ring.

::: render
render=../../../code/statistics/components/charts/radial-bar/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Single value || A single radial ring for one percentage value.
example=../../../code/statistics/components/charts/radial-bar/single-value.vue
:::

::: example Multiple values || Multiple concentric radial bars for related metrics.
example=../../../code/statistics/components/charts/radial-bar/multiple-values.vue
:::

::: example Custom labels || A radial bar with a custom total label in the center.
example=../../../code/statistics/components/charts/radial-bar/with-label.vue
:::

::: example With icons || A radial bar whose rings carry icons that surface in the legend.
example=../../../code/statistics/components/charts/radial-bar/with-icons.vue
:::

::: example Two rings || A compact radial bar with two concentric rings.
example=../../../code/statistics/components/charts/radial-bar/two-rings.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/radial-bar/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/scatter.md'
---

# Scatter chart

The scatter chart plots discrete data points on a two-dimensional grid. It is the preferred chart type for visualizing correlations between two numeric variables.

::: render
render=../../../code/statistics/components/charts/scatter/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Correlation || A scatter chart highlighting the correlation between two variables.
example=../../../code/statistics/components/charts/scatter/correlation.vue
:::

::: example Multiple series || Two overlapping scatter series distinguished by color.
example=../../../code/statistics/components/charts/scatter/multi-series.vue
:::

::: example With markers || A scatter chart with larger, hollow markers for sparse data.
example=../../../code/statistics/components/charts/scatter/with-markers.vue
:::

::: example Clustered || A scatter chart with three visually distinct clusters.
example=../../../code/statistics/components/charts/scatter/clustered.vue
:::

::: example With icons || A scatter chart whose series carry icons in the legend.
example=../../../code/statistics/components/charts/scatter/with-icons.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/scatter/with-tooltip.vue
:::

::: example With axis labels || Show X/Y axis labels and dashed split lines.
example=../../../code/statistics/components/charts/scatter/with-axis-labels.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/charts/treemap.md'
---

# Treemap chart

The treemap chart visualizes proportional data as nested rectangles. Each tile's area is sized according to its value, making it well suited for showing the relative size of categories or hierarchical structures.

::: render
render=../../../code/statistics/components/charts/treemap/preview.vue
:::

::: tip
This component is best used inside a [Chart pane](../chart-pane).
:::

## Examples

::: example Distributed || A single-series treemap with distributed colors.
example=../../../code/statistics/components/charts/treemap/distributed.vue
:::

::: example Custom colors || A treemap that uses a specific Flux color palette.
example=../../../code/statistics/components/charts/treemap/custom-colors.vue
:::

::: example Many categories || A treemap with a large number of small tiles.
example=../../../code/statistics/components/charts/treemap/many-categories.vue
:::

::: example Nested || A two-level treemap showing parent categories and their children.
example=../../../code/statistics/components/charts/treemap/nested.vue
:::

::: example Two categories || A simple two-tile split for a high-level breakdown.
example=../../../code/statistics/components/charts/treemap/two-categories.vue
:::

::: example With tooltip || Enable the hover tooltip by setting the `tooltip` prop.
example=../../../code/statistics/components/charts/treemap/with-tooltip.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/chart-pane.md'
---

# Chart pane

The chart pane wraps a chart in a structured widget with a title, optional icon, and slots for a legend and toolbar. It controls the dimensions of the chart area through aspect ratio and min/max height constraints.

::: render
render=../../code/statistics/components/chart-pane/preview.vue
:::

## Examples

::: example Basic || A chart pane with an area chart, legend, and icon.
example=../../code/statistics/components/chart-pane/basic.vue
:::

::: example With toolbar || A chart pane with an action button in the toolbar slot.
example=../../code/statistics/components/chart-pane/with-toolbar.vue
:::

## Used components

* [Charts](./charts/)
* [Legend](./legend/)

---

---
url: 'https://flux-ui.dev/statistics/components/comparison.md'
---

# Comparison

The comparison widget renders two values side by side, typically a current period and a previous period. It automatically calculates and displays the percentage delta between them with a colored trend indicator.

::: render
render=../../code/statistics/components/comparison/preview.vue
:::

## Examples

::: example Basic || A basic comparison with whole-number values.
example=../../code/statistics/components/comparison/basic.vue
:::

::: example Formatted currency || A comparison with a formatter for currency values.
example=../../code/statistics/components/comparison/formatted-currency.vue
:::

::: example Negative trend || A comparison where the current period is worse than the previous one.
example=../../code/statistics/components/comparison/negative-trend.vue
:::

::: example Custom labels || A comparison with custom period labels and a formatter.
example=../../code/statistics/components/comparison/custom-labels.vue
:::

## Used components

* [Change](./change)

---

---
url: 'https://flux-ui.dev/statistics/components/details-table.md'
---

# Details table

The details table displays a structured list of label/value pairs under a heading. It is suitable for summarizing the attributes or properties of an entity alongside a chart or metric.

::: render
render=../../../code/statistics/components/details-table/preview.vue
:::

::: info
The table is built from plain elements but exposes semantic ARIA table roles: the wrapper is a `table` labelled by its `title` (announced as the `caption`), and the rows are grouped in a `rowgroup` so assistive technologies present it as a real table.
:::

## Examples

::: example Standalone || A details table used without a pane wrapper.
example=../../../code/statistics/components/details-table/standalone.vue
:::

::: example Inside a pane || A details table placed inside a statistics base widget.
example=../../../code/statistics/components/details-table/in-base.vue
:::

## Used components

* [Row](./row)

---

---
url: 'https://flux-ui.dev/statistics/components/details-table/row.md'
---

# Details table row

A single row in a [Details table](./index), displaying a label and its corresponding value.

::: render
render=../../../code/statistics/components/details-table/row/preview.vue
:::

::: tip
This component is best used within a [Details table](./index).
:::

::: info
The row exposes the ARIA `row` role; its label is a `rowheader` and its value is a `cell`, so the pair is announced as a labelled table row.
:::

## Snippet

::: code-group

```vue \[FluxStatisticsDetailsTableRow.vue]
<template>
    <Preview>
        <FluxPane style="min-width: 300px">
            <FluxPaneBody>
                <FluxStatisticsDetailsTable>
                    <FluxStatisticsDetailsTableRow
                        label="Status"
                        value="Paid"/>
                    <FluxStatisticsDetailsTableRow
                        label="Total"
                        value="€ 149.99"/>
                </FluxStatisticsDetailsTable>
            </FluxPaneBody>
        </FluxPane>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxPane, FluxPaneBody } from '@flux-ui/components';
    import { FluxStatisticsDetailsTable, FluxStatisticsDetailsTableRow } from '@flux-ui/statistics';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/statistics/components/empty.md'
---

# Empty

The empty widget provides a placeholder to display inside a [Chart pane](./chart-pane) or [Base](./grid) when there is no data to visualize. It supports an icon, title, description, and a default slot for action elements.

::: render
render=../../code/statistics/components/empty/preview.vue
:::

::: tip
Use this component to replace a chart whenever the data source returns an empty result, instead of rendering an empty chart.
:::

## Examples

::: example With action || An empty state that includes a primary action button.
example=../../code/statistics/components/empty/with-action.vue
:::

::: example Custom icon || An empty state with a topic-specific icon.
example=../../code/statistics/components/empty/custom-icon.vue
:::

::: example Inside a chart pane || An empty state placed inside a chart pane to replace a missing chart.
example=../../code/statistics/components/empty/in-chart-pane.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/grid.md'
---

# Grid

The statistics grid is a responsive layout component for arranging statistics widgets. Column counts can be defined per breakpoint and cascade from smaller to larger screen sizes when not explicitly set.

::: render
render=../../code/statistics/components/grid/preview.vue
:::

## Examples

::: example Responsive || A grid that collapses to one column on small screens and expands to four on large screens.
example=../../code/statistics/components/grid/responsive.vue
:::

::: example Mixed widgets || A grid combining KPI, metric, and meter widgets in a single row.
example=../../code/statistics/components/grid/mixed-widgets.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/kpi.md'
---

# KPI

The KPI (Key Performance Indicator) widget displays a single prominent metric alongside an optional trend indicator and footer. It is compact by default and well suited for use in a [Statistics grid](./grid).

::: render
render=../../code/statistics/components/kpi/preview.vue
:::

## Examples

::: example Simple || A KPI widget without a change indicator.
example=../../code/statistics/components/kpi/simple.vue
:::

::: example In a grid || Multiple KPI widgets arranged in a responsive statistics grid.
example=../../code/statistics/components/kpi/in-grid.vue
:::

## Used components

* [Change](./change)

---

---
url: 'https://flux-ui.dev/statistics/components/legend.md'
---

# Legend

The statistics legend groups [Legend items](./item) together, providing a visual key that maps colors or icons to the data series displayed in a chart.

::: render
render=../../../code/statistics/components/legend/preview.vue
:::

::: tip
This component is best used within a [Chart pane](../chart-pane) via the `legend` slot.
:::

::: info
The legend exposes the ARIA `list` role and its items are `listitem`s. The legend is a single tab stop: Tab moves focus into it, and the arrow keys move between items. Focusing an item drives the same hover synchronization as the mouse, so the linked chart or percentage bar highlights when a legend item is focused with the keyboard.
:::

## Examples

::: example Basic || A legend with two series using a color swatch.
example=../../../code/statistics/components/legend/basic.vue
:::

::: example With values || Legend items that include a percentage value alongside the label.
example=../../../code/statistics/components/legend/with-values.vue
:::

::: example With icons || Set the `icon` prop to replace the color swatch with an icon.
example=../../../code/statistics/components/legend/with-icons.vue
:::

::: example Mixed || Color swatches and icons can be combined within a single legend.
example=../../../code/statistics/components/legend/mixed.vue
:::

::: example Compact || The `compact` variant renders a condensed color dot and label, ideal for use outside of a chart.
example=../../../code/statistics/components/legend/compact.vue
:::

::: example Compact vertical || Set `direction` to `vertical` to stack a compact legend.
example=../../../code/statistics/components/legend/compact-vertical.vue
:::

::: example Compact with icons || The compact variant also supports icons and values.
example=../../../code/statistics/components/legend/compact-icons.vue
:::

## Used components

* [Item](./item)

---

---
url: 'https://flux-ui.dev/statistics/components/legend/item.md'
---

# Legend item

A single entry in a [Legend](./index), consisting of a color swatch or icon, a label, and an optional value.

::: render
render=../../../code/statistics/components/legend/item/preview.vue
:::

::: tip
This component is best used within a [Legend](./index).
:::

::: info
The item exposes the ARIA `listitem` role and is keyboard focusable. Within a [Legend](./index) it is reached through the legend's single tab stop and arrow-key navigation. Its tab order is managed automatically, so you do not set `tabindex` yourself. Focusing an item triggers the same hover synchronization as the mouse, highlighting the matching series in the linked visualization.
:::

## Snippet

::: code-group

```vue \[FluxStatisticsLegendItem.vue]
<template>
    <Preview>
        <FluxStatisticsLegend>
            <FluxStatisticsLegendItem
                color="primary"
                label="Revenue"
                value="€ 48,290"/>
            <FluxStatisticsLegendItem
                icon="cart-shopping"
                label="Orders"
                value="3,821"/>
        </FluxStatisticsLegend>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxStatisticsLegend, FluxStatisticsLegendItem } from '@flux-ui/statistics';
</script>

```

:::

## Used components

* [Icon](../../../components/icon)

---

---
url: 'https://flux-ui.dev/statistics/components/legend-scope.md'
---

# Legend scope

The legend scope is a renderless wrapper that provides a shared chart legend context to its children. It lets you pair any chart or statistics component with a `FluxStatisticsLegend` outside of a `FluxStatisticsChartPane`, while still benefiting from bidirectional hover synchronization between the data visualization and its legend.

`FluxStatisticsChartPane` uses this wrapper internally, so any direct usage of the scope mirrors the same behavior.

::: render
render=../../code/statistics/components/legend-scope/preview.vue
:::

## Examples

::: example With a donut chart || A donut chart paired with a statistics legend in a custom layout, sharing hover state through the scope.
example=../../code/statistics/components/legend-scope/with-donut.vue
:::

::: example With a pie chart || A pie chart with icons paired with a statistics legend outside of a chart pane.
example=../../code/statistics/components/legend-scope/with-pie.vue
:::

## Used components

* [Charts](./charts/)
* [Legend](./legend/)
* [Percentage bar](./percentage-bar)

---

---
url: 'https://flux-ui.dev/statistics/components/meter.md'
---

# Meter

The meter widget visualizes a value as a horizontal progress bar. It supports theming with any Flux color or a custom hex color and can display a title, subtitle, tip, and footer alongside the percentage.

::: render
render=../../code/statistics/components/meter/preview.vue
:::

## Examples

::: example Blocks || The `blocks` variant splits the bar into discrete blocks that fill the available width.
example=../../code/statistics/components/meter/blocks.vue
:::

::: example Compact || Multiple compact meters grouped inside a statistics base widget.
example=../../code/statistics/components/meter/compact.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/metric.md'
---

# Metric

The metric widget is a larger statistics widget that displays a title, label, value, and an optional trend indicator. The default slot can be used to embed additional content such as a chart.

::: render
render=../../code/statistics/components/metric/preview.vue
:::

## Examples

::: example Simple || A metric widget without any content in the default slot.
example=../../code/statistics/components/metric/simple.vue
:::

::: example With a breakdown || A metric widget using the default slot to display a breakdown of values.
example=../../code/statistics/components/metric/with-sparkline.vue
:::

::: example With a meter || A metric widget embedding a blocks meter in the default slot.
example=../../code/statistics/components/metric/with-meter.vue
:::

## Used components

* [Change](./change)

---

---
url: 'https://flux-ui.dev/statistics/components/percentage-bar.md'
---

# Percentage bar

The percentage bar visualizes the proportional breakdown of a collection of items as a single horizontal segmented bar. Each segment can carry an optional icon and label, and integrates with the statistics legend context to provide bidirectional hover synchronization when wrapped in a `FluxStatisticsLegendScope`.

::: render
render=../../code/statistics/components/percentage-bar/preview.vue
:::

::: tip
Negative item values are clamped to `0`, so a malformed data point never renders as a reversed or overlapping segment.
:::

::: info
The bar exposes the ARIA `img` role with an `aria-label` summarizing each segment as a percentage and label, so the breakdown is available to assistive technologies without relying on the visual segments.
:::

## Examples

::: example Basic || A standalone percentage bar using semantic Flux color tokens.
example=../../code/statistics/components/percentage-bar/basic.vue
:::

::: example Scoped with legend || A percentage bar wrapped in a legend scope together with a statistics legend, demonstrating bidirectional hover sync.
example=../../code/statistics/components/percentage-bar/scoped.vue
:::

## Used components

* [Legend](./legend/)
* [Legend scope](./legend-scope)
* [Tooltip](../../components/tooltip)
* [Icon](../../components/icon)

---

---
url: 'https://flux-ui.dev/statistics/components/sparkline.md'
---

# Sparkline

The sparkline is a generic mini-chart designed for inline use, for example next to a KPI value, inside a table cell, or in a tight dashboard slot. It supports `line`, `bar`, and `area` variants and a single explicit color.

::: render
render=../../code/statistics/components/sparkline/preview.vue
:::

## Examples

::: example Line variant || A line sparkline showing a quick trend.
example=../../code/statistics/components/sparkline/line.vue
:::

::: example Bar variant || A bar sparkline emphasizing discrete values.
example=../../code/statistics/components/sparkline/bar.vue
:::

::: example Area variant || An area sparkline with a soft gradient fill.
example=../../code/statistics/components/sparkline/area.vue
:::

::: example Inside a metric || A sparkline displayed alongside a metric value.
example=../../code/statistics/components/sparkline/in-kpi.vue
:::

---

---
url: 'https://flux-ui.dev/statistics/components/tracker.md'
---

# Tracker

The tracker shows how something progresses over time: a vertical rail with an [Entry](./entry) per milestone, an optional [Label](./label) to mark a phase, and a group of [Steps](./step) branching off the rail for the work inside a milestone.

::: render
render=../../../code/statistics/components/tracker/preview.vue
:::

::: tip
The tracker is display-only. It renders what you declare and nothing more, so ordering, states and content come from your data.
:::

::: info
Every line is drawn as a single SVG overlay, measured from the markers that are actually rendered. Nothing is masked against a background color, so the tracker keeps working on any surface.
:::

::: info
The tracker exposes the ARIA `list` role and its rows are `listitem`s.
:::

## Examples

::: example Live || Steps complete one by one, the entry flips to delivered and a closing row joins the rail. The lines follow along, since they are measured from what is rendered.
example=../../../code/statistics/components/tracker/live.vue
:::

::: example Order tracking || A [Tracker card](../tracker-card/) summarizing the progress, followed by a tracker detailing every shipment.
example=../../../code/statistics/components/tracker/order-tracking.vue
:::

## Used components

* [Entry](./entry)
* [Label](./label)
* [Step](./step)

---

---
url: 'https://flux-ui.dev/statistics/components/tracker/entry.md'
---

# Tracker entry

A milestone on the rail of a [Tracker](./index): a marker, a header carrying the title, a badge and the moment, and a body holding whatever the milestone needs.

::: render
render=../../../code/statistics/components/tracker/entry/preview.vue
:::

::: tip
The marker follows the color of the milestone; leave `icon` out and the entry falls back to a small dot, for a row that merely happened.
:::

::: info
The entry exposes the ARIA `listitem` role.
:::

## Examples

::: example Start and end || The header carries whatever you put in it; an avatar in front of the title, a badge behind it.
example=../../../code/statistics/components/tracker/entry/slots.vue
:::

::: example Colors || The marker and the badge follow the state of the milestone.
example=../../../code/statistics/components/tracker/entry/colors.vue
:::

## Used components

* [Icon](../../../components/icon)

---

---
url: 'https://flux-ui.dev/statistics/components/tracker/label.md'
---

# Tracker label

A phase marker on the rail of a [Tracker](./index). It groups the entries that follow it, without taking the visual weight of an [Entry](./entry).

::: render
render=../../../code/statistics/components/tracker/label/preview.vue
:::

::: tip
Keep labels short. They name a phase, such as `Completed` or `In-progress`, and are rendered in uppercase.
:::

::: info
The label exposes the ARIA `listitem` role.
:::

## Snippet

::: code-group

```vue \[FluxStatisticsTrackerLabel.vue]
<template>
    <Preview>
        <FluxStatisticsTracker style="width: 100%; max-width: 450px">
            <FluxStatisticsTrackerLabel label="Completed"/>

            <FluxStatisticsTrackerEntry
                color="success"
                icon="circle-check"
                title="Order placed"
                when="Mar 8, 2026 · 09:12 am"/>

            <FluxStatisticsTrackerLabel
                color="primary"
                label="In-progress"/>

            <FluxStatisticsTrackerEntry
                color="primary"
                icon="truck"
                title="Shipment 1">
                <template #end>
                    <FluxBadge
                        colored
                        color="primary"
                        label="In Progress"/>
                </template>
            </FluxStatisticsTrackerEntry>
        </FluxStatisticsTracker>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxBadge } from '@flux-ui/components';
    import { FluxStatisticsTracker, FluxStatisticsTrackerEntry, FluxStatisticsTrackerLabel } from '@flux-ui/statistics';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/statistics/components/tracker/step.md'
---

# Tracker step

The work inside an [Entry](./entry). Steps are wrapped in a `FluxStatisticsTrackerSteps` group; the tracker branches its rail into the group and rejoins it below the last step.

::: render
render=../../../code/statistics/components/tracker/step/preview.vue
:::

::: tip
Steps are the detail level of a tracker. Keep the milestone itself in the [Entry](./entry) and put everything that happens within it here.
:::

::: info
The group exposes the ARIA `list` role and its steps are `listitem`s.
:::

## Snippet

::: code-group

```vue \[FluxStatisticsTrackerStep.vue]
<template>
    <Preview>
        <FluxStatisticsTracker style="width: 100%; max-width: 450px">
            <FluxStatisticsTrackerEntry
                color="primary"
                icon="box"
                title="Fulfillment">
                <template #end>
                    <FluxBadge
                        colored
                        color="primary"
                        label="In Progress"/>
                </template>

                <FluxStatisticsTrackerSteps>
                    <FluxStatisticsTrackerStep
                        state="done"
                        label="Items picked"/>

                    <FluxStatisticsTrackerStep
                        state="active"
                        label="Packing in progress"/>

                    <FluxStatisticsTrackerStep label="Handed to carrier"/>
                </FluxStatisticsTrackerSteps>
            </FluxStatisticsTrackerEntry>
        </FluxStatisticsTracker>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxBadge } from '@flux-ui/components';
    import { FluxStatisticsTracker, FluxStatisticsTrackerEntry, FluxStatisticsTrackerStep, FluxStatisticsTrackerSteps } from '@flux-ui/statistics';
</script>

```

:::

## Used components

* [Icon](../../../components/icon)

---

---
url: 'https://flux-ui.dev/statistics/components/tracker-card.md'
---

# Tracker card

The tracker card summarizes a process in a single glance: what it is, where it stands, and how far along it is. The progress itself is declared as a row of [Segments](./segment), one per step.

::: render
render=../../../code/statistics/components/tracker-card/preview.vue
:::

::: tip
The card pairs well with a [Tracker](../tracker/) below it: the card gives the summary, the tracker gives the detail.
:::

## Examples

::: example Live || The running segment fills up before it hands over to the next one, so the card reads as a process instead of a score.
example=../../../code/statistics/components/tracker-card/live.vue
:::

::: example Labels || Segments can carry a label. Set `labels` to `top` to render them above the bar instead of below it.
example=../../../code/statistics/components/tracker-card/labels.vue
:::

::: example Colors || The header icon and the segments are tinted separately, so a card can follow the color of the process it tracks.
example=../../../code/statistics/components/tracker-card/colors.vue
:::

## Used components

* [Boxed icon](../../../components/boxed-icon)
* [Pane](../../../components/pane)
* [Segment](./segment)

---

---
url: 'https://flux-ui.dev/statistics/components/tracker-card/segment.md'
---

# Tracker card segment

A single step in the bar of a [Tracker card](./index). Every segment takes an equal share of the width, so the bar reads as a step count rather than as a percentage.

::: render
render=../../../code/statistics/components/tracker-card/segment/preview.vue
:::

::: tip
`min`, `max` and `value` only apply to an `active` segment; the other states are either full or empty. Leave them out and a running step is drawn halfway.
:::

::: info
The segment exposes the ARIA `listitem` role. An `active` segment is marked with `aria-current="step"`, and its `label` is used as the accessible name.
:::

## Snippet

::: code-group

```vue \[FluxStatisticsTrackerCardSegment.vue]
<template>
    <Preview>
        <FluxStatisticsTrackerCard
            style="width: 100%; max-width: 450px"
            title="Fulfillment"
            subtitle="Packed 3 of 8 items"
            icon="box">
            <FluxStatisticsTrackerCardSegment
                label="Picked"
                state="done"/>

            <FluxStatisticsTrackerCardSegment
                label="Packing"
                state="active"
                :min="0"
                :max="8"
                :value="3"/>

            <FluxStatisticsTrackerCardSegment label="Shipped"/>
        </FluxStatisticsTrackerCard>
    </Preview>
</template>

<script
    setup
    lang="ts">
    import { FluxStatisticsTrackerCard, FluxStatisticsTrackerCardSegment } from '@flux-ui/statistics';
</script>

```

:::

---

---
url: 'https://flux-ui.dev/visuals.md'
---
# Flux Visuals

Flux Visuals is a collection of decorative visual effect components. It provides shimmering borders, animated color fields, patterned backdrops and rolling text, helping you add subtle movement and focus to an interface without reaching for a separate animation library.

All effects are purely decorative and `aria-hidden`, and they respect `prefers-reduced-motion`. Because they build on the Flux design tokens, load them alongside `@flux-ui/components`.

---

---
url: 'https://flux-ui.dev/visuals/introduction/installation.md'
---
# Installation

To start using Flux Visuals in your Vue application, you'll need to add it to your project. This section provides step-by-step instructions on how to install Flux Visuals, ensuring you can quickly integrate its components into your development workflow.

::: tip
Flux Visuals relies on the Flux design tokens (`--gray-*`, `--radius`, …) for its colors and radii. Always install and load `@flux-ui/components` alongside it, otherwise the effects render without a theme.
:::

## Plain installation

::: tip
This is the most recommended way to use Flux Visuals. Use this form of installation if you don't need to customize the style of Flux Visuals or if you simply need to use the components without the source code.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [bun]
bun add @flux-ui/visuals @flux-ui/components
```

```shell [pnpm]
pnpm install @flux-ui/visuals @flux-ui/components
```

```shell [yarn]
yarn add @flux-ui/visuals @flux-ui/components
```

```shell [npm]
npm install @flux-ui/visuals @flux-ui/components
```

:::

### Step 2

Once the installation is complete, you need to add the following line to your `main.ts` file:

```ts [main.ts]
import '@flux-ui/visuals/style.css'
import '@flux-ui/components/style.css'
```

### Step 3

Import the components you want to use, like this:

```vue [Hero.vue]
<template>
    <FluxVisualBorderBeam variant="md"> <!-- [!code focus:3] -->
        <FluxPane>...</FluxPane>
    </FluxVisualBorderBeam>
</template>

<script
    setup
    lang="ts">
    import { FluxPane } from '@flux-ui/components'
    import { FluxVisualBorderBeam } from '@flux-ui/visuals' // [!code focus]
</script>
```

## Vite-preset installation

::: tip
Only use this form of installation if you need more control of Flux Visuals and need the Flux Visuals source code injected into your own project.
:::

### Step 1

Open your project's root directory in your terminal and run the following command:

::: code-group

```shell [bun]
bun add @flux-ui/visuals @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [pnpm]
pnpm install @flux-ui/visuals @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [yarn]
yarn add @flux-ui/visuals @flux-ui/components sass-embedded @basmilius/vite-preset
```

```shell [npm]
npm install @flux-ui/visuals @flux-ui/components sass-embedded @basmilius/vite-preset
```

:::

### Step 2

Once the installation is complete, you need to configure your `vite.config.ts` file to use Flux Visuals.

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { composeLibrary, flux, preset } from '@basmilius/vite-preset'

const fluxVisuals = composeLibrary({
    name: '@flux-ui/visuals',
    alias: '~flux/visuals'
});

export default defineConfig({
    plugins: [
        vue(),
        preset(),
        flux(),
        fluxVisuals()
    ]
});
```

### Step 3

Import the components you want to use as shown in step 3 of the plain installation.

---

---
url: 'https://flux-ui.dev/visuals/components/animated-colors.md'
---

# Animated colors

The animated colors component presents an array of colors with a blurred animation effect, often used in the [Pane Illustration](./pane-illustration) component.

::: render
render=../../code/visuals/animated-colors/preview.vue
:::

## Examples

::: example Free || When used freely, the animated colors fill the parent container.
example=../../code/visuals/animated-colors/free.vue
:::

::: example Pane || The animated colors visual can be used to make pane's more alive.
example=../../code/visuals/animated-colors/pane.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/attention.md'
---

# Attention

A subtle attention nudge that plays a one-shot animation on command. Reach for it to highlight a KPI that just changed or a badge that needs a glance. Four effects are available: `pulse`, `shake`, `bounce` and `tada`.

::: render
render=../../code/visuals/attention/preview.vue
:::

Bind the `trigger` prop to a reactive value to replay the effect whenever it changes, or call the exposed `play()` method through a template ref. The `finished` event fires on animation end. When `prefers-reduced-motion` is set no animation plays and `play()` simply emits `finished` right away.

## Examples

::: example Effects || Pick between the pulse, shake, bounce and tada effects.
example=../../code/visuals/attention/effects.vue
:::

::: example On change || Bind the trigger prop to a value so the effect replays each time it updates.
example=../../code/visuals/attention/trigger.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/border-beam.md'
---

# Border beam

This component adds a traveling or breathing glow animation around any element, such as cards, buttons, inputs or panes. The wrapped element is clipped to the beam's radius and three layers are rendered on top of it: the beam stroke, an inner glow and a soft bloom. Colors adapt to light and dark mode and slowly shift hue over time.

::: render
render=../../code/visuals/border-beam/preview.vue
:::

The beam pauses automatically when it is scrolled offscreen. The pulse variants are driven by a single shared animation loop that is capped at ~30fps and respect `prefers-reduced-motion`.

## Examples

::: example Button || Use the compact sm variant on buttons to guide the user to important actions.
example=../../code/visuals/border-beam/button.vue
:::

::: example Pane || Use the md variant on panes to highlight new or prominent features.
example=../../code/visuals/border-beam/pane.vue
:::

::: example Line || The line variant renders a traveling glow along the bottom edge, ideal for inputs and search bars.
example=../../code/visuals/border-beam/line.vue
:::

::: example Pulse || The pulse variants breathe instead of rotate. Pulse-inner stays contained within the element, while pulse-outside blooms outward and requires an opaque child.
example=../../code/visuals/border-beam/pulse.vue
:::

::: example Palettes || Four color palettes are available: colorful, mono, ocean and sunset.
example=../../code/visuals/border-beam/palettes.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/border-shine.md'
---

# Border shine

This component adds a shimmering border effect to any element. Customize the colors, duration, offset, radius, and width to create a unique glowing effect that enhances the visual appeal of your interface.

::: render
render=../../code/visuals/border-shine/preview.vue
:::

## Examples

::: example Button || Use it on buttons to guide the user to subscriptions.
example=../../code/visuals/border-shine/button.vue
:::

::: example Pane || Use it on panes to apply a shine that highlights prominent features.
example=../../code/visuals/border-shine/pane.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/dot-pattern.md'
---

# Dot pattern

A customizable SVG-based dot pattern component that can seamlessly fill any container. Adjust properties like dot size and positioning, ideal for backgrounds and overlays.

::: render
render=../../code/visuals/dot-pattern/preview.vue
:::

## Examples

::: example Free || When used freely, the dot pattern fills the parent container.
example=../../code/visuals/dot-pattern/free.vue
:::

::: example Glow || With `glow` enabled, the pattern lights up around the cursor as it moves across the container, while the rest stays dimmed.
example=../../code/visuals/dot-pattern/glow.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/flickering-grid.md'
---

# Flickering grid

Displays a dynamic grid of flickering squares, creating an eye-catching effect. Customize the grid's color, size, opacity, and spacing for added visual interest.

::: render
render=../../code/visuals/flickering-grid/preview.vue
:::

## Examples

::: example Free || When used freely, the flickering grid fills the parent container.
example=../../code/visuals/flickering-grid/free.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/grid-pattern.md'
---

# Grid pattern

A stylish SVG grid pattern component that fills any container and can be customized in terms of grid size, positioning, and stroke style. Supports highlighting specific squares.

::: render
render=../../code/visuals/grid-pattern/preview.vue
:::

## Examples

::: example Free || When used freely, the grid pattern fills its parent container.
example=../../code/visuals/grid-pattern/free.vue
:::

::: example Glow || With `glow` enabled, the grid lines light up around the cursor as it moves across the container, while the rest stays dimmed.
example=../../code/visuals/grid-pattern/glow.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/highlighter.md'
---

# Highlighter

This component draws a hand-drawn annotation, such as a highlight, underline, box or circle, around inline content. It builds on [rough-notation](https://roughnotation.com), so every stroke looks sketched rather than perfectly geometric, and the annotation animates itself into place.

::: render
render=../../code/visuals/highlighter/preview.vue
:::

The annotation is purely decorative and is drawn on top of the content, so it never affects layout or readability. The draw animation is skipped when `prefers-reduced-motion` is set, in which case the annotation appears instantly.

Inside a [Highlighter group](./highlighter-group) the group draws all annotations as one sequence and can supply defaults for the annotation props; a highlighter's own props always win. The component also exposes `show()`, `hide()` and `replay()` through a template ref for programmatic control.

## Examples

::: example Actions || Seven annotation styles are available: highlight, underline, box, circle, bracket, strike-through and crossed-off.
example=../../code/visuals/highlighter/actions.vue
:::

::: example Colors || Any CSS color works. Reach for the theme tokens to keep the annotation in sync with light and dark mode.
example=../../code/visuals/highlighter/colors.vue
:::

::: example When in view || Set `when-in-view` to defer the animation until the element scrolls into the viewport.
example=../../code/visuals/highlighter/in-view.vue
:::

::: example Replay || Call show(), hide() or replay() through a template ref to control the annotation programmatically.
example=../../code/visuals/highlighter/replay.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/highlighter-group.md'
---

# Highlighter group

This component wraps several [Highlighter](./highlighter) components and draws their annotations as one sequence, one after another in document order, instead of all at once. Internally the annotations are combined through rough-notation's `annotationGroup`, which staggers each draw by the previous one's duration.

Every highlighter inside a group hands its annotation to the group, so the individual `when-in-view` of each highlighter is ignored: the whole cascade is controlled here. The group can also supply defaults for the annotation props, such as `variant` and `color`, which the highlighters inherit unless they set their own.

::: render
render=../../code/visuals/highlighter-group/preview.vue
:::

When `prefers-reduced-motion` is set the cascade is skipped and every annotation appears instantly.

## Examples

::: example Defaults || Set the annotation props once on the group; each highlighter inherits them and can still override them individually.
example=../../code/visuals/highlighter-group/defaults.vue
:::

::: example When in view || Set `when-in-view` to defer the whole cascade until the group scrolls into the viewport.
example=../../code/visuals/highlighter-group/in-view.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/noise.md'
---

# Noise

A subtle film-grain overlay that adds texture to panes and hero areas. Use it as a fill element inside a relatively positioned container; it sits on top with pointer events disabled and blends into the surface below.

::: render
render=../../code/visuals/noise/preview.vue
:::

The grain is generated from an inline SVG turbulence filter, so there is nothing to download. The animated variant snaps between a handful of positions with a stepped animation instead of a per-frame script, and always falls back to a static grain when reduced motion is requested.

## Examples

::: example Animated || Add lively, cinematic movement with jittering grain.
example=../../code/visuals/noise/animated.vue
:::

::: example Paper || A multiply blend turns the grain into a faint printed texture.
example=../../code/visuals/noise/paper.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/number-flow.md'
---

# Number flow

Number flow renders a single `<span>` that tweens smoothly between numbers, ideal for KPI tiles, counters and live metrics. On mount it counts up from zero, and whenever `value` changes it rolls from the number currently on screen to the new one. Every frame is rendered through `Intl.NumberFormat`, so thousands separators, currency, percentages and decimals all animate cleanly, and tabular figures keep the value from shifting horizontally as digits change.

::: render
render=../../code/visuals/number-flow/preview.vue
:::

::: tip
The tween respects `prefers-reduced-motion`: when reduced motion is requested the value swaps straight to its target instead of tweening. The final, settled value is always exposed as the accessible label, so screen readers read the real number rather than the frames streaming past.
:::

## Examples

::: example Basic || Bind a reactive value and the display tweens every time it changes.
example=../../code/visuals/number-flow/basic.vue
:::

::: example Easing || Swap the easing curve through the easing prop: a named keyword, a cubic-bezier() string or your own function. Each row tweens to the same value so the curves are easy to compare.
example=../../code/visuals/number-flow/easing.vue
:::

::: example KPI tile || A live dashboard stat: the value counts up on mount and rolls each time the underlying data updates, formatted as currency.
example=../../code/visuals/number-flow/kpi-tile.vue
:::

::: example Formatting || Pass Intl.NumberFormat options through format to render currency, percentages and decimals, each tweening in its own format.
example=../../code/visuals/number-flow/formatting.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/pane-illustration.md'
---

# Pane illustration

The pane illustration places a visual illustration within a pane, often in feature or onboarding-style cards. Illustrations are created outside of Flux and brought into the pane to add personality.

::: render
render=../../code/visuals/pane-illustration/preview.vue
:::

## Examples

::: example Basic || A basic pane illustration.
example=../../code/visuals/pane-illustration/basic.vue
:::

## Used components

* [Visuals](../)
  * [Grid pattern](./grid-pattern)
  * [Animated colors](./animated-colors)

---

---
url: 'https://flux-ui.dev/visuals/components/ping.md'
---

# Ping

A radar-style status dot that emits expanding, fading rings behind a solid center. Ideal for live, online or realtime indicators on dashboards. The effect is purely decorative, so it is marked `aria-hidden` and pairs well with a text label.

::: render
render=../../code/visuals/ping/preview.vue
:::

The rings are driven entirely by CSS keyframes. When `prefers-reduced-motion` is set the rings are removed and only the solid dot remains.

## Examples

::: example Statuses || Combine differently colored pings with a label to build a compact service status list.
example=../../code/visuals/ping/statuses.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/slot-text.md'
---

# Slot text

Slot text renders a single `<span>` that animates with a tactile per-character "roll": each character sits in its own clipped cell, and whenever the `text` changes the old glyph slides out while the new one chases it in with a springy overshoot. It is ideal for short labels, statuses, numbers and commands, such as the classic `Copy → Copied → Copy` button, a live status word or a changing counter.

::: render
render=../../code/visuals/slot-text/preview.vue
:::

::: tip
The roll respects `prefers-reduced-motion`: when reduced motion is requested the text simply swaps instead of rolling. The current `text` is always exposed as the accessible label, so screen readers read the value rather than the individual glyph cells.
:::

The component also exposes two imperative methods through a template ref: `set(text, options?)` rolls to new text permanently, and `flash(text, options?)` rolls to temporary text and automatically rolls back, the spam-safe `Copy → Copied → Copy` pattern in one call.

## Examples

::: example Basic || Bind a reactive value to text and the label rolls every time it changes.
example=../../code/visuals/slot-text/basic.vue
:::

::: example Counter || Roll digits up or down to animate a counter, a quantity or a live metric. Tabular numbers keep the value from shifting horizontally.
example=../../code/visuals/slot-text/counter.vue
:::

::: example Metric || A live KPI tile: the value streams in and rolls every time the data updates, so a dashboard stat feels alive without redrawing the card.
example=../../code/visuals/slot-text/metric.vue
:::

::: example Trend || A delta indicator that rolls up and tints green when the reading rises, and rolls down and tints red when it falls.
example=../../code/visuals/slot-text/trend.vue
:::

::: example Status || Tint each new status as it rolls in with the color prop, fading back to the resting color, ideal for job, order or deployment states.
example=../../code/visuals/slot-text/status.vue
:::

::: example Clock || Frequent updates roll cleanly: only the digits that actually change re-roll, so a ticking clock animates just its seconds.
example=../../code/visuals/slot-text/clock.vue
:::

::: example Flash || Call flash() through a template ref to roll to temporary text that automatically rolls back, ideal for copy buttons.
example=../../code/visuals/slot-text/flash.vue
:::

::: example Direction || Roll glyphs upward or downward with the direction prop.
example=../../code/visuals/slot-text/direction.vue
:::

::: example Chromatic || Enable chromatic for a rainbow hue sweep that fades back to the resting color as the glyphs land.
example=../../code/visuals/slot-text/chromatic.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/text-scramble.md'
---

# Text scramble

Text scramble renders a single `<span>` that "decodes" its text: whenever `text` changes each character cycles through random glyphs before settling on its final one, rippling across the string from left to right. It is ideal for dashboard widgets that refresh, status reveals and headline transitions.

::: render
render=../../code/visuals/text-scramble/preview.vue
:::

::: tip
The decode respects `prefers-reduced-motion`: when reduced motion is requested the text swaps straight to its target instead of scrambling. The current `text` is always exposed as the accessible label, so screen readers read the real value rather than the random glyphs.
:::

The component also exposes two imperative methods through a template ref: `set(text)` decodes to new text, and `replay()` re-runs the decode on the current text. A `finished` event fires once the animation settles.

## Examples

::: example Widget refresh || Decode a value every time a dashboard tile refreshes, so the update reads as a live recompute rather than a silent swap.
example=../../code/visuals/text-scramble/widget.vue
:::

::: example Replay || Call replay() through a template ref to re-run the decode on demand, without changing the text.
example=../../code/visuals/text-scramble/replay.vue
:::

::: example Characters || Narrow the scramble pool with characters, for example to digits only so a counter decodes through numbers.
example=../../code/visuals/text-scramble/characters.vue
:::

---

---
url: 'https://flux-ui.dev/visuals/components/text-shimmer.md'
---

# Text shimmer

Text shimmer sweeps a soft highlight across its text, a CSS-only loading shimmer for pending, streaming or "AI is thinking" states. The effect clips an animated gradient to the text itself, so it works on any font size or weight without extra markup.

::: render
render=../../code/visuals/text-shimmer/preview.vue
:::

::: tip
The sweep respects `prefers-reduced-motion`: when reduced motion is requested the text falls back to a plain, solid color with no animation. The text lives in the default slot, so it stays fully readable to screen readers.
:::

## Examples

::: example Thinking || Show the shimmer while a task is running, then swap it for a solid result once it settles.
example=../../code/visuals/text-shimmer/thinking.vue
:::

::: example Colors || Tint the resting text and the highlight with color and shimmer-color, and widen the band with spread.
example=../../code/visuals/text-shimmer/colors.vue
:::

---

---
url: 'https://flux-ui.dev/internals.md'
---
# Flux Internals

This package contains internal composables, directives and utilities that are used by Flux. You should probably not directly use it in your own project. To install the component library, please visit [Manual installation](../guide/introduction/installation/manual).

::: code-group

```shell [Bun]
bun add @flux-ui/internals
```

```shell [PNPM]
pnpm install @flux-ui/internals
```

```shell [Yarn]
yarn add @flux-ui/internals
```

```shell [NPM]
npm install @flux-ui/internals
```

:::

---

---
url: 'https://flux-ui.dev/internals/composables/useCalendar.md'
---
# useCalendar

This composable function is used to create month calendars in Flux. It contains the internal workings for determining which dates are visible and how to navigate between them.

## Usage

```ts
import { useCalendar } from '@flux-ui/internals';
import { DateTime } from 'luxon';

const {
    isTransitioningToPast,
    viewDate,
    viewDateNext,
    viewDatePrevious,
    viewMonth,
    viewYear,
    dates,
    days,
    setViewDate,
    nextMonth,
    previousMonth
} = useCalendar(DateTime.now(), {
    monthLength: 'long',
    weekDayLength: 'long'
});
```

## Type declarations

```ts
import type { DateTime } from 'luxon';
import type { ComputedRef, Ref } from 'vue';

export declare function useCalendar(
    initialDate: DateTime,
    options?: Options
): UseCalendarReturn;

export declare type Options = {
    readonly monthLength?: 'short' | 'long';
    readonly weekDayLength?: 'short' | 'long';
};

export declare type UseCalendarReturn = {
    readonly isTransitioningToPast: Ref<boolean>;
    readonly viewDate: Ref<DateTime>;
    readonly viewDateNext: ComputedRef<DateTime>;
    readonly viewDatePrevious: ComputedRef<DateTime>;
    readonly viewMonth: ComputedRef<string>;
    readonly viewYear: ComputedRef<string>;
    readonly dates: ComputedRef<DateTime[]>;
    readonly days: ComputedRef<string[]>;
    
    setViewDate(date: DateTime): void;
    nextMonth(): void;
    previousMonth(): void;
};
```

## Used by

* [Calendar](../../components/calendar)
* [Date picker](../../components/date-picker)

---

---
url: 'https://flux-ui.dev/internals/composables/useCalendarMonthSwitcher.md'
---
# useCalendarMonthSwitcher

This composable function is used to create month switchers in Flux. It returns the months in the locale of the user.

## Usage

```ts
import { useCalendarMonthSwitcher } from '@flux-ui/internals';
import { DateTime } from 'luxon';

const {
    months
} = useCalendarMonthSwitcher(DateTime.now(), 'short');
```

## Type declarations

```ts
import type { DateTime } from 'luxon';
import type { Ref } from 'vue';

export declare function useCalendarMonthSwitcher(
    currentDate: Ref<DateTime>,
    displayLength: 'short' | 'long'
): UseCalendarMonthSwitcherReturn;

type MonthEntry = {
    readonly date: DateTime;
    readonly label: string;
};

type UseCalendarMonthSwitcherReturn = {
    readonly months: Ref<MonthEntry[]>;
};
```

## Used by

* [Calendar](../../components/calendar)
* [Date picker](../../components/date-picker)

---

---
url: 'https://flux-ui.dev/internals/composables/useCalendarYearSwitcher.md'
---
# useCalendarYearSwitcher

This composable function is used to create years switchers in Flux. It contains the internal workings for determining which years are visible and how to navigate between them.

## Usage

```ts
import { useCalendarYearSwitcher } from '@flux-ui/internals';
import { DateTime } from 'luxon';

const {
    years,
    next,
    previous
} = useCalendarYearSwitcher(DateTime.now(), 10);
```

## Type declarations

```ts
import type { DateTime } from 'luxon';
import type { Ref } from 'vue';

export declare function useCalendarYearSwitcher(
    currentDate: Ref<DateTime>,
    limit: number = 10
): UseCalendarYearSwitcherReturn;

type UseCalendarYearSwitcherReturn = {
    readonly years: Ref<number[]>;

    next(): void;
    previous(): void;
};
```

## Used by

* [Calendar](../../components/calendar)
* [Date picker](../../components/date-picker)

---

---
url: 'https://flux-ui.dev/internals/composables/useEventListener.md'
---
# useEventListener

This composable function is used to attach events to an element, with automatic disposal.

## Usage

```ts
import { useEventListener } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

const element = useTemplateRef('element');

useEventListener(element, 'click', () => {
    console.log('Element clicked!');
});
```

## Type declarations

```ts
import type { TemplateRef } from '@flux-ui/internals';
import type { Ref } from 'vue';

export declare function useEventListener<K extends keyof HTMLElementEventMap>(
    elementRef: TemplateRef<HTMLElement>,
    eventName: K,
    listener: (evt: HTMLElementEventMap[K]) => any,
    options: AddEventListenerOptions = {passive: true}
): void;
```

## Used by

* [Tab bar](../../components/tab-bar)

---

---
url: 'https://flux-ui.dev/internals/composables/useFocusTrap.md'
---
# useFocusTrap

This composable function is used to trap focus within a container.

## Usage

```ts
import { useFocusTrap } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

const element = useTemplateRef('element');

useFocusTrap(element);
```

## Type declarations

```ts
import type { TemplateRef } from '@flux-ui/internals';
import type { Ref } from 'vue';

export declare function useFocusTrap(
    containerRef: TemplateRef<HTMLElement>,
    options: UseFocusTrapOptions = {}
): void;

type UseFocusTrapOptions = {
    attachTo?: HTMLElement | Document;
    disable?: Ref<boolean>;
    disableReturn?: Ref<boolean>;
};
```

## Used by

* [Flyout](../../components/flyout)

---

---
url: 'https://flux-ui.dev/internals/composables/useFocusTrapLock.md'
---
# useFocusTrapLock

This composable function is used to manage focus locking for a component instance.

## Usage

```ts
import { useFocusTrapLock } from '@flux-ui/internals';

useFocusTrapLock(true);
```

## Type declarations

```ts
import type { Ref } from 'vue';

export declare function useFocusTrapLock(
    autoFocus: boolean = false
): Ref<boolean>;
```

---

---
url: 'https://flux-ui.dev/internals/composables/useFocusTrapReturn.md'
---
# useFocusTrapReturn

This composable function is used to manage focus returning for a component instance.

## Usage

```ts
import { useFocusTrapReturn } from '@flux-ui/internals';

useFocusTrapReturn(false);
```

## Type declarations

```ts
import type { Ref } from 'vue';

export declare function useFocusTrapReturn(
    disable: Ref<boolean> = false
): void;
```

---

---
url: 'https://flux-ui.dev/internals/composables/useFocusTrapSubscription.md'
---
# useFocusTrapSubscription

This composable function is used to subscribe to focus locking of a component instance.

## Usage

```ts
import { useFocusTrapSubscription } from '@flux-ui/internals';

useFocusTrapSubscription(() => {
    console.log('Focus trap changed!');
});
```

## Type declarations

```ts
import type { Ref } from 'vue';

export declare function useFocusTrapSubscription(
    listener: FocusTrapListener
): void;

export type FocusTrapListener = (isEnabled: boolean, focusTraps: object[]) => void;
```

---

---
url: 'https://flux-ui.dev/internals/composables/useFocusZone.md'
---
# useFocusZone

This composable function is used to create a focus zone within an element.

## Usage

```ts
import { useFocusZone } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

const element = useTemplateRef('element');

useFocusZone(element, {
    cycle: true,
    direction: 'vertical'
});
```

## Type declarations

```ts
import type { TemplateRef } from '@flux-ui/internals';

export declare function useFocusZone<TElement extends HTMLElement>(
    containerRef: TemplateRef<TElement>,
    options: UseFocusZoneOptions = {}
): void;

type UseFocusZoneOptions = {
    readonly cycle?: boolean;
    readonly direction?: 'bidirectional' | 'horizontal' | 'vertical';
};
```

## Used by

* [Menu](../../components/menu)

---

---
url: 'https://flux-ui.dev/internals/composables/useInView.md'
---
# useInView

This composable function is used to check if an element is currently visible in the viewport.

## Usage

```ts
import { useInView } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

const element = useTemplateRef('element');

useInView(element, {
    threshold: 1
});
```

## Type declarations

```ts
import type { TemplateRef } from '@flux-ui/internals';
import type { Ref } from 'vue';

export declare function useInView<TElement extends HTMLElement>(
    containerRef: TemplateRef<TElement>,
    options: UseInViewOptions = {}
): Ref<boolean>;

type UseInViewOptions = IntersectionObserverInit & {
    readonly initial?: boolean;
};
```

## Used by

* [Visuals](../../visuals/)
  * [Flickering grid](../../visuals/components/flickering-grid)

---

---
url: 'https://flux-ui.dev/internals/composables/useRemembered.md'
---
# useRemembered

This composable function is used remember a simple value in the browser.

## Usage

```ts
import { useRemembered } from '@flux-ui/internals';

const darkMode = useRemembered('dark-mode', false);
```

## Type declarations

```ts
import type { Ref } from 'vue';

export declare function useRemembered<T>(
    key: string,
    initialValue: T
): Ref<T>;
```

---

---
url: 'https://flux-ui.dev/internals/composables/useScrollPosition.md'
---
# useScrollPosition

This composable tracks the scroll position of a given element or the document. It provides reactive `x` and `y` refs that update on scroll events.

## Usage

```ts
import { useScrollPosition } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

// Track document scroll
const { x, y } = useScrollPosition();

// Track element scroll
const element = useTemplateRef('scrollContainer');
const { x: elX, y: elY } = useScrollPosition(element);
```

## Type declarations

```ts
import type { TemplateRef } from '@flux-ui/internals';
import type { Ref } from 'vue';

export declare function useScrollPosition<TElement extends HTMLElement>(
    elementRef?: TemplateRef<TElement>
): UseScrollPositionReturn;

type UseScrollPositionReturn = {
    readonly x: Ref<number>;
    readonly y: Ref<number>;
};
```

---

---
url: 'https://flux-ui.dev/internals/directives/focusTrap.md'
---
# `v-focus-trap`

This directive is used to trap focus within the element the directive is bound to.

---

---
url: 'https://flux-ui.dev/internals/directives/heightTransition.md'
---
# `v-height-transition`

This directive is used to add height transitions to an element.

---

---
url: 'https://flux-ui.dev/internals/utils/animationFrameDebounce.md'
---
# animationFrameDebounce

Debounce a function to be called only once per animation frame.

## Usage

```ts
import { animationFrameDebounce } from '@flux-ui/internals';

function reposition(): void {
    // reposition logic.
}

const debounced = animationFrameDebounce(reposition);
```

## Type declarations

```ts
export declare function animationFrameDebounce<T extends Function>(fn: T): T;
```

---

---
url: 'https://flux-ui.dev/internals/utils/flattenVNodeTree.md'
---
# flattenVNodeTree

Flattens a VNode tree to remove non-dom elements.

## Usage

```ts
import { flattenVNodeTree } from '@flux-ui/internals';
import { useSlots } from 'vue';

const slots = useSlots();
const flattened = flattenVNodeTree(slots.default?.() ?? []);
```

## Type declarations

```ts
import type { VNode } from 'vue';

export declare function flattenVNodeTree(
    vnodes: VNode[]
): VNode[];
```

---

---
url: 'https://flux-ui.dev/internals/utils/getBidirectionalFocusElement.md'
---
# getBidirectionalFocusElement

Navigates bidirectionally within a container.

## Usage

```ts
import { getBidirectionalFocusElement } from '@flux-ui/internals';

const container = document.querySelector('#container');
const newFocusElement = getBidirectionalFocusElement(container.document.activeElement, 'down');
```

## Type declarations

```ts
export declare function getBidirectionalFocusElement(
    container: HTMLElement,
    currentElement: HTMLElement,
    direction: 'up' | 'down' | 'left' | 'right'
): HTMLElement | null;
```

---

---
url: 'https://flux-ui.dev/internals/utils/getComponentName.md'
---
# getComponentName

Returns the name of the component, based on its `VNode`.

## Usage

```ts
import { getComponentName } from '@flux-ui/internals';

const name = getComponentName(vnode);
```

## Type declarations

```ts
export declare function getComponentName(
    component: VNode
): string;
```

---

---
url: 'https://flux-ui.dev/internals/utils/getComponentProps.md'
---
# getComponentProps

Returns the props of the component, based on its `VNode`.

## Usage

```ts
import { getComponentProps } from '@flux-ui/internals';

const props = getComponentProps(vnode);
```

## Type declarations

```ts
export declare function getComponentProps<T extends object>(
    component: VNode
): T;
```

---

---
url: 'https://flux-ui.dev/internals/utils/getExposedRef.md'
---
# getExposedRef

Returns the name of the component, based on its `VNode`.

## Usage

```ts
import { getExposedRef } from '@flux-ui/internals';

const isOpen = getExposedRef(instance, 'isOpen');
```

## Type declarations

```ts
import type { ComponentInternalInstance } from 'vue';

export declare function getExposedRef<T>(
    instance: ComponentInternalInstance
): Ref<T>;
```

---

---
url: 'https://flux-ui.dev/internals/utils/getFocusableElement.md'
---
# getFocusableElement

Navigates to a next or previous focusable element within the container.

## Usage

```ts
import { getFocusableElement } from '@flux-ui/internals';

const container = document.querySelector('#container');
const focusableElements = getFocusableElement(container, 1);
```

## Type declarations

```ts
export declare function getFocusableElement(
    container: HTMLElement,
    direction: number,
    activeElement: HTMLElement | undefined = undefined
): HTMLElement | undefined;
```

---

---
url: 'https://flux-ui.dev/internals/utils/getFocusableElements.md'
---
# getFocusableElements

Returns all the focusable elements within a container.

## Usage

```ts
import { getFocusableElements } from '@flux-ui/internals';

const container = document.querySelector('#container');
const focusableElements = getFocusableElements(container);
```

## Type declarations

```ts
export declare function getFocusableElements(
    container: HTMLElement
): HTMLElement[];
```

---

---
url: 'https://flux-ui.dev/internals/utils/getKeyboardFocusableElements.md'
---
# getKeyboardFocusableElements

Returns all the focusable elements within a container that are focusable with the keyboard.

## Usage

```ts
import { getKeyboardFocusableElements } from '@flux-ui/internals';

const container = document.querySelector('#container');
const focusableElements = getKeyboardFocusableElements(container);
```

## Type declarations

```ts
export declare function getKeyboardFocusableElements(
    container: HTMLElement
): HTMLElement[];
```

---

---
url: 'https://flux-ui.dev/internals/utils/unrefTemplateElement.md'
---
# unrefTemplateElement

Returns the HTML element of a template ref.

## Usage

```ts
import { unrefTemplateElement } from '@flux-ui/internals';
import { useTemplateRef } from 'vue';

const element = useTemplateRef('element');
const htmlElement = unrefTemplateElement(element);
```

## Type declarations

```ts
import { TemplateRef } from '@flux-ui/internals';

export declare function unrefTemplateElement<T extends HTMLElement>(
    ref: TemplateRef<T> | T
): T | null;
```

---

---
url: 'https://flux-ui.dev/internals/utils/warn.md'
---
# warn

Logs a console warning prefixed with `[Flux]`. Used internally to notify developers of potential issues or misuse of components.

## Usage

```ts
import { warn } from '@flux-ui/internals';

warn('Component requires a parent FluxRoot.');
```

## Type declarations

```ts
declare function warn(...data: any[]): void;
```

---

---
url: 'https://flux-ui.dev/internals/utils/wrapFocus.md'
---
# wrapFocus

Wraps focus within a container element, enabling circular focus navigation. When focus leaves the container, it wraps to the first or last focusable child based on the direction of navigation.

## Usage

```ts
import { wrapFocus } from '@flux-ui/internals';

// Wrap focus within a container
wrapFocus(containerElement, targetElement);

// Force focus to the first focusable element
wrapFocus(containerElement, targetElement, true);
```

## Type declarations

```ts
declare function wrapFocus(
    elm: HTMLElement,
    targetElm: Element,
    forceFirst?: boolean
): void;
```

## Used by

* [useFocusTrap](../composables/useFocusTrap)

---

---
url: 'https://flux-ui.dev/internals/utils/focusTrap.md'
---
# FOCUS\_TRAP\_LOCKS

A stack-based focus trap manager. Maintains a LIFO (Last In, First Out) stack of focus traps. When a new trap is pushed, the previous one is disabled. When a trap is removed, the previous one is re-enabled.

## Usage

```ts
import { FOCUS_TRAP_LOCKS } from '@flux-ui/internals';

// Add a focus trap
FOCUS_TRAP_LOCKS.add('my-trap', (isEnabled) => {
    console.log('Trap enabled:', isEnabled);
});

// Check if a trap is currently active
if (FOCUS_TRAP_LOCKS.active) {
    console.log('Current trap:', FOCUS_TRAP_LOCKS.current);
}

// Subscribe to changes
const unsubscribe = FOCUS_TRAP_LOCKS.subscribe((isEnabled, focusTraps) => {
    console.log('Focus traps changed:', focusTraps);
});

// Remove the trap
FOCUS_TRAP_LOCKS.remove('my-trap');

// Cleanup subscription
unsubscribe();
```

## Type declarations

```ts
declare const FOCUS_TRAP_LOCKS: FocusTrapLockStack;

interface FocusTrap {
    id: string;
    isEnabled: boolean;
    setEnabled(isEnabled: boolean): void;
}

type FocusTrapListener = (isEnabled: boolean, focusTraps: FocusTrap[]) => void;

declare class FocusTrapLockStack {
    get active(): boolean;
    get current(): FocusTrap | null;
    add(id: string, setEnabled: Function, autoFocus?: boolean): void;
    remove(id: string): void;
    emit(): void;
    subscribe(listener: FocusTrapListener): () => void;
}
```

## Used by

* [useFocusTrap](../composables/useFocusTrap)
* [useFocusTrapLock](../composables/useFocusTrapLock)
* [useFocusTrapSubscription](../composables/useFocusTrapSubscription)

---

---
url: 'https://flux-ui.dev/internals/data/color.md'
---
# Color palette

The `@flux-ui/internals` package exports a comprehensive color palette based on the Tailwind CSS color system. Each color is available in 12 shades, from `50` (lightest) to `950` (darkest).

## Usage

```ts
import { blue500, red500, green500 } from '@flux-ui/internals';

console.log(blue500); // '#3b82f6'
```

## Available colors

Each of the following colors exports shades `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, and `950`:

## Type declarations

```ts
// Each color exports shades as string constants, e.g.:
export declare const blue50: string;
export declare const blue100: string;
// ... through blue950
```

---

---
url: 'https://flux-ui.dev/showcase.md'
---
# Showcase

::: warning
Not available yet.
:::

---

---
url: 'https://flux-ui.dev/playground.md'
---


---

---
url: 'https://flux-ui.dev/flow/playground.md'
---