# Adaptive interfaces

The `adaptive` prop enables mobile presentation below the configured breakpoint. Supported controls open a modal suited to their content. It is opt-in; its default is `false`.

## Try it

Use the device buttons to switch between desktop, tablet, and mobile viewports. Open a control to compare its popup and modal presentations. The preview uses a real embedded viewport, so you can try mobile behavior without resizing your browser.


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'

const date = shallowRef<DateValue>()
const color = ref('#7c3aed')
const selected = ref<'Design' | 'Engineering' | 'Support'>()
const search = ref<string>()
const message = ref('Choose an action')
const actions = [[
  { label: 'Save draft', onSelect: () => { message.value = 'Draft saved' } },
  { label: 'Duplicate', onSelect: () => { message.value = 'Item duplicated' } },
]]
</script>

<template>
  <div class="flex w-full flex-wrap items-center gap-3">
    <SSelect v-model="selected" :items="['Design', 'Engineering', 'Support']" adaptive placeholder="Choose a team" class="w-56" />
    <SAutocomplete v-model="search" :items="['Jakarta', 'Bandung', 'Surabaya']" adaptive placeholder="Search cities" class="w-56" />
    <SDatePicker v-model="date" adaptive class="w-56" />
    <SColorPicker v-model="color" adaptive />
    <SDropdown :items="actions" adaptive>
      <SButton variant="outline">
        Actions
      </SButton>
    </SDropdown>
    <p class="w-full text-sm text-[var(--selaras-resolved-text-muted)]" aria-live="polite">
      {{ message }}
    </p>
  </div>
</template>
```


## Supported controls

| Component                                                             | Adaptive behavior                                             |
| --------------------------------------------------------------------- | ------------------------------------------------------------- |
| [Select](https://selarasui.my.id/components/forms/select)             | Selection popup becomes a modal.                              |
| [Autocomplete](https://selarasui.my.id/components/forms/autocomplete) | A modal contains the input, suggestions, and selected values. |
| [Dropdown](https://selarasui.my.id/components/overlays/dropdown)      | Menu actions appear in a modal.                               |
| [DatePicker](https://selarasui.my.id/components/forms/date-picker)    | Date and time picker content appears in a modal.              |
| [ColorPicker](https://selarasui.my.id/components/forms/color-picker)  | Color controls appear in a modal.                             |

Models and item actions use the same API in either presentation. Other overlay components do not automatically acquire an `adaptive` prop.

## Breakpoint

The default is Tailwind's `md` breakpoint. Set `selaras.adaptive.breakpoint` in Nuxt configuration to choose another Tailwind breakpoint token. Define its length in CSS; see [Nuxt configuration](https://selarasui.my.id/overview/getting-started/nuxt-configuration#adaptive-breakpoint).

Server rendering starts with desktop presentation. The viewport is measured after mount, and an open adaptive control retains its chosen presentation until it closes. Test both viewport sizes and keyboard interaction in your application.


# Component usage

Selaras components are auto-imported with the `S` prefix. Start with an existing component, then customize its props and slots before building a replacement.

## State and events

```vue
<script setup lang="ts">
const selected = ref<'Small' | 'Medium' | 'Large'>()
</script>

<template>
  <SSelect v-model="selected" :items="['Small', 'Medium', 'Large']" placeholder="Choose a size" />
</template>
```

Component reference pages document models, events, item shapes, and slots. Item labels are your content; internal labels are controlled through [messages](https://selarasui.my.id/overview/getting-started/messages).

## Customization

Use props for supported behavior and appearance. Use slots for custom content, `class` for the root, and `:ui` for specific styled parts. See [Component styling](https://selarasui.my.id/overview/theming/component-styling) for merging and precedence.

Wrap your app in [SApp](https://selarasui.my.id/components/layout/app) for providers. Add [Toast](https://selarasui.my.id/components/overlays/toast) and [CommandPalette](https://selarasui.my.id/components/overlays/command-palette) where their references describe; providers alone do not render these controls.

## Responsive interfaces

Use [adaptive controls](https://selarasui.my.id/overview/getting-started/adaptive-interfaces) to opt into modal presentation on small screens. Responsive layout utilities and adaptive presentation solve different needs.


# Icons

Selaras uses [Nuxt Icon](https://nuxt.com/modules/icon){rel="&#x22;nofollow&#x22;"} under the hood and installs its module automatically. `SIcon` wraps its `Icon` component, so Nuxt Icon configuration, providers, aliases, and custom collections also apply to Selaras icons. Icon names use `collection:name`; internal component icons default to Hugeicons.

## Local icons

```vue-html
<SButton icon="hugeicons:search-01">Search</SButton>
<SButton icon="hugeicons:cancel-01" square aria-label="Close" />
<SIcon name="hugeicons:calendar-01" class="size-6" aria-hidden="true" />
```

Components expose their supported `icon`, `trailingIcon`, or icon slots in their reference pages. Explicit icon names do not change when you override the internal registry. Give icon-only actions an accessible label; decorative icons can be hidden from assistive technology.

## Global internal icons

```ts [app.config.ts]
export default defineAppConfig({
  selaras: {
    icons: {
      close: 'hugeicons:cancel-01',
      loading: 'hugeicons:loading-02',
    },
  },
})
```

Each key describes a purpose rather than a component. Overriding `close` changes components that read that registry key. Unspecified keys retain their defaults. See [useIcons](https://selarasui.my.id/utilities/composables/use-icons) for the complete registry and how custom components can reuse it.

## Configuration and loading

Configure Nuxt Icon through the top-level `icon` key in `nuxt.config.ts`, alongside `selaras`. You do not need to register `@nuxt/icon` again.

Nuxt Icon can fetch icons from the [Iconify](https://iconify.design/){rel="&#x22;nofollow&#x22;"} API when they are unavailable locally. This is convenient for trying collections, but runtime requests can delay an icon's appearance. Install the collections you use locally:

```bash
bun add -d @iconify-json/hugeicons @iconify-json/lucide
```

`devDependencies` is appropriate for the normal bundled build: icon data is consumed during building. Build environments must install dev dependencies. If you explicitly externalize icon JSON for runtime resolution, keep the packages available as production dependencies instead.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  icon: {
    serverBundle: {
      collections: ['hugeicons', 'lucide'],
    },
    clientBundle: {
      scan: true,
      icons: ['lucide:search', 'lucide:x'],
    },
  },
})
```

Installing a collection avoids relying on the public API; it does not alone guarantee immediate rendering. The client bundle makes known icons available without an icon request. Scanning finds literal names; add dynamically selected names explicitly to `clientBundle.icons`. This is especially useful for static sites without a Nuxt server endpoint.

## Runtime customization

Nuxt Icon's runtime settings belong under `icon` in `app.config.ts`. Selaras's internal-purpose registry remains under `selaras.icons`:

```ts [app.config.ts]
export default defineAppConfig({
  icon: {
    mode: 'svg',
    aliases: {
      'app-search': 'lucide:search',
    },
  },
  selaras: {
    icons: {
      search: 'app-search',
    },
  },
})
```

Nuxt Icon also supports global SVG customization through `icon.customize`. Selaras components set their own icon sizing classes, so prefer their `ui` slots for sizing individual component parts. See the [Nuxt Icon configuration reference](https://github.com/nuxt/icon#icon-customization){rel="&#x22;nofollow&#x22;"} for the full upstream API.

## Custom SVG collections

Place SVG files in `app/assets/icons`, then register a collection:

```ts [nuxt.config.ts]
import { createResolver } from 'nuxt/kit'

const { resolve } = createResolver(import.meta.url)

export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  icon: {
    customCollections: [
      { prefix: 'app', dir: resolve('./app/assets/icons') },
    ],
    clientBundle: {
      includeCustomCollections: true,
    },
  },
})
```

A file named `brand.svg` becomes `app:brand`. Including custom collections in the client bundle also makes them available on static hosting.

```vue-html
<SIcon name="app:brand" class="size-6" />
<SButton icon="app:brand">Workspace</SButton>
```

## Vue components as icons

Nuxt Icon can resolve a globally registered Vue component by name. For example, create `app/components/global/BrandIcon.vue`:

```vue
<template>
  <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M4 12L12 4L20 12L12 20Z" fill="currentColor" />
  </svg>
</template>
```

Then use that component name through Selaras:

```vue-html
<SIcon name="BrandIcon" class="size-6" />
<SButton icon="BrandIcon">Workspace</SButton>
```

The component must be globally registered; an ordinary local import is insufficient for name-based resolution. Nuxt Icon renders the component directly and ignores its CSS/SVG mode setting for that icon. See [Nuxt Icon's component support](https://github.com/nuxt/icon#vue-component){rel="&#x22;nofollow&#x22;"}.


# Installation

## Requirements

Selaras supports Nuxt `^4.5.2`, Tailwind CSS `^4.3.0`, and Node.js
`^22.19.0 || ^24.11.0 || >=26.0.0`. Nuxt provides the Vue runtime and SFC
compiler, so they are not installed or versioned separately. Type checking is
verified with TypeScript `>=5.9.3`; TypeScript is a build-time tool, not a
Selaras runtime dependency.

## Install the package

Nuxt and Tailwind CSS are peer dependencies - install Selaras in an existing
Nuxt project and keep Tailwind under your project's direct control:

::code-group
```bash [bun]
bun add @sewadah/selaras tailwindcss
```

```bash [npm]
npm install @sewadah/selaras tailwindcss
```

```bash [pnpm]
pnpm add @sewadah/selaras tailwindcss
```
::

## Register the module

Add `@sewadah/selaras` to `modules` in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
})
```

Components are now auto-imported, and the module pulls in its own
dependencies (`@nuxt/icon`, `@nuxtjs/color-mode`) automatically.

## Wrap your app in `SApp`

Wrap your root `app.vue` in `<SApp>`, once:

```vue-html
<!-- app.vue -->
<template>
  <SApp>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </SApp>
</template>
```

This isn't optional - without it, Tooltip loses its shared hover-delay
behavior, and `useModal()`/`useDrawer()`/`useSlideover()`/`useConfirm()` (the "open from
anywhere" APIs) have nothing to render into. See [App](https://selarasui.my.id/components/layout/app)
for the full picture, including the two components (`SToast`,
`SCommandPalette`) that still need to be placed yourself even with `SApp`
already wrapping everything.

## Import the CSS

Selaras doesn't inject its own CSS for you - import it explicitly in your
own stylesheet, after Tailwind itself:

```css [assets/css/main.css]
@import "tailwindcss";
@import "@sewadah/selaras";
@import "#selaras/tailwind.css";
```

Then point Nuxt at that file:

```ts
export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  css: ['~/assets/css/main.css'],
})
```

`@import "@sewadah/selaras";` brings in the default theme and component base
styles - see [Theming](https://selarasui.my.id/overview/theming/overview). `#selaras/tailwind.css` is generated
by the Nuxt module. Import it in this same entry so library class candidates
and adaptive presentation use your app's final Tailwind theme.

### Complete explicit theme

Applications with a complete existing semantic theme can import Selaras's
structural entry instead of its owned default foundations:

```css [assets/css/main.css]
@import "tailwindcss";
@import "@sewadah/selaras/structural.css";
@import "#selaras/tailwind.css";
```

This entry retains source discovery, variants, motion and semantic bindings.
Provide a light and dark recipe for every role your components can render,
including any built-in role you keep and each custom role you register. Provide
the functional `--selaras-*` inputs required by your design system as well.
It is not an unthemed zero-configuration mode: incomplete structural themes
have no Selaras fallback palette or runtime completeness diagnostic. Use the
aggregate import unless you provide that complete contract.
If your project also renders long-form markdown/CMS content, add
[prose.css](https://selarasui.my.id/components/typography/prose) the same way:

```css [assets/css/main.css]
@import "tailwindcss";
@import "@sewadah/selaras";
@import "#selaras/tailwind.css";
@import "@sewadah/selaras/prose.css";
```

Continue with [Component usage](https://selarasui.my.id/overview/getting-started/component-usage) and [Nuxt configuration](https://selarasui.my.id/overview/getting-started/nuxt-configuration).


# Introduction

Selaras is a UI component library for Nuxt.

It uses [Reka UI](https://reka-ui.com){rel="&#x22;nofollow&#x22;"} for accessible UI primitives. It uses Tailwind CSS v4 for styling and [tailwind-variants](https://www.tailwind-variants.org){rel="&#x22;nofollow&#x22;"} for component variants.

Selaras provides ready-to-use components for forms, navigation, data display, overlays, content, and application layouts.

## Design goals

### CSS-first theming

Selaras uses CSS custom properties for design values.

You can change colors, surfaces, text, borders, radius, shadows, and other theme values with CSS.

For example:

```css
:root {
  --selaras-color-primary-fill: #6d4aff;
  --selaras-surface-canvas: #f9f9f9;
  --selaras-surface-default: #ffffff;
  --selaras-radius-base: 0.5rem;
}
```

You do not need JavaScript or Nuxt configuration for normal theme changes.

Use Nuxt configuration only when Selaras needs build-time information. For example, use it when you add a new color role such as `tertiary`.

See [Theming](https://selarasui.my.id/overview/theming/overview) for all theme options.

### Predictable component customization

Each component has one `:ui` prop for instance-level customization.

Use `:ui` when you want to change the classes or attributes of one component.

```vue-html
<SButton :ui="{ base: 'font-mono' }">
  Save
</SButton>
```

Use CSS theme tokens when you want to change design values across many components.

Use `app.config.ts` or `STheme` when you want to change component configuration across an application or a subtree.

### Accessible primitives

Selaras uses Reka UI for many interactive primitives.

Reka UI provides keyboard interaction, focus management, ARIA behavior, and other accessibility features for these primitives.

Selaras adds its own components and styling on top of this foundation.

### Adaptive interfaces

Some Selaras components can use a different presentation when the available screen space changes.

For example, a component can use a popover on a larger screen and a modal or drawer on a smaller screen.

The component keeps one public API while Selaras changes the presentation.

### CSS-based motion

Selaras uses CSS for component transitions and interaction states.

It does not require a JavaScript animation library for its standard motion.

Selaras also respects the user's reduced-motion preference.

## What you get

When you install Selaras, Nuxt automatically imports the components with an `S` prefix.

For example:

```vue-html
<SButton />
<SInput />
<SSelect />
<SModal />
<STable />
```

Selaras also provides composables for application-level UI:

```ts
useModal()
useDrawer()
useSlideover()
useToast()
useCommandPalette()
```

Selaras can also provide small DOM behaviors through directives, such as:

```vue-html
<SButton v-ripple>
  Save
</SButton>

<SInput v-mask="'(###) ###-####'" inputmode="tel" />
```

## Where to start

Start with [Installation](https://selarasui.my.id/overview/getting-started/installation).

Then read [Theming](https://selarasui.my.id/overview/theming/overview) to learn how to customize Selaras with CSS.

Use the component documentation when you need the props, slots, events, variants, and `:ui` options for a specific component.

## Acknowledgments

Selaras uses [Reka UI](https://reka-ui.com){rel="&#x22;nofollow&#x22;"} as its primitive foundation.

We appreciate the following projects for their contributions to the Vue ecosystem and the inspiration they provide for thoughtful component design:

- [Nuxt UI](https://ui.nuxt.com){rel="&#x22;nofollow&#x22;"}
- [PrimeVue](https://primevue.org){rel="&#x22;nofollow&#x22;"}
- [shadcn-vue](https://www.shadcn-vue.com){rel="&#x22;nofollow&#x22;"}
- [UI Thing](https://ui-thing.behonbaker.com){rel="&#x22;nofollow&#x22;"}
- [Quasar](https://quasar.dev){rel="&#x22;nofollow&#x22;"}

Their work has helped shape our thinking about usability, customization, and developer experience as we develop Selaras.


# Messages and localization

Internal labels and messages come from a shared English registry. Override only the keys your application needs; the remaining keys keep their defaults.

## Global messages

```ts [app.config.ts]
export default defineAppConfig({
  selaras: {
    locale: 'id-ID',
    messages: {
      close: 'Tutup',
      clear: 'Hapus',
      search: 'Cari...',
      noOptions: 'Tidak ada pilihan',
      paginationInfo: (page: number, total: number) => `Halaman ${page} dari ${total}`,
    },
  },
})
```

Messages include accessible labels as well as visible text. Function-valued messages must remain functions with the documented arguments. See [useMessages](https://selarasui.my.id/utilities/composables/use-messages) for every key and its default.

For interpolated announcements such as Stepper progress, keep the message as a
function: `` stepperProgress: (step, total) => `Langkah ${step} dari ${total}` ``.
The [Stepper progress slot](https://selarasui.my.id/components/navigation/stepper#progress-announcements)
also allows an individual instance to supply its own text.

## Local content

```vue-html
<SInput placeholder="Search customers..." />
<SButton>Save changes</SButton>
```

Text you supply through props, item labels, and slots stays under your control. Use each component's documented props or slots to customize individual instances. There is no generic per-component `messages` prop or scoped message registry on `STheme`.

## Formatting locale

`selaras.locale` sets the BCP 47 locale used by locale-aware formatting and date controls. It does not translate the message registry. Configure both when localizing an application. Selaras does not ship additional translation packs.

Use [useLocale](https://selarasui.my.id/utilities/composables/use-locale) and [useMessages](https://selarasui.my.id/utilities/composables/use-messages) in your own components to share the application's configuration.


# Migrating to 1.0

Selaras 1.0 makes the theme and component contracts explicit. Most applications
can keep the usual installation and component usage. Review this guide if you
customize CSS variables, define a theme, use scoped configuration, or use an
adaptive picker.

## 1. Keep the aggregate CSS import unless you own a complete theme

The normal import remains the recommended starting point:

```css [assets/css/main.css]
@import "tailwindcss";
@import "@sewadah/selaras";
@import "#selaras/tailwind.css";
```

It includes Selaras's default foundations and semantic recipes. If your design
system supplies every role and functional token that Selaras can render, use
the structural entry instead:

```css [assets/css/main.css]
@import "tailwindcss";
@import "@sewadah/selaras/structural.css";
@import "#selaras/tailwind.css";
```

Structural CSS is an explicit complete-theme contract. It does not fall back
to Selaras palette values or diagnose omitted roles at runtime. See
[Theming](https://selarasui.my.id/overview/theming/overview) for the required semantic recipes and functional
inputs.

## 2. Use the public token namespaces

`--selaras-*` variables are customization inputs. Use
`--selaras-resolved-*` only when your own CSS needs the effective value after
Selaras has applied defaults, modes, and scopes. The old `--ui-*` aliases are
not part of the 1.0 contract; move overrides to the semantic input that
matches their purpose.

```css
/* Before: a legacy, collision-prone implementation alias. */
:root { --ui-border: oklch(0.8 0.02 260); }

/* After: the public semantic input. */
:root { --selaras-border-default: oklch(0.8 0.02 260); }
```

For a color role, provide individual recipe leaves such as
`--selaras-color-primary-fill`. Do not target generated selectors,
`--_selaras-*` variables, or mode/portal attributes: they are implementation
details and can change without a public migration path.

## 3. Register colors at Nuxt build time

A custom `color` name must be registered in `nuxt.config.ts`. Registration
generates its CSS bindings and augments `ColorRole`, so the same role works
across components without component-specific configuration:

```ts [nuxt.config.ts]
import { defineColor } from '@sewadah/selaras/theme'

export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  selaras: {
    theme: {
      colors: {
        tertiary: defineColor({
          light: {
            fill: 'var(--brand-tertiary)',
            onFill: '#fff',
            subtle: 'var(--brand-tertiary-subtle)',
            onSubtle: '#172033',
            text: '#284772',
            border: '#7aa1d6',
          },
          dark: {
            fill: '#91bcf5',
            onFill: '#10213b',
            subtle: '#18385f',
            onSubtle: '#e9f2ff',
            text: '#b7d4ff',
            border: '#6b9bd8',
          },
        }),
      },
    },
  },
})
```

Then use `<SButton color="tertiary" />`, `<SBadge color="tertiary" />`, and
other applicable components normally. For a single opaque sRGB brand color,
`defineColorFromSeed()` can create an accessible complete recipe. Existing
token systems can map resolved CSS values into `defineColor()`; the DTCG helper
converts resolved color values, but does not import or resolve a whole DTCG
document.

## 4. Move runtime settings under `selaras`

Place application-level Selaras configuration under `app.config.selaras`.
This prevents collisions with other Nuxt modules and gives scoped `STheme`
overrides the same vocabulary:

```ts [app.config.ts]
export default defineAppConfig({
  selaras: {
    ui: {
      button: { slots: { base: 'rounded-full' } },
    },
    defaults: {
      button: { size: 'lg' },
    },
    tokens: {
      light: { surfaces: { default: '#f8fafc' } },
    },
  },
})
```

Use `STheme`'s `defaults` prop for scoped component prop defaults. It supports
only components that document default support; `ui` recipe overrides remain
available for every typed recipe key.

## 5. Replace `mobileModal` with `adaptive`

Select, Autocomplete, DatePicker, and ColorPicker now opt into small-screen
presentation with `adaptive`:

```vue-html
<!-- Before -->
<SDatePicker mobile-modal />

<!-- After -->
<SDatePicker adaptive />
```

The presentation is selected when the control opens and remains stable until it
closes. Autocomplete places its input and suggestions inside the mobile modal. The module reads the Tailwind breakpoint selected by
`selaras.adaptive.breakpoint`; see [Installation](https://selarasui.my.id/overview/getting-started/nuxt-configuration#adaptive-breakpoint).

## 6. Follow controlled and native-control conventions

Use `v-model` for controlled values and `default-value` for an uncontrolled
initial value. Controls with open state use `v-model:open` and `default-open`
the same way. Do not pass both forms for the same state.

```vue-html
<!-- Controlled -->
<SSelect v-model="country" v-model:open="isCountryPickerOpen" />

<!-- Uncontrolled -->
<SSelect default-value="id" :default-open="false" />
```

For native form behavior, put `name`, `form`, `required`, `readonly`, ARIA
attributes, and focus listeners on the Selaras control itself. Select and
picker controls synchronize their native form value and reset behavior; a
multiple Select rejects duplicate selected identities.

## 7. Use supported imports

Import from the package root, documented secondary entries, or
`@sewadah/selaras/components/*`. Do not import renderer queues, internal
composables, raw recipe files, or generated implementation files from `dist`.
Those paths were never stable integration points and are intentionally outside
the 1.0 public API.

Read the [Installation](https://selarasui.my.id/overview/getting-started/installation), [Theming](https://selarasui.my.id/overview/theming/overview),
and individual component pages for the resulting API reference. The generated
changelog remains a historical record; this page is the migration contract.


# Nuxt configuration

## Options

Configure the module under the `selaras` key:

```ts
export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  selaras: {
    // Prefix used for auto-imported components.
    prefix: 'S', // default
  },
})
```

| Option                | Type                                              | Default        | Description                                                           |
| --------------------- | ------------------------------------------------- | -------------- | --------------------------------------------------------------------- |
| `prefix`              | `string`                                          | `'S'`          | Prefix used for auto-imported components (`SButton`, `SModal`, ...).  |
| `classPrefix`         | `string`                                          | none           | Namespaces every class Selaras's own components render - see below.   |
| `theme.colors`        | `Record<string, ColorModePair<ColorRecipeInput>>` | built-in roles | Build-time light and dark color recipes; also registers custom roles. |
| `adaptive.breakpoint` | `string`                                          | `'md'`         | Selects a Tailwind `--breakpoint-*` token for adaptive presentation.  |

## Adaptive breakpoint

CSS owns breakpoint values. Override the default condition in your stylesheet:

```css
@theme {
  --breakpoint-md: 60rem;
}
```

Or define your own `--breakpoint-tablet` token and select it with
`selaras: { adaptive: { breakpoint: 'tablet' } }`. Supported values are simple
lengths in `px`, `rem` or `em`. Keep breakpoint units consistent with your other
Tailwind conditions. Selaras reads the resolved length after mount and uses the
native `(width < …)` media query, including under a class prefix. Its initial
SSR render uses desktop presentation; the existing adaptive controls hold their
chosen presentation until they close.

These are build-time `@theme` conditions. Changing a breakpoint CSS variable at
runtime does not rewrite Tailwind's compiled responsive rules. A missing or
unsupported binding produces a console diagnostic and disables mobile
presentation; there is no implicit 768px fallback.

## Class prefix

Tailwind v4 supports namespacing every one of its own utilities behind a
prefix (`@import "tailwindcss" prefix(tw);`, which turns `px-4` into
`tw:px-4`) - typically to avoid collisions with another CSS framework or a
second, differently-configured Tailwind build in the same project. Selaras
can match that prefix in the classes its own components render, via
`classPrefix` under the `selaras` key in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],
  selaras: {
    classPrefix: 'tw',
  },
})
```

This is a module option, not an `app.config.ts` value - Tailwind CSS
generation happens at build time, so Selaras needs to know the prefix
early enough to generate the class candidates imported through
`#selaras/tailwind.css`. Your own Tailwind entry produces the matching CSS
(Tailwind never generates CSS for a class it can't find as literal text
anywhere, whether that's your own templates or a safelist - an
`app.config.ts` value alone, read only at render time, could never
produce that).

**This value must match your own Tailwind prefix exactly.** Selaras has
no way to detect your Tailwind configuration, so if the two ever drift -
`classPrefix: 'tw'` here while your CSS still says `prefix(ui)`, or one
set and not the other - every component renders classes your Tailwind
build never generated CSS for, and the entire UI comes out unstyled. No
error is raised either way; it silently looks like a blank stylesheet.
Only set this if you've already added `prefix(...)` to your own
`@import "tailwindcss"`.

**Your own classes need the same prefix, written by hand.** Selaras's
automatic handling only covers classes baked into its own shipped
components - it has no way to see a string you write yourself, so a
`:ui` override (or your own custom component built the same way, on
`resolveSlot`/`tv()`) needs the prefix written directly into the string:

```vue-html
<!-- classPrefix: 'tw' -->
<SButton :ui="{ base: 'tw:bg-purple-700' }" />
```

This isn't a Selaras-specific gotcha - it's the same rule Tailwind's
prefix feature already applies to every other class in your project once
you've adopted it (a plain `<div class="tw:flex">` needs the same
literal prefix). See [Theming](https://selarasui.my.id/overview/theming/overview) for the other ways to
customize a component.

## Custom color roles

`selaras.theme.colors` registers build-time color recipes, including custom role names. Each role supplies light and dark recipes. See [Color roles](https://selarasui.my.id/overview/theming/color-roles) for the full contract. Runtime classes, defaults, messages, and icons belong in `app.config.ts`, not these module options.

See [Global configuration](https://selarasui.my.id/overview/theming/global-configuration) and [Color modes](https://selarasui.my.id/overview/theming/color-modes).


# TypeScript

Every component exports named, documented `Props`/`Emits`/`Slots`
interfaces (`ButtonProps`, `ModalEmits`, `PopoverSlots`, ...) - useful when
you're wrapping a component, forwarding its props from your own, or just
want autocomplete on an object you're building up before passing it down.

## From the `@sewadah/selaras/types` barrel

The simplest path - one import for every component's types:

```ts
import type { ModalEmits, ModalProps, PopoverSlots } from '@sewadah/selaras/types'
```

## From a specific component

Each component's `.vue` file is also a valid type-only import path, if you
only need one component and don't want the rest pulled into scope:

```ts
import type { PopoverProps } from '@sewadah/selaras/components/Popover.vue'
```

## Module options

The module's own configuration type (the shape of the `selaras` key in
`nuxt.config.ts`, see [Installation](https://selarasui.my.id/overview/getting-started/installation)) is exported
from the package root:

```ts
import type { ModuleOptions } from '@sewadah/selaras'
```


# Color modes

Selaras automatically installs Nuxt Color Mode and ships light and dark token recipes. The `system` preference follows the operating system; the resolved appearance is either `light` or `dark`.

## Built-in controls

```vue-html
<SColorModeToggle />
<SColorModeSwitch />
```

[ColorModeToggle](https://selarasui.my.id/components/layout/color-mode-toggle) switches appearance through a button. [ColorModeSwitch](https://selarasui.my.id/components/layout/color-mode-switch) offers a switch. Both use the shared color-mode state.

## Preference and resolved appearance

```vue
<script setup lang="ts">
const colorMode = useColorMode()
</script>

<template>
  <SButton @click="colorMode.preference = 'system'">
    Use system appearance
  </SButton>
</template>
```

Read `colorMode.preference` for the user's choice and `colorMode.value` for the resolved mode. Nuxt Color Mode manages the root `.light` and `.dark` classes and persistence. Configure its `colorMode` options in `nuxt.config.ts` when you need a different initial preference or storage policy.

## Scoped appearance

```vue-html
<STheme as="section" mode="dark">
  <SCard>Dark content inside a light page</SCard>
</STheme>
```

`STheme` accepts `inherit`, `light`, and `dark`. An explicit scoped mode needs a DOM owner through `as`. See [Scoped themes](https://selarasui.my.id/overview/theming/scoped-themes) for component configuration and token overrides.

Color modes choose light or dark recipes. Semantic roles such as `primary` and `danger` select a color purpose; documentation theme presets choose a visual design. These are separate settings.


# Color roles

### Built-in component color roles

Selaras supplies these roles:

- `primary`
- `secondary`
- `success`
- `info`
- `warning`
- `danger`
- `neutral`

The default theme maps these roles to foundation palettes:

| Role        | Default foundation |
| ----------- | ------------------ |
| `primary`   | `indigo`           |
| `secondary` | `plum`             |
| `success`   | `green`            |
| `info`      | `blue`             |
| `warning`   | `yellow`           |
| `danger`    | `red`              |
| `neutral`   | `gray`             |

The role name is the meaning. The foundation name is the hue family.

For example, the default `warning` recipe reads the Selaras yellow palette.
The default `danger` recipe reads the Selaras red palette.

### Change one exact role value

You can override a public role input directly:

```css
:root {
  --selaras-color-warning-fill: #ffff00;
  --selaras-color-warning-on-fill: #000000;
}
```

Selaras uses the exact CSS value that you provide. It does not change it.

This example changes only two leaves. The other warning leaves still use their
default values. If you want one consistent custom warning theme, define the
complete recipe.

### Build one role from one CSS color

You do not need a TypeScript helper when you want to start from one CSS color.

You can keep the base color exact and derive the other values with CSS:

```css
:root {
  --brand: #fd5e53;

  --selaras-color-primary-fill:
    var(--brand);

  --selaras-color-primary-fill-hover:
    color-mix(in oklch, var(--brand), black 8%);

  --selaras-color-primary-fill-pressed:
    color-mix(in oklch, var(--brand), black 15%);

  --selaras-color-primary-on-fill:
    white;

  --selaras-color-primary-indicator:
    color-mix(in oklch, var(--brand), black 18%);

  --selaras-color-primary-subtle:
    color-mix(in oklch, var(--brand) 12%, transparent);

  --selaras-color-primary-subtle-hover:
    color-mix(in oklch, var(--brand) 18%, transparent);

  --selaras-color-primary-subtle-pressed:
    color-mix(in oklch, var(--brand) 24%, transparent);

  --selaras-color-primary-on-subtle:
    color-mix(in oklch, var(--brand), black 35%);

  --selaras-color-primary-text:
    color-mix(in oklch, var(--brand), black 20%);

  --selaras-color-primary-text-hover:
    color-mix(in oklch, var(--brand), black 28%);

  --selaras-color-primary-text-pressed:
    color-mix(in oklch, var(--brand), black 35%);

  --selaras-color-primary-border:
    var(--brand);

  --selaras-color-primary-focus:
    var(--brand);
}
```

This is only one possible recipe. You own the color choices.

Test the result in the components and contexts that your application uses.
Selaras does not change CSS values that you author.

### Complete role recipe

A color role has these public inputs:

```text
fill
fill-hover
fill-pressed
on-fill
indicator

subtle
subtle-hover
subtle-pressed
on-subtle

text
text-hover
text-pressed

border
focus
```

For `warning`, the full CSS names are:

```css
:root {
  --selaras-color-warning-fill: ...;
  --selaras-color-warning-fill-hover: ...;
  --selaras-color-warning-fill-pressed: ...;
  --selaras-color-warning-on-fill: ...;
  --selaras-color-warning-indicator: ...;

  --selaras-color-warning-subtle: ...;
  --selaras-color-warning-subtle-hover: ...;
  --selaras-color-warning-subtle-pressed: ...;
  --selaras-color-warning-on-subtle: ...;

  --selaras-color-warning-text: ...;
  --selaras-color-warning-text-hover: ...;
  --selaras-color-warning-text-pressed: ...;

  --selaras-color-warning-border: ...;
  --selaras-color-warning-focus: ...;
}
```

Replace `warning` with any registered role name.

The component variant selects the leaves that it needs. For example, a solid
Button uses `fill`, `on-fill`, `fill-hover`, and `fill-pressed`. A soft Button
uses the `subtle` leaves. Essential unpaired graphics, such as progress and
radio indicators, use `indicator`. When it is omitted, it follows `border`.

You can also supply different values for dark mode:

```css
:root {
  --selaras-color-warning-fill: #ffff00;
  --selaras-color-warning-on-fill: #000000;
}

:root.dark {
  --selaras-color-warning-fill: #eaea00;
  --selaras-color-warning-on-fill: #000000;
}
```

## Nuxt configuration and theme helpers

Use CSS first.

Use `nuxt.config.ts` when Selaras needs build-time information. The most common
color case is a new role name.

### Add a new role

Built-in role names already work without theme configuration.

A new role such as `tertiary` or `premium` must be registered at build time so
Selaras can:

- generate its role bindings
- add it to `ColorRole`
- make `color="tertiary"` type-safe

The current Nuxt API requires a light and dark recipe:

```ts
import { defineColor } from '@sewadah/selaras/theme'

export default defineNuxtConfig({
  modules: ['@sewadah/selaras'],

  selaras: {
    theme: {
      colors: {
        tertiary: defineColor({
          light: {
            fill: 'var(--company-tertiary-fill)',
            onFill: 'var(--company-tertiary-on-fill)',
            subtle: 'var(--company-tertiary-subtle)',
            onSubtle: 'var(--company-tertiary-on-subtle)',
            text: 'var(--company-tertiary-text)',
            border: 'var(--company-tertiary-border)',
          },
          dark: {
            fill: 'var(--company-tertiary-fill-dark)',
            onFill: 'var(--company-tertiary-on-fill-dark)',
            subtle: 'var(--company-tertiary-subtle-dark)',
            onSubtle: 'var(--company-tertiary-on-subtle-dark)',
            text: 'var(--company-tertiary-text-dark)',
            border: 'var(--company-tertiary-border-dark)',
          },
        }),
      },
    },
  },
})
```

After registration, you can use:

```vue-html
<SButton color="tertiary">
  Tertiary
</SButton>
```

You can still override the registered role from CSS:

```css
:root {
  --selaras-color-tertiary-fill: #8b5cf6;
}
```

The Nuxt configuration registers the role. CSS can still own its visual values.

### Override a built-in recipe in Nuxt config

You can also replace a built-in recipe:

```ts
import { defineColor } from '@sewadah/selaras/theme'

export default defineNuxtConfig({
  selaras: {
    theme: {
      colors: {
        warning: defineColor({
          light: {
            fill: '#ffff00',
            onFill: '#000000',
            subtle: '#fffbd1',
            onSubtle: '#3d3d00',
            text: '#6b6b00',
            border: '#a3a300',
          },
          dark: {
            fill: '#eaea00',
            onFill: '#000000',
            subtle: '#2a2a00',
            onSubtle: '#ffff99',
            text: '#ffff66',
            border: '#baba00',
          },
        }),
      },
    },
  },
})
```

`defineColor()` validates the required recipe shape. It does not change the
values that you provide.

The required leaves in each mode are:

- `fill`
- `onFill`
- `subtle`
- `onSubtle`
- `text`
- `border`

These leaves are optional:

- `fillHover`
- `fillPressed`
- `indicator` (defaults to `border`)
- `subtleHover`
- `subtlePressed`
- `textHover`
- `textPressed`
- `focus`

If an optional interaction leaf is missing, Selaras links it to the nearest
defined state. It does not calculate a new hue for `defineColor()`.

### Optional helper: `defineColorFromSeed()`

`defineColorFromSeed()` is not the CSS-first theme path.

Use it when you want Selaras to preserve one opaque sRGB color as the resting
solid fill and derive the rest of the recipe around it.

```ts
import { defineColorFromSeed } from '@sewadah/selaras/theme'

export default defineNuxtConfig({
  selaras: {
    theme: {
      colors: {
        coral: defineColorFromSeed('#FD5E53'),
      },
    },
  },
})
```

The light and dark resting `fill` values remain exactly the six-digit color
that you pass. Selaras chooses black or white `onFill`, derives distinct
interaction states, and derives text, border, focus, and indicator colors
against the supplied surfaces. If those supporting families cannot be derived
safely, the helper rejects the input and directs you to `defineColor()`.

Use CSS or `defineColor()` when you need exact control over every state.

The helper currently accepts only opaque six-digit sRGB hex values. It cannot
evaluate CSS variables, transparent colors, or arbitrary CSS expressions.

If you use custom surfaces, you can give the resolved light and dark surface
colors to the helper:

```ts
defineColorFromSeed('#FD5E53', {
  surfaces: {
    light: '#f4f0e8',
    dark: '#20242a',
  },
})
```

### Optional helper: DTCG resolved colors

If your design-token pipeline uses DTCG, resolve aliases and modes in that
pipeline first.

`dtcgColorToCss()` converts a resolved structured DTCG color value to CSS. It
does not parse a token document. It does not resolve aliases. It does not
select a mode.

```ts
import { dtcgColorToCss } from '@sewadah/selaras/theme'

const fill = dtcgColorToCss(tokens.brand.fill.$value, {
  path: 'semantic.brand.fill.$value',
})
```

You can then use the result in `defineColor()` or in your own generated CSS.


# Complete themes

### Complete CSS theme example

The following example replaces the main Selaras visual theme with CSS only.

It defines:

- surfaces
- general text
- general borders
- scrim
- radius
- shadows
- `primary`
- `secondary`
- `success`
- `info`
- `warning`
- `danger`
- `neutral`

It also defines separate light and dark values. When adapting this example,
check visible borders against the surfaces they touch in each mode. Surface
and border tokens are independent; see
[Check borders against their surfaces](https://selarasui.my.id/overview/theming/css-tokens#check-borders-against-their-surfaces).

These values are examples. Use the values that match your product.

```css
/* Light mode */
:root {
  /* Surfaces */
  --selaras-surface-canvas: #f9f9f9;
  --selaras-surface-default: #fffdf9;
  --selaras-surface-elevated: #ffffff;
  --selaras-surface-inverted: #161616;

  /* General text */
  --selaras-text-default: #1f1f1f;
  --selaras-text-muted: #707070;
  --selaras-text-inverted: #ffffff;

  /* General borders */
  --selaras-border-default: #e7e2dc;
  --selaras-border-muted: #f2eee9;
  --selaras-border-hover: #d4cdc5;

  /* Overlay */
  --selaras-scrim: rgb(0 0 0 / 0.55);

  /* Radius */
  --selaras-radius-base: 0.5rem;
  --selaras-radius-sm: 0.375rem;
  --selaras-radius-md: 0.5rem;
  --selaras-radius-lg: 1rem;
  --selaras-radius-full: 9999px;

  /* Shadows */
  --selaras-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
  --selaras-shadow-md: 0 6px 20px rgb(0 0 0 / 0.10);
  --selaras-shadow-lg: 0 18px 48px rgb(0 0 0 / 0.16);

  /* Primary */
  --selaras-color-primary-fill: #6d4aff;
  --selaras-color-primary-fill-hover: #5e3bf0;
  --selaras-color-primary-fill-pressed: #4f2fd8;
  --selaras-color-primary-on-fill: #ffffff;

  --selaras-color-primary-subtle: #f0ecff;
  --selaras-color-primary-subtle-hover: #e7e0ff;
  --selaras-color-primary-subtle-pressed: #ddd3ff;
  --selaras-color-primary-on-subtle: #3d267f;

  --selaras-color-primary-text: #5b3be0;
  --selaras-color-primary-text-hover: #4f31c4;
  --selaras-color-primary-text-pressed: #4328a9;

  --selaras-color-primary-border: #8d73ff;
  --selaras-color-primary-focus: #6d4aff;

  /* Secondary */
  --selaras-color-secondary-fill: #d946ef;
  --selaras-color-secondary-fill-hover: #c735dc;
  --selaras-color-secondary-fill-pressed: #ad27c2;
  --selaras-color-secondary-on-fill: #ffffff;

  --selaras-color-secondary-subtle: #fcecff;
  --selaras-color-secondary-subtle-hover: #f8ddff;
  --selaras-color-secondary-subtle-pressed: #f3ccff;
  --selaras-color-secondary-on-subtle: #70207c;

  --selaras-color-secondary-text: #b72cca;
  --selaras-color-secondary-text-hover: #9822aa;
  --selaras-color-secondary-text-pressed: #7d1b8b;

  --selaras-color-secondary-border: #e879f9;
  --selaras-color-secondary-focus: #d946ef;

  /* Success */
  --selaras-color-success-fill: #16a34a;
  --selaras-color-success-fill-hover: #138a3f;
  --selaras-color-success-fill-pressed: #107436;
  --selaras-color-success-on-fill: #ffffff;

  --selaras-color-success-subtle: #eaf8ef;
  --selaras-color-success-subtle-hover: #dcf3e4;
  --selaras-color-success-subtle-pressed: #ccecd8;
  --selaras-color-success-on-subtle: #14532d;

  --selaras-color-success-text: #16803f;
  --selaras-color-success-text-hover: #126b35;
  --selaras-color-success-text-pressed: #0f592d;

  --selaras-color-success-border: #3fc16d;
  --selaras-color-success-focus: #16a34a;

  /* Info */
  --selaras-color-info-fill: #0ea5e9;
  --selaras-color-info-fill-hover: #0c91cc;
  --selaras-color-info-fill-pressed: #0a7db0;
  --selaras-color-info-on-fill: #ffffff;

  --selaras-color-info-subtle: #e9f7fe;
  --selaras-color-info-subtle-hover: #d8f1fd;
  --selaras-color-info-subtle-pressed: #c7eafb;
  --selaras-color-info-on-subtle: #0c4a6e;

  --selaras-color-info-text: #087fb6;
  --selaras-color-info-text-hover: #076b9a;
  --selaras-color-info-text-pressed: #065a82;

  --selaras-color-info-border: #38bdf8;
  --selaras-color-info-focus: #0ea5e9;

  /* Warning */
  --selaras-color-warning-fill: #ffff00;
  --selaras-color-warning-fill-hover: #eeee00;
  --selaras-color-warning-fill-pressed: #d8d800;
  --selaras-color-warning-on-fill: #111111;

  --selaras-color-warning-subtle: #fffed6;
  --selaras-color-warning-subtle-hover: #fffca8;
  --selaras-color-warning-subtle-pressed: #fff77a;
  --selaras-color-warning-on-subtle: #575700;

  --selaras-color-warning-text: #757500;
  --selaras-color-warning-text-hover: #626200;
  --selaras-color-warning-text-pressed: #505000;

  --selaras-color-warning-border: #bdbd00;
  --selaras-color-warning-focus: #8a8a00;

  /* Danger */
  --selaras-color-danger-fill: #ff3b5c;
  --selaras-color-danger-fill-hover: #ed2e4e;
  --selaras-color-danger-fill-pressed: #d62241;
  --selaras-color-danger-on-fill: #ffffff;

  --selaras-color-danger-subtle: #fff0f3;
  --selaras-color-danger-subtle-hover: #ffe1e7;
  --selaras-color-danger-subtle-pressed: #ffd0da;
  --selaras-color-danger-on-subtle: #8a1c32;

  --selaras-color-danger-text: #d92c49;
  --selaras-color-danger-text-hover: #bd243f;
  --selaras-color-danger-text-pressed: #a21d35;

  --selaras-color-danger-border: #ff6b84;
  --selaras-color-danger-focus: #ff3b5c;

  /* Neutral */
  --selaras-color-neutral-fill: #27272a;
  --selaras-color-neutral-fill-hover: #3f3f46;
  --selaras-color-neutral-fill-pressed: #52525b;
  --selaras-color-neutral-on-fill: #ffffff;

  --selaras-color-neutral-subtle: #f4f4f5;
  --selaras-color-neutral-subtle-hover: #e4e4e7;
  --selaras-color-neutral-subtle-pressed: #d4d4d8;
  --selaras-color-neutral-on-subtle: #27272a;

  --selaras-color-neutral-text: #3f3f46;
  --selaras-color-neutral-text-hover: #27272a;
  --selaras-color-neutral-text-pressed: #18181b;

  --selaras-color-neutral-border: #a1a1aa;
  --selaras-color-neutral-focus: #52525b;
}


/* Dark mode */
:root.dark {
  /* Surfaces */
  --selaras-surface-canvas: #0c0c0d;
  --selaras-surface-default: #0f0f12;
  --selaras-surface-elevated: #18181d;
  --selaras-surface-inverted: #f6f6f6;

  /* General text */
  --selaras-text-default: #f4f4f5;
  --selaras-text-muted: #a1a1aa;
  --selaras-text-inverted: #18181b;

  /* General borders */
  --selaras-border-default: #2d2d35;
  --selaras-border-muted: #232329;
  --selaras-border-hover: #3b3b45;

  /* Overlay */
  --selaras-scrim: rgb(0 0 0 / 0.72);

  /* Radius */
  --selaras-radius-base: 0.5rem;
  --selaras-radius-sm: 0.375rem;
  --selaras-radius-md: 0.5rem;
  --selaras-radius-lg: 1rem;
  --selaras-radius-full: 9999px;

  /* Shadows */
  --selaras-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.28);
  --selaras-shadow-md: 0 8px 28px rgb(0 0 0 / 0.38);
  --selaras-shadow-lg: 0 22px 56px rgb(0 0 0 / 0.48);

  /* Primary */
  --selaras-color-primary-fill: #8b6cff;
  --selaras-color-primary-fill-hover: #9c82ff;
  --selaras-color-primary-fill-pressed: #ad98ff;
  --selaras-color-primary-on-fill: #171020;

  --selaras-color-primary-subtle: #261f46;
  --selaras-color-primary-subtle-hover: #302858;
  --selaras-color-primary-subtle-pressed: #3a306a;
  --selaras-color-primary-on-subtle: #d9d0ff;

  --selaras-color-primary-text: #b9a9ff;
  --selaras-color-primary-text-hover: #c9bcff;
  --selaras-color-primary-text-pressed: #d8d0ff;

  --selaras-color-primary-border: #7259dc;
  --selaras-color-primary-focus: #9f8aff;

  /* Secondary */
  --selaras-color-secondary-fill: #e879f9;
  --selaras-color-secondary-fill-hover: #ef91fb;
  --selaras-color-secondary-fill-pressed: #f3a9fc;
  --selaras-color-secondary-on-fill: #2a0b2e;

  --selaras-color-secondary-subtle: #3c173f;
  --selaras-color-secondary-subtle-hover: #4a1c4e;
  --selaras-color-secondary-subtle-pressed: #59235d;
  --selaras-color-secondary-on-subtle: #f7c9ff;

  --selaras-color-secondary-text: #f0a5fb;
  --selaras-color-secondary-text-hover: #f5bafd;
  --selaras-color-secondary-text-pressed: #f9d0fe;

  --selaras-color-secondary-border: #c65fd6;
  --selaras-color-secondary-focus: #e879f9;

  /* Success */
  --selaras-color-success-fill: #22c55e;
  --selaras-color-success-fill-hover: #35d36f;
  --selaras-color-success-fill-pressed: #4ade80;
  --selaras-color-success-on-fill: #061a0c;

  --selaras-color-success-subtle: #12331f;
  --selaras-color-success-subtle-hover: #174129;
  --selaras-color-success-subtle-pressed: #1d5033;
  --selaras-color-success-on-subtle: #bbf7d0;

  --selaras-color-success-text: #86efac;
  --selaras-color-success-text-hover: #a7f3c0;
  --selaras-color-success-text-pressed: #c6f6d5;

  --selaras-color-success-border: #3fba68;
  --selaras-color-success-focus: #4ade80;

  /* Info */
  --selaras-color-info-fill: #38bdf8;
  --selaras-color-info-fill-hover: #55c7fa;
  --selaras-color-info-fill-pressed: #73d2fb;
  --selaras-color-info-on-fill: #06151d;

  --selaras-color-info-subtle: #112f3f;
  --selaras-color-info-subtle-hover: #163c50;
  --selaras-color-info-subtle-pressed: #1b4a61;
  --selaras-color-info-on-subtle: #c7efff;

  --selaras-color-info-text: #7dd3fc;
  --selaras-color-info-text-hover: #9bdffc;
  --selaras-color-info-text-pressed: #bae9fd;

  --selaras-color-info-border: #2e9fd0;
  --selaras-color-info-focus: #38bdf8;

  /* Warning */
  --selaras-color-warning-fill: #ffff33;
  --selaras-color-warning-fill-hover: #ffff66;
  --selaras-color-warning-fill-pressed: #ffff88;
  --selaras-color-warning-on-fill: #111100;

  --selaras-color-warning-subtle: #333300;
  --selaras-color-warning-subtle-hover: #414100;
  --selaras-color-warning-subtle-pressed: #505000;
  --selaras-color-warning-on-subtle: #ffffb8;

  --selaras-color-warning-text: #ffff66;
  --selaras-color-warning-text-hover: #ffff88;
  --selaras-color-warning-text-pressed: #ffffaa;

  --selaras-color-warning-border: #baba24;
  --selaras-color-warning-focus: #ffff66;

  /* Danger */
  --selaras-color-danger-fill: #ff5c78;
  --selaras-color-danger-fill-hover: #ff748c;
  --selaras-color-danger-fill-pressed: #ff8ca0;
  --selaras-color-danger-on-fill: #26070d;

  --selaras-color-danger-subtle: #3c1720;
  --selaras-color-danger-subtle-hover: #4b1c28;
  --selaras-color-danger-subtle-pressed: #5b2330;
  --selaras-color-danger-on-subtle: #ffd0da;

  --selaras-color-danger-text: #ff9caf;
  --selaras-color-danger-text-hover: #ffb3c1;
  --selaras-color-danger-text-pressed: #ffc8d2;

  --selaras-color-danger-border: #d64f68;
  --selaras-color-danger-focus: #ff6b84;

  /* Neutral */
  --selaras-color-neutral-fill: #e4e4e7;
  --selaras-color-neutral-fill-hover: #f4f4f5;
  --selaras-color-neutral-fill-pressed: #ffffff;
  --selaras-color-neutral-on-fill: #18181b;

  --selaras-color-neutral-subtle: #27272a;
  --selaras-color-neutral-subtle-hover: #3f3f46;
  --selaras-color-neutral-subtle-pressed: #52525b;
  --selaras-color-neutral-on-subtle: #f4f4f5;

  --selaras-color-neutral-text: #d4d4d8;
  --selaras-color-neutral-text-hover: #e4e4e7;
  --selaras-color-neutral-text-pressed: #f4f4f5;

  --selaras-color-neutral-border: #71717a;
  --selaras-color-neutral-focus: #a1a1aa;
}
```

This example changes the complete semantic theme without `nuxt.config.ts`.

Use `nuxt.config.ts` only when you need build-time features, such as a new
role name that must work with a component `color` prop.


# Component styling

## The `:ui` prop and `STheme`

Color tokens and component class overrides are separate systems.

Use theme tokens for design values. Use `:ui` when you want to change classes
or attributes for one component instance.

```vue-html
<SButton :ui="{ base: 'font-mono' }">
  Custom
</SButton>
```

Each `:ui` key is a component slot.

A string adds classes. Selaras merges conflicting Tailwind classes with
`tailwind-merge`.

An object can contain `class` and other Vue attributes:

```vue-html
<SButton
  :ui="{
    base: {
      class: 'font-mono',
      'data-test': 'save-button',
    },
  }"
>
  Save
</SButton>
```

## Precedence

For component classes, the order from low priority to high priority is:

1. component base `tv()` theme
2. `app.config.selaras.ui`
3. ancestor `STheme` recipes, from outer to inner
4. the component root `class`
5. the component `:ui` slot class

For design tokens, normal CSS cascade rules apply to the public
`--selaras-*` inputs. Managed `STheme` and runtime token scopes create explicit
theme owners for their subtree and supported portals.


# CSS tokens

### Start with CSS

For most theme changes, edit CSS only.

Selaras has public input variables. The main groups are:

| Input                           | Purpose                                               |
| ------------------------------- | ----------------------------------------------------- |
| `--selaras-surface-*`           | Page and surface colors                               |
| `--selaras-text-*`              | General text colors                                   |
| `--selaras-border-*`            | General border colors                                 |
| `--selaras-color-<role>-<leaf>` | Component color roles, such as `primary` or `warning` |
| `--selaras-radius-*`            | Corner radius                                         |
| `--selaras-shadow-*`            | Shadow values                                         |
| `--selaras-z-*`                 | Overlay stacking                                      |
| `--selaras-scrim`               | Overlay backdrop                                      |

Selaras also has `--selaras-resolved-*` variables. These are effective read
values. Do not use them as theme inputs.

### Small CSS changes

You can change one value:

```css
:root {
  --selaras-radius-base: 0.375rem;
}
```

Or you can change general surfaces and text:

The light canvas is white by default. A card-heavy dashboard can use a subtle
canvas such as `#f9f9f9` while keeping its component surfaces white:

```css
:root {
  --selaras-surface-canvas: #f9f9f9;
  --selaras-surface-default: #ffffff;
  --selaras-surface-elevated: #fafafa;

  --selaras-text-default: #18181b;
  --selaras-text-muted: #71717a;

  --selaras-border-default: #e4e4e7;
  --selaras-border-hover: #d4d4d8;
}
```

For dark mode, override the same inputs under `:root.dark`:

```css
:root.dark {
  --selaras-surface-canvas: #0c0c0d;
  --selaras-surface-default: #09090b;
  --selaras-surface-elevated: #18181b;

  --selaras-text-default: #fafafa;
  --selaras-text-muted: #a1a1aa;

  --selaras-border-default: #27272a;
  --selaras-border-hover: #3f3f46;
}
```

Selaras follows the `.dark` class on `<html>` for the document theme.

### Check borders against their surfaces

`--selaras-surface-*` and `--selaras-border-*` are independent inputs. Component
themes choose which ones to pair. For example,
[DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) paints its background
with `surface-elevated` and draws its footer divider with `border-default`.
If both resolve to the same color, the divider blends into that background.

When a border should be visible, give it enough contrast against the surfaces
it touches. Check the actual component in both light and dark modes, including
hover and focus states, after changing either token or its foundation palette.
Different token names or different scale steps alone do not guarantee a visible
boundary. An intentionally blended border is also a valid design choice; each
border does not need to differ from every surface in your theme.

Selaras does not automatically adjust border colors or validate their contrast
when you override CSS variables. For transparent components, check the actual
background showing through, which may be your application's canvas.

### Change a complete foundation palette

The default foundations are Tailwind v4 theme variables.

For example, the default warning role uses the Selaras yellow foundation. You
can replace that foundation and keep the built-in warning recipe:

```css
@theme {
  --color-selaras-yellow-50: var(--color-orange-50);
  --color-selaras-yellow-100: var(--color-orange-100);
  --color-selaras-yellow-200: var(--color-orange-200);
  --color-selaras-yellow-300: var(--color-orange-300);
  --color-selaras-yellow-400: var(--color-orange-400);
  --color-selaras-yellow-500: var(--color-orange-500);
  --color-selaras-yellow-600: var(--color-orange-600);
  --color-selaras-yellow-700: var(--color-orange-700);
  --color-selaras-yellow-800: var(--color-orange-800);
  --color-selaras-yellow-900: var(--color-orange-900);
  --color-selaras-yellow-950: var(--color-orange-950);
}
```

The warning role now uses your replacement foundation through its existing
recipe.

The same rule applies to:

- `blue` for the default `info` role
- `red` for the default `danger` role
- `gray` for the default `neutral` role
- `green` for the default `success` role
- `yellow` for the default `warning` role
- `indigo` for the default `primary` role
- `plum` for the default `secondary` role

The Selaras gray foundation also supplies the default general surfaces, text,
and borders. A change to the gray foundation can therefore change more than the
`neutral` component role.

### Map an existing design system

You do not have to rename your design tokens.

For example, your design system can use a `10` to `100` scale:

```css
:root {
  --company-brand-10: ...;
  --company-brand-20: ...;
  --company-brand-30: ...;
  --company-brand-40: ...;
  --company-brand-50: ...;
  --company-brand-60: ...;
  --company-brand-70: ...;
  --company-brand-80: ...;
  --company-brand-90: ...;
  --company-brand-100: ...;

  --selaras-color-primary-fill: var(--company-brand-60);
  --selaras-color-primary-fill-hover: var(--company-brand-70);
  --selaras-color-primary-fill-pressed: var(--company-brand-80);
  --selaras-color-primary-on-fill: var(--company-brand-10);

  --selaras-color-primary-subtle: var(--company-brand-10);
  --selaras-color-primary-subtle-hover: var(--company-brand-20);
  --selaras-color-primary-subtle-pressed: var(--company-brand-30);
  --selaras-color-primary-on-subtle: var(--company-brand-90);

  --selaras-color-primary-text: var(--company-brand-70);
  --selaras-color-primary-text-hover: var(--company-brand-80);
  --selaras-color-primary-text-pressed: var(--company-brand-90);

  --selaras-color-primary-border: var(--company-brand-50);
  --selaras-color-primary-focus: var(--company-brand-60);
}
```

Map the neutral foundations as well as component color roles. For example,
if your existing system exposes these surface and divider tokens:

```css
:root {
  --selaras-surface-canvas: var(--company-canvas-light);
  --selaras-surface-default: var(--company-panel-light);
  --selaras-surface-elevated: var(--company-sidebar-light);

  --selaras-border-default: var(--company-divider-light);
  --selaras-border-muted: var(--company-divider-subtle-light);
  --selaras-border-hover: var(--company-divider-hover-light);
}

:root.dark {
  --selaras-surface-canvas: var(--company-canvas-dark);
  --selaras-surface-default: var(--company-panel-dark);
  --selaras-surface-elevated: var(--company-sidebar-dark);

  --selaras-border-default: var(--company-divider-dark);
  --selaras-border-muted: var(--company-divider-subtle-dark);
  --selaras-border-hover: var(--company-divider-hover-dark);
}
```

Define the `--company-*` variables in your own system. Choose divider values
that remain visible on the panels and sidebar where you need a boundary; do
not automatically map a border to the same scale entry as its background.
See [Check borders against their surfaces](https://selarasui.my.id/#check-borders-against-their-surfaces).

Your design system stays the source of truth. The `--selaras-*` variables are
the mapping layer.

### Use your own complete theme

Most applications should import the default theme:

```css
@import "tailwindcss";
@import "@sewadah/selaras";
@import "#selaras/tailwind.css";
```

A mature design system can omit Selaras-owned foundation colors:

```css
@import "tailwindcss";
@import "@sewadah/selaras/structural.css";
@import "#selaras/tailwind.css";
```

Then provide all semantic values that your application uses.

`structural.css` still supplies:

- Selaras source discovery for Tailwind
- variants
- animations
- structural CSS
- semantic read bindings

It does not supply the default Selaras foundation palette.

This mode is for a complete external theme. It is not an automatic unthemed
fallback.

### Radius, shadows, stacking, and Tailwind tokens

Radius uses one base input by default:

```css
:root {
  --selaras-radius-base: 0.25rem;
}
```

Selaras derives its default small, medium, and large radius values from this
base. You can override each radius input separately if you need to.

You can also set shadows and stacking values:

```css
:root {
  --selaras-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
  --selaras-shadow-md: 0 4px 16px -2px rgb(0 0 0 / 0.12);
  --selaras-shadow-lg: 0 12px 32px -4px rgb(0 0 0 / 0.16);

  --selaras-z-modal-overlay: 40;
  --selaras-z-modal: 50;
  --selaras-z-dropdown: 60;
  --selaras-z-tooltip: 70;
  --selaras-z-toast: 80;
}
```

Spacing and normal Tailwind breakpoints are Tailwind tokens, not Selaras theme
tokens:

```css
@theme {
  --breakpoint-3xl: 1920px;
  --spacing: 0.2rem;
}
```

The adaptive Selaras presentation uses the Tailwind breakpoint name selected by
`selaras.adaptive.breakpoint`. The default name is `md`.


# Global configuration

## Global overrides

Use `app.config.ts` when you want global component class changes or supported
component defaults.

This configuration is not required for normal CSS theme customization.

### Global component classes

```ts
export default defineAppConfig({
  selaras: {
    ui: {
      button: {
        slots: {
          base: 'font-mono',
        },
      },
    },
  },
})
```

Selaras extends the component `tailwind-variants` recipe with these classes.

### Global component defaults

Only components that support theme defaults read this configuration.

For example:

```ts
export default defineAppConfig({
  selaras: {
    defaults: {
      button: {
        size: 'lg',
      },
    },
  },
})
```

An explicit component prop has higher priority than a configured default.

### Global runtime tokens

`app.config.selaras.tokens` can also supply runtime token overrides.

Use this only when you need runtime-managed values. Prefer CSS for a static
global design theme.

All app-wide Selaras runtime settings use the `app.config.selaras` namespace.


# Theming

Selaras separates semantic CSS tokens, component styles, and behavior defaults. You can change a few values or supply a complete design system.

| Goal                                            | Guide                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| Change surfaces, typography, radius, or shadows | [CSS tokens](https://selarasui.my.id/overview/theming/css-tokens)                     |
| Customize semantic colors or register a role    | [Color roles](https://selarasui.my.id/overview/theming/color-roles)                   |
| Follow system appearance or switch light/dark   | [Color modes](https://selarasui.my.id/overview/theming/color-modes)                   |
| Style one component or slot                     | [Component styling](https://selarasui.my.id/overview/theming/component-styling)       |
| Share styles and defaults across the app        | [Global configuration](https://selarasui.my.id/overview/theming/global-configuration) |
| Style a subtree independently                   | [Scoped themes](https://selarasui.my.id/overview/theming/scoped-themes)               |
| Supply every theme input yourself               | [Complete themes](https://selarasui.my.id/overview/theming/complete-themes)           |

Start with the aggregate CSS import from [Installation](https://selarasui.my.id/overview/getting-started/installation). It supplies the default theme. For a complete owned theme, the structural entry retains component behavior and bindings while you provide the theme contract.

The documentation's Pelog, Slendro, and Degung presets demonstrate CSS and component configuration working together. They are documentation showcase themes, not additional named themes automatically installed into your application.


# Scoped themes

### Scoped component configuration

Use `STheme` to scope `ui` and supported default props to a subtree:

```vue-html
<STheme :ui="{ button: { slots: { base: 'font-mono' } } }">
  <SButton>Scoped</SButton>
</STheme>
```

Use a DOM boundary when you also need runtime token overrides:

```vue-html
<STheme
  as="section"
  :tokens="{
    light: {
      colors: {
        primary: {
          fill: '#fd5e53',
        },
      },
    },
  }"
>
  <SButton color="primary">Scoped color</SButton>
</STheme>
```

Runtime tokens are useful for dynamic or scoped themes. They do not replace the
normal CSS-first global theme path.

Supported overlay portals carry managed Selaras theme values into the portal
scope. External CSS custom properties still follow normal DOM inheritance.


# Calendar

## Usage

`SCalendar` is an inline date grid. Its value is an `@internationalized/date``DateValue`, as in `SDatePicker`. The selected date and the displayed month are
separate: use `v-model` for selection and `v-model:placeholder` when you need to
control the displayed month.


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const selected = shallowRef<DateValue>(new CalendarDate(2026, 9, 24))
</script>

<template>
  <SCalendar v-model="selected" />
</template>
```


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const selected = shallowRef<DateValue>(new CalendarDate(2026, 9, 24))
</script>

<template>
  <SCalendar v-model="selected" />
</template>
```

Use `default-value` and `default-placeholder` for initial uncontrolled state.
`min-value`, `max-value`, `is-date-disabled`, and `is-date-unavailable` control
which dates can be selected. A holiday can be shown without marking its date
unavailable.

### Meeting content

`#day` replaces the content *inside* the date button; it receives the date,
localized day label, and selected/today/disabled/unavailable state. Use it for
compact markers. `#day-details` renders beside that button within the day cell,
so meeting links or buttons do not become nested controls. Selaras associates
that detail area with the date button for assistive technology. The calendar
does not own your events or their data format.


```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const meetings: Record<string, string[]> = {
  '2026-09-08': ['Planning'],
  '2026-09-16': ['Design review', 'Team sync'],
  '2026-09-24': ['Release check'],
}
</script>

<template>
  <div class="max-w-full overflow-x-auto">
    <SCalendar
      :default-placeholder="new CalendarDate(2026, 9, 1)"
      calendar-label="September meetings"
      class="w-full"
      style="min-width: 42rem"
      :ui="{
        grids: 'block',
        grid: { class: 'w-full', style: { tableLayout: 'fixed' } },
        headCell: { style: { width: '14.285714%' } },
        cell: { class: 'border border-[var(--selaras-resolved-border-default)] p-1 text-start', style: { height: '8rem' } },
        dayDetails: { class: 'space-y-1 overflow-hidden pt-1 text-xs', style: { overflowWrap: 'anywhere', maxHeight: '5rem' } },
      }"
    >
      <template #day-details="{ date }">
        <div v-for="meeting in meetings[date.toString()] ?? []" :key="meeting" class="rounded bg-[var(--selaras-resolved-surface-elevated)] px-1 py-0.5">
          {{ meeting }}
        </div>
      </template>
    </SCalendar>
  </div>
</template>
```


```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const meetings: Record<string, string[]> = {
  '2026-09-08': ['Planning'],
  '2026-09-16': ['Design review', 'Team sync'],
  '2026-09-24': ['Release check'],
}
</script>

<template>
  <div class="max-w-full overflow-x-auto">
    <SCalendar
      :default-placeholder="new CalendarDate(2026, 9, 1)"
      calendar-label="September meetings"
      class="w-full"
      style="min-width: 42rem"
      :ui="{
        grids: 'block',
        grid: { class: 'w-full', style: { tableLayout: 'fixed' } },
        headCell: { style: { width: '14.285714%' } },
        cell: { class: 'border border-[var(--selaras-resolved-border-default)] p-1 text-start', style: { height: '8rem' } },
        dayDetails: { class: 'space-y-1 overflow-hidden pt-1 text-xs', style: { overflowWrap: 'anywhere', maxHeight: '5rem' } },
      }"
    >
      <template #day-details="{ date }">
        <div v-for="meeting in meetings[date.toString()] ?? []" :key="meeting" class="rounded bg-[var(--selaras-resolved-surface-elevated)] px-1 py-0.5">
          {{ meeting }}
        </div>
      </template>
    </SCalendar>
  </div>
</template>
```

The full month grid needs room on narrow screens. A consumer can scroll its
container, shorten the in-cell preview, or place the complete meeting list
below the calendar. If meetings have their own actions, render actual links or
buttons in `#day-details` and provide an accessible name for each action.

### Schedule composition

The same slots can support a larger schedule: the date sits at the top right
of each day cell, a timed event uses `SBadge`'s status dot, an all-day event
uses its soft badge, and a multi-day event is split into visual segments at
week boundaries. The whole cell selects a date, while each event opens a
popover with details and attendee avatars. This layout is an example-level
`ui` override; the compact calendar keeps centered dates by default.


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate, getDayOfWeek } from '@internationalized/date'

// Fixed fixture dates keep the documentation example identical during SSR,
// hydration, and static generation. The circled date stands in for "today".
const displayMonth = new CalendarDate(2026, 9, 1)
const sampleToday = '2026-09-24'

type EventColor = 'primary' | 'info' | 'success' | 'warning' | 'danger'
interface Attendee { name: string, initials: string, color: EventColor }
interface ScheduleEvent {
  title: string
  when: string
  description: string
  color: EventColor
  attendees: Attendee[]
}
interface TimedEvent extends ScheduleEvent { time: string }
interface MultiDayEvent extends ScheduleEvent { start: CalendarDate, end: CalendarDate }

const timedEvents: Record<string, TimedEvent[]> = {
  '2026-09-16': [{
    title: 'Design review',
    when: 'September 16 · 9:00–10:00 AM',
    time: '9:00 AM',
    description: 'Review the next release with design and engineering.',
    color: 'info',
    attendees: [{ name: 'Maya Putri', initials: 'MP', color: 'primary' }, { name: 'Arif Rahman', initials: 'AR', color: 'success' }],
  }],
  '2026-09-24': [{
    title: 'Roadmap cut',
    when: 'September 24 · 9:00–9:30 AM',
    time: '9:00 AM',
    description: 'Agree on the final scope for the next milestone.',
    color: 'success',
    attendees: [{ name: 'Maya Putri', initials: 'MP', color: 'primary' }, { name: 'Dina Sari', initials: 'DS', color: 'warning' }],
  }],
  '2026-09-25': [{
    title: 'Team sync',
    when: 'September 25 · 11:00–11:30 AM',
    time: '11:00 AM',
    description: 'Share progress, blockers, and the plan for next week.',
    color: 'warning',
    attendees: [{ name: 'Arif Rahman', initials: 'AR', color: 'success' }, { name: 'Dina Sari', initials: 'DS', color: 'warning' }],
  }],
}

const allDayEvents: Record<string, ScheduleEvent> = {
  '2026-09-08': {
    title: 'Company holiday',
    when: 'September 8 · All day',
    description: 'The team is away. Meetings resume the following day.',
    color: 'info',
    attendees: [],
  },
}

const multiDayEvent: MultiDayEvent = {
  title: 'Launch freeze',
  when: 'September 23–27 · All day',
  description: 'Only release-critical changes are merged during the launch freeze.',
  color: 'danger',
  attendees: [{ name: 'Maya Putri', initials: 'MP', color: 'primary' }, { name: 'Arif Rahman', initials: 'AR', color: 'success' }],
  start: new CalendarDate(2026, 9, 23),
  end: new CalendarDate(2026, 9, 27),
}

function coversMultiDay(date: DateValue) {
  return date.compare(multiDayEvent.start) >= 0 && date.compare(multiDayEvent.end) <= 0
}

// A single visual bar spans the remaining cells in its week. A new segment
// begins on Sunday when the event continues into another week.
function multiDaySegment(date: DateValue) {
  if (!coversMultiDay(date))
    return undefined
  const weekDay = getDayOfWeek(date, 'en-US')
  const continuation = date.compare(multiDayEvent.start) > 0
  if (continuation && weekDay !== 0)
    return undefined

  let days = 0
  let cursor = date
  while (days < 7 - weekDay && cursor.compare(multiDayEvent.end) <= 0) {
    days++
    cursor = cursor.add({ days: 1 })
  }
  return { days, continuation }
}
</script>

<template>
  <div class="max-w-full overflow-x-auto">
    <SCalendar
      :default-placeholder="displayMonth"
      :week-starts-on="0"
      calendar-label="September 2026 team schedule"
      class="schedule-calendar w-full"
      style="width: 100%; min-width: 44rem"
      :ui="{
        grid: { style: { display: 'table', width: '100%', tableLayout: 'fixed' } },
        headCell: { style: { width: '14.285714%' } },
        cell: { class: 'border border-[var(--selaras-resolved-border-default)]', style: { height: '8rem', padding: 0, position: 'relative', textAlign: 'end', verticalAlign: 'top' } },
        dayButton: { style: { position: 'absolute', inset: 0, width: '100%', height: '100%', padding: '0.5rem', borderRadius: 0, alignItems: 'flex-start', justifyContent: 'flex-end' } },
        dayDetails: { style: { textAlign: 'start' } },
      }"
    >
      <template #day="{ date, dayValue, selected }">
        <span :class="date.toString() === sampleToday && !selected ? 'schedule-today' : undefined">
          {{ dayValue }}
        </span>
      </template>

      <template #day-details="{ date }">
        <div v-if="allDayEvents[date.toString()]" class="schedule-all-day">
          <SPopover align="start" :ui="{ content: { 'aria-label': `${allDayEvents[date.toString()]!.title} details` } }">
            <button type="button" class="schedule-event-trigger" :aria-label="`Show details for ${allDayEvents[date.toString()]!.title}`">
              <SBadge
                :label="allDayEvents[date.toString()]!.title"
                :color="allDayEvents[date.toString()]!.color"
                variant="soft"
                size="sm"
              />
            </button>
            <template #content>
              <div class="schedule-popover">
                <strong>{{ allDayEvents[date.toString()]!.title }}</strong>
                <p>{{ allDayEvents[date.toString()]!.when }}</p>
                <p>{{ allDayEvents[date.toString()]!.description }}</p>
              </div>
            </template>
          </SPopover>
        </div>

        <div v-if="multiDaySegment(date)" class="schedule-span" :style="{ '--event-days': multiDaySegment(date)!.days }">
          <SPopover align="start" :ui="{ content: { 'aria-label': `${multiDayEvent.title} details` } }">
            <button type="button" class="schedule-event-trigger" :aria-label="`Show details for ${multiDayEvent.title}`">
              <SBadge
                :label="`${multiDaySegment(date)!.continuation ? '↳ ' : ''}${multiDayEvent.title}`"
                :color="multiDayEvent.color"
                variant="soft"
                size="sm"
              />
            </button>
            <template #content>
              <div class="schedule-popover">
                <strong>{{ multiDayEvent.title }}</strong>
                <p>{{ multiDayEvent.when }}</p>
                <p>{{ multiDayEvent.description }}</p>
                <div class="schedule-attendees">
                  <SAvatarGroup size="sm">
                    <SAvatar v-for="person in multiDayEvent.attendees" :key="person.name" :text="person.initials" :alt="person.name" :color="person.color" />
                  </SAvatarGroup>
                  <span>{{ multiDayEvent.attendees.map(person => person.name).join(', ') }}</span>
                </div>
              </div>
            </template>
          </SPopover>
        </div>
        <span v-else-if="coversMultiDay(date)" class="sr-only">{{ multiDayEvent.title }} continues</span>

        <div v-if="timedEvents[date.toString()]" class="schedule-timed">
          <SPopover v-for="event in timedEvents[date.toString()]" :key="event.title" align="start" :ui="{ content: { 'aria-label': `${event.title} details` } }">
            <button type="button" class="schedule-timed-event" :aria-label="`Show details for ${event.title}, ${event.when}`">
              <SBadge dot :color="event.color" aria-hidden="true" />
              <span class="schedule-timed-title">{{ event.title }}</span>
              <time>{{ event.time }}</time>
            </button>
            <template #content>
              <div class="schedule-popover">
                <strong>{{ event.title }}</strong>
                <p>{{ event.when }}</p>
                <p>{{ event.description }}</p>
                <div class="schedule-attendees">
                  <SAvatarGroup size="sm">
                    <SAvatar v-for="person in event.attendees" :key="person.name" :text="person.initials" :alt="person.name" :color="person.color" />
                  </SAvatarGroup>
                  <span>{{ event.attendees.map(person => person.name).join(', ') }}</span>
                </div>
              </div>
            </template>
          </SPopover>
        </div>
      </template>
    </SCalendar>
  </div>
</template>

<style scoped>
.schedule-calendar :deep([data-today]::after) {
  display: none;
}

/* Keep the full-cell selection, but give it the primary soft-button recipe. */
.schedule-calendar :deep([data-reka-calendar-cell-trigger][data-selected]) {
  background-color: var(--_selaras-color-subtle);
  color: var(--_selaras-color-on-subtle);
}

.schedule-calendar :deep([data-reka-calendar-cell-trigger][data-selected]:hover) {
  background-color: var(--_selaras-color-subtle-hover);
}

.schedule-calendar :deep([data-reka-calendar-cell-trigger][data-selected]:active) {
  background-color: var(--_selaras-color-subtle-pressed);
}

.schedule-today {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 1.75rem;
  height: 1.75rem;
  border-radius: 9999px;
  background: var(--selaras-resolved-color-success-subtle);
  color: var(--selaras-resolved-color-success-text);
  font-weight: 700;
}

.schedule-all-day,
.schedule-span {
  position: absolute;
  z-index: 2;
  inset-inline-start: 0.25rem;
  top: 2.4rem;
  width: calc(100% - 0.5rem);
  min-width: 0;
  text-align: start;
}

.schedule-span {
  z-index: 3;
  width: calc(var(--event-days) * 100% - 0.5rem);
}

.schedule-event-trigger {
  display: block;
  width: 100%;
  min-width: 0;
  cursor: pointer;
  text-align: start;
}

.schedule-event-trigger:focus-visible,
.schedule-timed-event:focus-visible {
  outline: 2px solid var(--_selaras-color-focus, currentColor);
  outline-offset: 2px;
}

.schedule-all-day :deep([data-selaras-color]),
.schedule-span :deep([data-selaras-color]) {
  display: flex;
  width: 100%;
  min-width: 0;
  justify-content: flex-start;
  overflow: hidden;
}

.schedule-timed {
  position: absolute;
  inset-inline: 0.25rem;
  top: 4.35rem;
  display: grid;
  gap: 0.25rem;
  min-width: 0;
  text-align: start;
}

.schedule-timed-event {
  display: flex;
  align-items: center;
  gap: 0.25rem;
  min-width: 0;
  width: 100%;
  cursor: pointer;
  text-align: start;
  font-size: 0.7rem;
  line-height: 1rem;
}

.schedule-timed-title {
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.schedule-timed-event time {
  flex: none;
  color: var(--selaras-resolved-text-muted);
  font-size: 0.65rem;
}

.schedule-calendar :deep(td[aria-selected="true"] .schedule-timed-event),
.schedule-calendar :deep(td[aria-selected="true"] .schedule-timed-event time) {
  color: var(--_selaras-color-on-subtle);
}

.schedule-popover {
  display: grid;
  width: min(18rem, calc(100vw - 3rem));
  gap: 0.5rem;
  font-size: 0.875rem;
  color: var(--selaras-resolved-text-default);
}

.schedule-popover strong {
  font-weight: 600;
}

.schedule-popover p {
  margin: 0;
}

.schedule-popover p:nth-of-type(1) {
  color: var(--selaras-resolved-text-muted);
}

.schedule-attendees {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  margin-top: 0.25rem;
  color: var(--selaras-resolved-text-muted);
  font-size: 0.75rem;
}
</style>
```


The fixture uses a fixed September 2026 date as its highlighted sample
"today" so its SSR and static output stay deterministic. In an application,
derive that date from your own time-zone-aware state. The event records,
week-segment calculation, and scoped layout styles are all in the
[complete example source](https://github.com/sewadahapp/selaras/blob/master/docs/components/content/examples/calendar/CalendarSchedule.vue){rel="&#x22;nofollow&#x22;"}.

### Styling

`ui` targets `root`, `header`, `heading`, `grids`, `grid`, `gridHead`,
`headCell`, `cell`, `dayButton`, `dayDetails`, and `footer`. `color` styles
unselected day/navigation buttons; `active-color` styles the selected day.
The `#footer` slot adds content below the grids. Each month is compact by
default; use `class="w-full"` with `:ui="{ grid: 'w-full' }"` for a calendar
that fills its container.


# Table

## Usage

Pass `data` and declare columns with `<SColumn>` children - no column config
objects required for the common case:


```vue
<script setup lang="ts">
interface User {
  name: string
  email: string
  role: string
}

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
  { name: 'Cara Lee', email: 'cara@example.com', role: 'Member' },
  { name: 'Dave Kim', email: 'dave@example.com', role: 'Viewer' },
  { name: 'Eve Torres', email: 'eve@example.com', role: 'Admin' },
])

const rowSelection = ref({})
const globalFilter = ref('')
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SInput v-model="globalFilter" placeholder="Search users..." class="max-w-64" />
    <STable
      v-model:row-selection="rowSelection"
      v-model:global-filter="globalFilter"
      :data="users"
      selectable
      :page-size="3"
    >
      <SColumn field="name" header="Name" filterable sortable />
      <SColumn field="email" header="Email" />
      <SColumn field="role" header="Role" />
    </STable>
  </div>
</template>
```


```vue
<script setup lang="ts">
interface User { name: string, email: string, role: string }

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
])

const rowSelection = ref({})
const globalFilter = ref('')
const getUserId = (user: User) => user.email
</script>

<template>
  <SInput v-model="globalFilter" placeholder="Search users..." />
  <STable
    v-model:row-selection="rowSelection"
    v-model:global-filter="globalFilter"
    :data="users"
    :get-row-id="getUserId"
    selectable
    :page-size="3"
  >
    <SColumn field="name" header="Name" filterable sortable />
    <SColumn field="email" header="Email" />
    <SColumn field="role" header="Role" />
  </STable>
</template>
```

Columns are not sortable by default. Add `sortable` to an `<SColumn>` to
enable sorting; an adjacent icon shows its current state (unsorted, ascending,
or descending). Click a sortable header, or focus it and press
:kbd[Enter] / :kbd[Space], to cycle through those states. Shift-click
a second sortable header to add it as a secondary sort without clearing the
first. `filterable` adds a funnel button beside that column's header; it opens
a popover with a live text filter and a Clear action. `selectable` adds a leading checkbox column wired to
`v-model:row-selection`.

Use `select-on-row-click` alongside `selectable` to toggle selection by
clicking anywhere on a row. Clicks on controls inside cells (such as links,
buttons, and checkboxes) keep their normal behavior. `row-hover` adds a subtle
theme-aware background while the pointer is over a body row:


```vue
<script setup lang="ts">
interface User {
  name: string
  email: string
  role: string
}

const users: User[] = [
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
  { name: 'Cara Lee', email: 'cara@example.com', role: 'Member' },
]

const rowSelection = ref<Record<string, true>>({})
const selectedUsers = computed(() => users.filter(user => rowSelection.value[user.email]))
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <STable
      v-model:row-selection="rowSelection"
      :data="users"
      :get-row-id="user => user.email"
      selectable
      select-on-row-click
      row-hover
    >
      <SColumn field="name" header="Name" />
      <SColumn field="email" header="Email" />
      <SColumn field="role" header="Role" />
    </STable>
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Selected: {{ selectedUsers.length ? selectedUsers.map(user => user.name).join(', ') : 'none' }}
    </p>
  </div>
</template>
```


```vue-html
<STable
  v-model:row-selection="rowSelection"
  :data="users"
  :get-row-id="user => user.email"
  selectable
  select-on-row-click
  row-hover
>
  <SColumn field="name" header="Name" />
  <SColumn field="email" header="Email" />
</STable>
```

Selection and expansion use TanStack's positional row ids by default. For
data that can be sorted, filtered, refreshed, or paginated by a server, provide
`get-row-id` so controlled state follows the record rather than its current
array position:

```vue-html
<STable
  v-model:row-selection="rowSelection"
  :data="users"
  :get-row-id="getUserId"
  selectable
>
  <SColumn field="name" header="Name" />
</STable>
```

`STable` doesn't render a global search input itself - wire one up yourself
and bind it to `v-model:global-filter`, same compositional approach as the
rest of the library.

### Grouped headers

Wrap columns in `<SColumnGroup>` to produce a multi-row header with the
correct `colspan`/`rowspan` - nest as deeply as needed:


```vue
<script setup lang="ts">
interface Employee {
  name: string
  age: number
  city: string
  department: string
}

const employees = ref<Employee[]>([
  { name: 'Alice Johnson', age: 29, city: 'New York', department: 'Engineering' },
  { name: 'Bob Smith', age: 34, city: 'Austin', department: 'Sales' },
  { name: 'Cara Lee', age: 41, city: 'Seattle', department: 'Engineering' },
])
</script>

<template>
  <STable :data="employees">
    <SColumn field="name" header="Name" />
    <SColumnGroup header="Details">
      <SColumn field="age" header="Age" />
      <SColumn field="city" header="City" />
      <SColumn field="department" header="Department" />
    </SColumnGroup>
  </STable>
</template>
```


```vue-html
<STable :data="employees">
  <SColumn field="name" header="Name" />
  <SColumnGroup header="Details">
    <SColumn field="age" header="Age" />
    <SColumn field="city" header="City" />
    <SColumn field="department" header="Department" />
  </SColumnGroup>
</STable>
```

### Pagination

Pagination is opt-in: every row renders on one page until you set
`page-size`. Once set, a [Pagination](https://selarasui.my.id/components/navigation/pagination)
control (page numbers, Prev/Next, scaling with `size`) appears automatically
once there's more than one page, and binds to `v-model:page-index` if you
need to read or control the current page yourself. `virtualize` is the
better fit for windowing a large dataset instead - see
[Virtual scroll](https://selarasui.my.id/#virtual-scroll) below.

### Presort

`default-sorting` seeds the initial sort without needing `v-model:sorting` -
useful when you want a table to open already sorted but still let the user
change it freely afterward:

```vue-html
<STable :data="users" :default-sorting="[{ id: 'name', desc: false }]">
  <SColumn field="name" header="Name" sortable />
</STable>
```

Unlike `sorting`, this is read once as a starting value, not on every render -
the same uncontrolled-default pattern as `Accordion`/`Tabs`'s `defaultValue`.

### Custom cell content

Give an `<SColumn>` a default slot to customize how each cell renders. It
receives `{ row, value }`, where `row` is the full row object and `value` is
that column's own field value:

```vue-html
<SColumn field="role" header="Role">
  <template #default="{ value }">
    <SBadge :label="value" />
  </template>
</SColumn>
```

### Custom header content

`<SColumn>`/`<SColumnGroup>` take the same treatment for their `header`/
`footer` - a named slot (scoped with `{ column }`, TanStack's own column
API) that replaces the plain string prop when given:


```vue
<script setup lang="ts">
interface User { name: string, email: string, role: string }

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
])
</script>

<template>
  <STable :data="users">
    <SColumn field="name" header="Name" />
    <SColumn field="role">
      <template #header>
        <span class="inline-flex items-center gap-1">
          Role
          <STooltip text="Admins can manage billing and members">
            <SIcon name="hugeicons:information-circle" class="size-3.5 text-[var(--selaras-resolved-text-muted)]" />
          </STooltip>
        </span>
      </template>
    </SColumn>
  </STable>
</template>
```


```vue-html
<SColumn field="role">
  <template #header>
    <span class="inline-flex items-center gap-1">
      Role
      <STooltip text="Admins can manage billing and members">
        <SIcon name="hugeicons:information-circle" class="size-3.5 text-[var(--selaras-resolved-text-muted)]" />
      </STooltip>
    </span>
  </template>
</SColumn>
```

### Row expansion

`expandable` adds a leading toggle column; give `STable` an `expanded` slot
for the detail content, receiving `{ row }` (the row's original data object):


```vue
<script setup lang="ts">
interface Order { id: number, customer: string, total: string, items: string[] }

const orders = ref<Order[]>([
  { id: 1001, customer: 'Alice Johnson', total: '$120.00', items: ['Widget A', 'Widget B'] },
  { id: 1002, customer: 'Bob Smith', total: '$45.50', items: ['Gadget C'] },
])
</script>

<template>
  <STable :data="orders" expandable>
    <SColumn field="id" header="Order" />
    <SColumn field="customer" header="Customer" />
    <SColumn field="total" header="Total" />
    <template #expanded="{ row }">
      <strong>Items:</strong> {{ (row as Order).items.join(', ') }}
    </template>
  </STable>
</template>
```


```vue-html
<STable :data="orders" expandable>
  <SColumn field="id" header="Order" />
  <SColumn field="customer" header="Customer" />
  <SColumn field="total" header="Total" />
  <template #expanded="{ row }">
    <strong>Items:</strong> {{ row.items.join(', ') }}
  </template>
</STable>
```

Expansion state is uncontrolled by default; bind `v-model:expanded` if you
need to read or drive it yourself (e.g. to expand a row programmatically).

### Tree data

Set `tree` to render hierarchical rows from each row's `subRows` array. Parent
rows get an inline expand control in the first visible data column, and nested
rows are indented by depth. For another child property, pass `get-sub-rows`.
Use stable `get-row-id` values when the same table may expand, select, or sort
tree rows. Tree mode uses `expanded` for child visibility, so it cannot be
combined with the detail `#expanded` slot.


```vue
<script setup lang="ts">
interface Team {
  name: string
  lead: string
  subRows?: Team[]
}

const teams = ref<Team[]>([
  {
    name: 'Engineering',
    lead: 'Arif Rahman',
    subRows: [
      {
        name: 'Platform',
        lead: 'Maya Putri',
        subRows: [
          { name: 'Runtime', lead: 'Dina Sari' },
          { name: 'Infrastructure', lead: 'Dave Kim' },
        ],
      },
      { name: 'Applications', lead: 'Cara Lee' },
    ],
  },
  { name: 'Design', lead: 'Nina Patel' },
])

const getTeamId = (team: Team) => team.name
</script>

<template>
  <STable :data="teams" :get-row-id="getTeamId" tree>
    <SColumn field="name" header="Team" />
    <SColumn field="lead" header="Lead" />
  </STable>
</template>
```


```vue-html
<STable :data="teams" tree :get-row-id="team => team.name">
  <SColumn field="name" header="Team" />
  <SColumn field="lead" header="Lead" />
</STable>
```

For a different nested field, return each row's children with
`get-sub-rows="row => row.children"`.

### Row click

`@row-click`/`@row-contextmenu` fire with the row's original data object
and the native event - useful for navigating to a detail page, for
instance. A row only gets a pointer cursor when `@row-click` actually has
a listener attached, so a plain, non-interactive table isn't misleadingly
styled as clickable:


```vue
<script setup lang="ts">
interface User {
  name: string
  email: string
  role: string
}

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
  { name: 'Cara Lee', email: 'cara@example.com', role: 'Member' },
])

const selected = ref<User>()

function onRowClick(row: unknown) {
  selected.value = row as User
}
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <STable :data="users" @row-click="onRowClick">
      <SColumn field="name" header="Name" />
      <SColumn field="email" header="Email" />
      <SColumn field="role" header="Role" />
    </STable>
    <p v-if="selected" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Selected: {{ selected.name }}
    </p>
  </div>
</template>
```


```vue-html
<STable :data="users" @row-click="(row) => router.push(`/users/${row.id}`)">
  <SColumn field="name" header="Name" />
  <SColumn field="email" header="Email" />
  <SColumn field="role" header="Role" />
</STable>
```

### Per-row styling

`row-class`/`row-style` are called with each row's own data, letting you
style a row conditionally - highlighting an overdue order, say:


```vue
<script setup lang="ts">
interface Order {
  id: string
  customer: string
  total: number
  overdue: boolean
}

const orders = ref<Order[]>([
  { id: '#1001', customer: 'Alice Johnson', total: 42, overdue: false },
  { id: '#1002', customer: 'Bob Smith', total: 128, overdue: true },
  { id: '#1003', customer: 'Cara Lee', total: 76, overdue: false },
])

function rowClass(row: unknown) {
  return (row as Order).overdue ? 'bg-[var(--selaras-resolved-color-danger-subtle)]' : undefined
}
</script>

<template>
  <STable :data="orders" :row-class="rowClass">
    <SColumn field="id" header="Order" />
    <SColumn field="customer" header="Customer" />
    <SColumn field="total" header="Total" />
  </STable>
</template>
```


```vue-html
<STable :data="orders" :row-class="(row) => row.overdue ? 'bg-[var(--selaras-resolved-color-danger-subtle)]' : undefined">
  <SColumn field="id" header="Order" />
  <SColumn field="customer" header="Customer" />
  <SColumn field="total" header="Total" />
</STable>
```

### Column visibility toggle

`column-toggle` renders a "Columns" button above the table that opens a panel
of checkboxes, one per column, letting the user hide/show columns on the fly:


```vue
<script setup lang="ts">
interface User { name: string, email: string, role: string }

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
])
</script>

<template>
  <STable :data="users" column-toggle>
    <SColumn field="name" header="Name" />
    <SColumn field="email" header="Email" />
    <SColumn field="role" header="Role" />
  </STable>
</template>
```


```vue-html
<STable :data="users" column-toggle>
  <SColumn field="name" header="Name" />
  <SColumn field="email" header="Email" />
  <SColumn field="role" header="Role" />
</STable>
```

Bind `v-model:column-visibility` if you need to read or control which
columns are shown yourself (e.g. to persist the choice).

### Frozen columns

Give a column `pinned="left"` or `pinned="right"` to keep it fixed at that
edge during horizontal scroll - pair it with `scroll-height` (below) and
enough columns (or a `ui.table` min-width override) that the table actually
needs to scroll:


```vue
<script setup lang="ts">
interface Employee {
  id: number
  name: string
  department: string
  role: string
  email: string
  phone: string
  city: string
  startDate: string
  actions: string
}

const employees = ref<Employee[]>(
  Array.from({ length: 8 }, (_, i) => ({
    id: i + 1,
    name: `Employee ${i + 1}`,
    department: 'Engineering',
    role: 'Software Engineer',
    email: `employee${i + 1}@example.com`,
    phone: '+1 555 0100',
    city: 'San Francisco',
    startDate: '2023-01-15',
    actions: '',
  })),
)
</script>

<template>
  <STable :data="employees" scroll-height="16rem" :ui="{ table: 'min-w-[960px]' }">
    <SColumn field="name" header="Name" pinned="left" />
    <SColumn field="department" header="Department" />
    <SColumn field="role" header="Role" />
    <SColumn field="email" header="Email" />
    <SColumn field="phone" header="Phone" />
    <SColumn field="city" header="City" />
    <SColumn field="startDate" header="Start date" />
    <SColumn field="actions" header="Actions" :sortable="false" pinned="right">
      <template #default>
        <div class="flex gap-2">
          <SButton variant="outline" size="sm">
            Edit
          </SButton>
          <SButton variant="outline" size="sm">
            Delete
          </SButton>
        </div>
      </template>
    </SColumn>
  </STable>
</template>
```


```vue-html
<STable :data="employees" scroll-height="16rem" :ui="{ table: 'min-w-[960px]' }">
  <SColumn field="name" header="Name" pinned="left" />
  <SColumn field="department" header="Department" />
  <SColumn field="role" header="Role" />
  <SColumn field="email" header="Email" />
  <SColumn field="phone" header="Phone" />
  <SColumn field="city" header="City" />
  <SColumn field="startDate" header="Start date" />
  <SColumn field="actions" header="Actions" sortable="false" pinned="right">
    <template #default>
      <SButton variant="outline" size="sm">Edit</SButton>
    </template>
  </SColumn>
</STable>
```

Sticky offsets are measured from each header's real rendered width after
mount and whenever the column list or visibility changes - not on every
possible layout shift (a later web-font load, a window resize), which is a
deliberate scope cut for this pass.

### Virtual scroll

`scroll-height` caps the table at a fixed CSS height with a sticky header and
vertical scroll. Add `virtualize` to only render the rows currently in view,
for datasets too large to put in the DOM all at once:


```vue
<script setup lang="ts">
const rows = ref(Array.from({ length: 10000 }, (_, i) => ({ id: i + 1, name: `Row ${i + 1}` })))
</script>

<template>
  <STable :data="rows" scroll-height="16rem" virtualize>
    <SColumn field="id" header="ID" />
    <SColumn field="name" header="Name" />
  </STable>
</template>
```


```vue-html
<STable :data="tenThousandRows" scroll-height="16rem" virtualize>
  <SColumn field="id" header="ID" />
  <SColumn field="name" header="Name" />
</STable>
```

Pass an object instead of `true` to tune `estimateSize`/`overscan`:

```vue-html
<STable :data="rows" scroll-height="16rem" :virtualize="{ estimateSize: 48, overscan: 12 }" />
```

Omit either field (or pass `virtualize` as plain `true`) and it defaults to
`estimateSize: 40, overscan: 8`.

Virtualizing replaces pagination as the strategy for a large dataset - while
`virtualize` is set, `page-size` has no effect and the pagination controls
don't render.

### Sizes, grid lines & striped rows

`size` (`sm` / `md` / `lg`) controls cell padding and text size. `gridlines`
adds borders around every cell instead of just row dividers, and `striped`
alternates row backgrounds:


```vue
<script setup lang="ts">
interface User { name: string, email: string, role: string }

const users = ref<User[]>([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
  { name: 'Carol Lee', email: 'carol@example.com', role: 'Member' },
])
</script>

<template>
  <STable :data="users" gridlines striped size="sm">
    <SColumn field="name" header="Name" />
    <SColumn field="email" header="Email" />
    <SColumn field="role" header="Role" />
  </STable>
</template>
```


Gridline tables keep one rounded outer frame around the scroll viewport, with
lines between columns and rows. The same frame remains around empty and loading
states; no extra table border is added. Use `ui.wrapper` to customize the frame
and `ui.th` / `ui.td` for cell lines.

```vue-html
<STable :data="users" gridlines striped size="sm">
  <SColumn field="name" header="Name" />
  <SColumn field="email" header="Email" />
  <SColumn field="role" header="Role" />
</STable>
```

### Loading

`loading` overlays the table with a spinner while keeping the existing rows
visible underneath, rather than swapping to an empty state:


```vue
<script setup lang="ts">
const loading = ref(true)

const users = ref([{ name: 'Alice Johnson', email: 'alice@example.com' }])
</script>

<template>
  <STable :data="users" :loading="loading">
    <SColumn field="name" header="Name" />
    <SColumn field="email" header="Email" />
  </STable>
</template>
```


```vue-html
<STable :data="users" :loading="loading">
  <SColumn field="name" header="Name" />
  <SColumn field="email" header="Email" />
</STable>
```

### Export

`STable` exposes an `exportCsv(filename?)` method via a template ref - it
downloads every row matching the current filters/sort across all pages (not
just the current page), skipping any synthetic selection/expand column:


```vue
<script setup lang="ts">
const tableRef = ref()

const users = ref([
  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { name: 'Bob Smith', email: 'bob@example.com', role: 'Member' },
])
</script>

<template>
  <div class="flex flex-col gap-3">
    <SButton variant="outline" size="sm" icon="hugeicons:download-01" class="self-end" @click="tableRef.exportCsv('users.csv')">
      Export CSV
    </SButton>
    <STable ref="tableRef" :data="users">
      <SColumn field="name" header="Name" />
      <SColumn field="email" header="Email" />
      <SColumn field="role" header="Role" />
    </STable>
  </div>
</template>
```


```vue-html
<script setup lang="ts">
const tableRef = ref()
</script>

<template>
  <SButton @click="tableRef.exportCsv('users.csv')">
    Export CSV
  </SButton>
  <STable ref="tableRef" :data="users">
    <SColumn field="name" header="Name" />
    <SColumn field="email" header="Email" />
  </STable>
</template>
```

### Server-side / manual mode

By default, `STable` sorts/filters/paginates `data` itself, locally, every
time. Set `manual-sorting`/`manual-filtering`/`manual-pagination` when
`data` is already sorted/filtered/paginated server-side instead - each one
opts that specific concern out of the local row model (TanStack's term for
the actual list of rows it computes after applying sorting/filtering/
pagination), so `STable` doesn't redundantly (and incorrectly) reprocess a
slice the server already handled. `sorting`/`global-filter`/`page-index` still drive the UI and
still emit their own `update:*` events the normal way; only the local row
model backing them changes.

`manual-pagination` also suppresses the built-in pagination UI entirely -
there's no way to derive a real page count from a server-paginated slice
of `data`, and guessing at one would be misleading. Bring your own
[SPagination](https://selarasui.my.id/components/navigation/pagination) instead, bound to
whatever your server actually returns, the same way this table already
expects you to bring your own search input for `global-filter` (see
[Usage](https://selarasui.my.id/#usage) above) rather than rendering one itself:

```vue-html
<script setup lang="ts">
const sorting = ref([])
const pageIndex = ref(0)
const total = ref(0)
const rows = ref([])

watch([sorting, pageIndex], async () => {
  const result = await fetchUsers({ sorting: sorting.value, page: pageIndex.value })
  rows.value = result.rows
  total.value = result.total
}, { immediate: true })
</script>

<template>
  <STable
    v-model:sorting="sorting"
    v-model:page-index="pageIndex"
    :data="rows"
    manual-sorting
    manual-pagination
  >
    <SColumn field="name" header="Name" sortable />
    <SColumn field="email" header="Email" sortable />
  </STable>
  <SPagination
    :page="pageIndex + 1"
    :total="total"
    :items-per-page="10"
    @update:page="(page) => pageIndex = page - 1"
  />
</template>
```

### Escape hatch: raw column defs

For full TanStack type inference (or features `<SColumn>` doesn't expose),
pass a `columns` prop instead of `<SColumn>` children. Raw column definitions
also start non-sortable; set `enableSorting: true` on columns that should sort.
`STable` infers its row type from `data`, and `TableColumnDef<TData>` checks
accessor keys and render contexts against that same type.
`createTableColumnHelper<TData>()` is
auto-imported by the Nuxt module and binds TanStack v9's feature generic to the
fixed feature set used by `STable`:

```vue
<script setup lang="ts">
interface User { id: string, name: string, age: number }

const column = createTableColumnHelper<User>()
const columns = column.columns([
  column.accessor('name', { header: 'Name', enableSorting: true }),
  column.accessor('age', {
    header: 'Age',
    enableSorting: true,
    cell: context => context.getValue().toFixed(0),
  }),
])
</script>

<template>
  <STable :data="users" :columns="columns" />
</template>
```

## Known limitation

`<SColumn>`'s `field` prop remains a plain `string`, rather than `keyof TData` -
this is a genuine Vue limitation (a parent's generic type parameter doesn't
propagate into child components referenced in its template), not something
unique to `STable` - any declarative-column-as-children table API in Vue has
the identical gap. As a cheap safety net, `STable` warns in dev mode (not
production) if a column's `field` doesn't exist as a key on the first row of
`data` - catching typos without any type-system gymnastics. For actual
compile-time safety, use the `columns` escape hatch above instead.

The table component itself is generic. Its `columns`, `getRowId`, `rowClass`,
`rowStyle`, row events, and `expanded` slot all share the row type inferred
from `data`.

### Accessibility

Sortable headers are keyboard-operable ( :kbd[Enter] / :kbd[Space]
toggle the sort, same as a click) and expose `aria-sort` reflecting the
current state. The row-expansion toggle is a real `<button>` with an
`aria-label` of "Expand row"/"Collapse row" that updates with its state.
Each filterable column has a labeled filter button that opens its text filter
in a popover; its Clear action resets that column's filter.
Column-visibility checkboxes are standard `SCheckbox` elements, and
pagination is a nested [SPagination](https://selarasui.my.id/components/navigation/pagination), so
both inherit those components' own accessibility behavior rather than
reimplementing it here.

## Custom `:ui`

`SColumn`/`SColumnGroup` render no DOM of their own (see
[Escape hatch: raw column defs](https://selarasui.my.id/#escape-hatch-raw-column-defs) above) and
have no theme file - every visual slot lives on `STable` itself. To see
exactly what you'd be overriding - the current default classes for every
slot - here's `Table`'s own theme file:

:theme-source{name="table"}

## Props

### STable

| Prop               | Type                                                          | Default                                     |
| ------------------ | ------------------------------------------------------------- | ------------------------------------------- |
| `data`             | `TData[]`                                                     | -                                           |
| `columns`          | `TableColumnDef<TData>[]`                                     | -                                           |
| `selectable`       | `boolean`                                                     | `false`                                     |
| `selectOnRowClick` | `boolean`                                                     | `false`                                     |
| `rowHover`         | `boolean`                                                     | `false`                                     |
| `pageSize`         | `number`                                                      | - (no pagination until set)                 |
| `loading`          | `boolean`                                                     | `false`                                     |
| `sorting`          | `SortingState`                                                | -                                           |
| `defaultSorting`   | `SortingState`                                                | -                                           |
| `rowSelection`     | `TableRowSelectionState`                                      | -                                           |
| `globalFilter`     | `string`                                                      | -                                           |
| `pageIndex`        | `number`                                                      | -                                           |
| `size`             | `'sm' | 'md' | 'lg'`                                          | `'md'`                                      |
| `gridlines`        | `boolean`                                                     | `false`                                     |
| `striped`          | `boolean`                                                     | `false`                                     |
| `expandable`       | `boolean`                                                     | `false`                                     |
| `tree`             | `boolean`                                                     | `false`                                     |
| `getSubRows`       | `(row: TData, index: number) => readonly TData[] | undefined` | `row => row.subRows` when `tree` is enabled |
| `expanded`         | `TableExpandedState`                                          | -                                           |
| `columnVisibility` | `TableColumnVisibilityState`                                  | -                                           |
| `columnToggle`     | `boolean`                                                     | `false`                                     |
| `scrollHeight`     | `string`                                                      | -                                           |
| `virtualize`       | `boolean | { estimateSize?: number; overscan?: number }`      | `false`                                     |
| `manualSorting`    | `boolean`                                                     | `false`                                     |
| `manualFiltering`  | `boolean`                                                     | `false`                                     |
| `manualPagination` | `boolean`                                                     | `false`                                     |
| `getRowId`         | `(row: TData, index: number) => string`                       | row index                                   |
| `rowClass`         | `(row: TData) => string | undefined`                          | -                                           |
| `rowStyle`         | `(row: TData) => Record<string, string> | undefined`          | -                                           |
| `ui`               | `Partial<Record<TableSlot, string | object>>`                 | -                                           |

## Emits

| Event                     | Payload                           | Description                                                                                                                                                      |
| ------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update:sorting`          | `TableSortingState`               | Backs `v-model:sorting` - fired whenever the sort state changes (see [Presort](https://selarasui.my.id/#presort))                                                |
| `update:rowSelection`     | `TableRowSelectionState`          | Backs `v-model:row-selection` - fired whenever the selected rows change                                                                                          |
| `update:globalFilter`     | `string`                          | Backs `v-model:global-filter` - fired whenever the global filter value changes                                                                                   |
| `update:pageIndex`        | `number`                          | Backs `v-model:page-index` - fired whenever the current page changes (see [Pagination](https://selarasui.my.id/#pagination))                                     |
| `update:expanded`         | `TableExpandedState`              | Backs `v-model:expanded` - fired whenever row expansion state changes (see [Row expansion](https://selarasui.my.id/#row-expansion))                              |
| `update:columnVisibility` | `TableColumnVisibilityState`      | Backs `v-model:column-visibility` - fired whenever column visibility changes (see [Column visibility toggle](https://selarasui.my.id/#column-visibility-toggle)) |
| `rowClick`                | `(row: TData, event: MouseEvent)` | Fired when a body row is clicked                                                                                                                                 |
| `rowContextmenu`          | `(row: TData, event: MouseEvent)` | Fired when a body row is right-clicked                                                                                                                           |

### SColumn

| Prop         | Type               | Default      |
| ------------ | ------------------ | ------------ |
| `field`      | `string`           | - (required) |
| `header`     | `string`           | -            |
| `footer`     | `string`           | -            |
| `sortable`   | `boolean`          | `false`      |
| `filterable` | `boolean`          | `false`      |
| `pinned`     | `'left' | 'right'` | -            |

### SColumnGroup

| Prop     | Type     | Default |
| -------- | -------- | ------- |
| `header` | `string` | -       |
| `footer` | `string` | -       |

## Slots

| Slot       | Props     | Description                                                |
| ---------- | --------- | ---------------------------------------------------------- |
| `empty`    | -         | Shown when `data` is empty                                 |
| `expanded` | `{ row }` | Detail content for an expanded row (requires `expandable`) |

`SColumn`'s own default slot customizes that column's cell content - see
[Custom cell content](https://selarasui.my.id/#custom-cell-content) above. `SColumn`/`SColumnGroup`
also both take `header`/`footer` slots (scoped with `{ column }`) - see
[Custom header content](https://selarasui.my.id/#custom-header-content) above.

## Methods

Access these via a template ref on `STable`.

| Method                         | Description                                                   |
| ------------------------------ | ------------------------------------------------------------- |
| `exportCsv(filename?: string)` | Downloads all matching rows (across every page) as a CSV file |


# Timeline

## Usage

`STimeline` renders an ordered sequence of events. It is display-only; use
[Stepper](https://selarasui.my.id/components/navigation/stepper) when people need to navigate or
advance through a workflow.


```vue
<script setup lang="ts">
const items = [
  { id: 'created', date: '9:15 AM', title: 'Request created', description: 'A new access request was submitted.' },
  { id: 'review', date: '10:30 AM', title: 'Manager review', description: 'The request was approved by Maya.' },
  { id: 'complete', date: '11:05 AM', title: 'Access granted', description: 'The team workspace is ready to use.', color: 'success' as const },
]
</script>

<template>
  <STimeline :items="items" />
</template>
```


```vue
<script setup lang="ts">
const items = [
  { id: 'created', date: '9:15 AM', title: 'Request created', description: 'A new request was submitted.' },
  { id: 'approved', date: '10:30 AM', title: 'Approved', color: 'success' },
]
</script>

<template>
  <STimeline :items="items" />
</template>
```

Each item can provide a stable `id`, a display `date`, an ISO `datetime`, a
`title`, a `description`, an `icon`, a semantic `color`, and a custom `slot`
name. Caller order is preserved. Dates are displayed as supplied so the
component does not assume a locale or time zone.

Set `icon` to any registered icon name to replace the solid dot with a larger
outlined marker. A per-item `color` changes that marker's accent:


```vue
<script setup lang="ts">
const items = [
  { id: 'submitted', date: '9:15 AM', title: 'Request submitted', icon: 'hugeicons:file-01' },
  { id: 'reviewed', date: '10:30 AM', title: 'Review completed', icon: 'hugeicons:checkmark-circle-01', color: 'success' as const },
  { id: 'released', date: '11:05 AM', title: 'Access granted', icon: 'hugeicons:rocket-01', color: 'info' as const },
]
</script>

<template>
  <STimeline :items="items" />
</template>
```


```vue-html
<STimeline :items="[
  { date: '9:15 AM', title: 'Request submitted', icon: 'hugeicons:file-01' },
  { date: '10:30 AM', title: 'Review completed', icon: 'hugeicons:checkmark-circle-01', color: 'success' },
]" />
```

### Orientation and alignment

The default is a vertical feed aligned to the start. `align` accepts `start`,
`end`, or `alternate`; the same choices place horizontal content below, above,
or alternately around the marker line.


```vue
<script setup lang="ts">
const items = [
  { id: 'plan', date: 'May', title: 'Plan' },
  { id: 'build', date: 'June', title: 'Build' },
  { id: 'launch', date: 'July', title: 'Launch' },
]
</script>

<template>
  <STimeline :items="items" orientation="horizontal" align="alternate" />
</template>
```


```vue-html
<STimeline :items="milestones" orientation="horizontal" align="alternate" />
```

### Custom content

Use `#marker`, `#date`, `#title`, and `#description` to replace individual
parts, or `#content` to build each event body. A `#item` slot replaces all
default content for every event. An item's `slot` field can choose a named
slot for just that event. Scoped slots receive `{ item, index }`, including
any custom fields supplied in the item data.


```vue
<script setup lang="ts">
const items = [
  {
    id: 'opened',
    date: 'Today · 9:15 AM',
    title: 'Issue opened',
    actor: 'Maya Putri',
    initials: 'MP',
    action: 'New issue',
    detail: 'Checkout returns an error when applying a discount code.',
    color: 'warning' as const,
  },
  {
    id: 'assigned',
    date: 'Today · 10:02 AM',
    title: 'Assigned to engineering',
    actor: 'Arif Rahman',
    initials: 'AR',
    action: 'In progress',
    detail: 'Arif picked up the issue and started investigating.',
    color: 'info' as const,
  },
  {
    id: 'fixed',
    date: 'Today · 1:40 PM',
    title: 'Fix merged',
    actor: 'Dina Sari',
    initials: 'DS',
    action: 'Resolved',
    detail: 'The validation fix is merged and ready for release.',
    color: 'success' as const,
  },
]
</script>

<template>
  <STimeline
    :items="items"
    :ui="{
      item: 'py-3 first:pt-0 last:pb-0',
      content: 'rounded-xl border border-[var(--selaras-resolved-border-default)] bg-[var(--selaras-resolved-surface-elevated)] p-4 sm:p-5',
    }"
  >
    <template #marker="{ item }">
      <SAvatar :name="item.actor" :text="item.initials" size="sm" />
    </template>
    <template #content="{ item }">
      <div class="flex flex-wrap items-start justify-between gap-x-4 gap-y-2">
        <h3 class="font-semibold tracking-tight">
          {{ item.title }}
        </h3>
        <SBadge :label="item.action" :color="item.color" variant="soft" size="sm" />
      </div>
      <p class="mt-2 text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
        {{ item.detail }}
      </p>
      <p class="mt-3 border-t border-[var(--selaras-resolved-border-default)] pt-3 text-sm text-[var(--selaras-resolved-text-muted)]">
        <span class="font-medium text-[var(--selaras-resolved-text-default)]">{{ item.actor }}</span>
        <span aria-hidden="true"> · </span>
        <time>{{ item.date }}</time>
      </p>
    </template>
  </STimeline>
</template>
```


```vue-html
<STimeline :items="activity" align="alternate">
  <template #marker="{ item }">
    <SAvatar :name="item.actor" :text="item.initials" size="sm" />
  </template>
  <template #content="{ item }">
    <strong>{{ item.title }}</strong>
    <SBadge :label="item.action" :color="item.color" variant="soft" />
  </template>
</STimeline>
```

The marker and connector remain decorative; put links and buttons in the
content slots so they keep their native interaction and accessibility.

### Styling

`size` accepts `sm`, `md`, or `lg`; `color` sets the default marker color and
each item can override it. `ui` can override `root`, `item`, `track`, `marker`,
`icon`, `connector`, `content`, `date`, `title`, and `description`. An item may
also provide its own `class` and partial `ui` overrides. The theme can be
configured globally under `ui.timeline`.

:theme-source{name="timeline"}

## Props

| Prop          | Type                                                  | Default    |
| ------------- | ----------------------------------------------------- | ---------- |
| `items`       | `TimelineItem[]`                                      | required   |
| `orientation` | `'vertical' | 'horizontal'`                           | `vertical` |
| `align`       | `'start' | 'end' | 'alternate'`                       | `start`    |
| `size`        | `'sm' | 'md' | 'lg'`                                  | `md`       |
| `color`       | `ColorRole`                                           | `primary`  |
| `ui`          | `Partial<Record<TimelineThemeSlot, string | object>>` | -          |

`TimelineItem` supports `id`, `date`, `datetime`, `title`, `description`,
`icon`, `color`, `slot`, `class`, per-item `ui`, and custom application data.

## Slots

| Slot            | Props             | Description                                                             |
| --------------- | ----------------- | ----------------------------------------------------------------------- |
| `marker`        | `{ item, index }` | Replaces the marker content; defaults to the item's icon or a dot       |
| `connector`     | `{ item, index }` | Content inside the decorative connector between items                   |
| `date`          | `{ item, index }` | Replaces the displayed date                                             |
| `title`         | `{ item, index }` | Replaces the title text                                                 |
| `description`   | `{ item, index }` | Replaces the description text                                           |
| `content`       | `{ item, index }` | Replaces the whole default event body                                   |
| `item`          | `{ item, index }` | Replaces the whole default event body, including date/title/description |
| Named item slot | `{ item, index }` | An item's `slot` property can select a named slot for that item         |


# Alert

## Usage


```vue
<template>
  <SAlert
    color="info"
    title="Heads up"
    description="This changes how the export command behaves - check the migration notes before upgrading."
    class="w-full"
  />
</template>
```


```vue-html
<SAlert
  color="info"
  title="Heads up"
  description="This changes how the export command behaves - check the migration notes before upgrading."
/>
```

### Variant

`variant` picks between `soft` (default), `outline`, and `solid`:


```vue
<script setup lang="ts">
const variants = ['solid', 'soft', 'outline'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SAlert
      v-for="variant in variants"
      :key="variant"
      color="success"
      :variant="variant"
      title="Payment received"
      description="Your subscription is now active."
    />
  </div>
</template>
```


```vue-html
<SAlert color="success" variant="outline" title="Payment received" description="Your subscription is now active." />
```

### Color

`color` accepts any registered semantic role. The four built-in feedback
intents - `success`, `danger`, `warning`, and `info` - each select a matching
default icon. Other roles still control the visual recipe, but do not guess an
icon; set `icon` explicitly when that role needs one. A default icon only
renders once `color` is supplied, so an `SAlert` with neither renders no icon:


```vue
<script setup lang="ts">
const alerts = [
  { color: 'success' as const, title: 'Success', description: 'Your changes have been saved.' },
  { color: 'danger' as const, title: 'Error', description: 'Something went wrong while saving.' },
  { color: 'warning' as const, title: 'Warning', description: 'This action can\'t be undone.' },
  { color: 'info' as const, title: 'Note', description: 'This feature is still in beta.' },
]
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SAlert v-for="alert in alerts" :key="alert.color" :color="alert.color" :title="alert.title" :description="alert.description" />
  </div>
</template>
```


```vue-html
<SAlert color="danger" title="Error" description="Something went wrong while saving." />
```

### Closable

`closable` shows a dismiss button and emits `close` when clicked - the
alert has no open state of its own, so hiding it is up to your own
`v-if`, the same way `Chip`'s own `removable` works:


```vue
<script setup lang="ts">
const visible = ref(true)
</script>

<template>
  <SAlert
    v-if="visible"
    color="warning"
    title="Unsaved changes"
    description="Leaving this page will discard your edits."
    closable
    class="w-full"
    @close="visible = false"
  />
  <SButton v-else variant="outline" color="neutral" @click="visible = true">
    Show the alert again
  </SButton>
</template>
```


```vue-html
<SAlert v-if="visible" title="Unsaved changes" closable @close="visible = false" />
```

### With actions

The `actions` slot renders buttons below the description:


```vue
<template>
  <SAlert color="danger" title="Upload failed" description="The file couldn't be uploaded - check your connection and try again." class="w-full">
    <template #actions>
      <SButton size="sm" color="danger">
        Retry
      </SButton>
      <SButton size="sm" variant="ghost" color="neutral">
        Dismiss
      </SButton>
    </template>
  </SAlert>
</template>
```


```vue-html
<SAlert color="danger" title="Upload failed" description="Check your connection and try again.">
  <template #actions>
    <SButton size="sm" color="danger">Retry</SButton>
    <SButton size="sm" variant="ghost" color="neutral">Dismiss</SButton>
  </template>
</SAlert>
```

## Props

| Prop          | Type                                          | Default |
| ------------- | --------------------------------------------- | ------- |
| `title`       | `string`                                      | -       |
| `description` | `string`                                      | -       |
| `icon`        | `string`                                      | -       |
| `closable`    | `boolean`                                     | `false` |
| `color`       | `ColorRole`                                   | `info`  |
| `variant`     | `'solid' | 'soft' | 'outline'`                | `soft`  |
| `ui`          | `Partial<Record<AlertSlot, string | object>>` | -       |

## Events

| Event   | Payload | Description                              |
| ------- | ------- | ---------------------------------------- |
| `close` | -       | Fires when the dismiss button is clicked |

## Slots

| Slot          | Props | Description                          |
| ------------- | ----- | ------------------------------------ |
| `title`       | -     | Replaces the title text              |
| `description` | -     | Replaces the description text        |
| `actions`     | -     | Action buttons below the description |


# Avatar

## Usage

An avatar shows a person or entity: a photo when a `src` is available, and a fallback - initials, an icon, or the default user glyph - while the photo loads or when it fails to load.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar />
    <SAvatar text="JD" />
    <SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" />
  </div>
</template>
```


```vue-html
<SAvatar />
<SAvatar text="JD" />
<SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" />
```

A bare `<SAvatar />` - no `src`, `text`, or `icon` - renders the default user icon on top of the placeholder color, still themed by `color`/`size`/`shape`.

### Fallback

`text` usually holds the person's initials. `icon` swaps the fallback for a glyph instead, and `text` wins when both are given. The `fallback` slot replaces the whole fallback content for anything custom.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar text="JD" color="primary" />
    <SAvatar icon="hugeicons:user-group" color="success" />
    <SAvatar color="warning">
      <template #fallback>
        <span class="text-sm font-semibold">ACME</span>
      </template>
    </SAvatar>
  </div>
</template>
```


```vue-html
<SAvatar text="JD" color="primary" />
<SAvatar icon="hugeicons:user-group" color="success" />
<SAvatar color="warning">
  <template #fallback>
    <span class="text-sm font-semibold">ACME</span>
  </template>
</SAvatar>
```

### Sizes


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar size="sm" text="JD" />
    <SAvatar size="md" text="JD" color="primary" />
    <SAvatar size="lg" text="JD" color="success" />
  </div>
</template>
```


```vue-html
<SAvatar size="sm" text="JD" />
<SAvatar size="md" text="JD" color="primary" />
<SAvatar size="lg" text="JD" color="success" />
```

### Colors

`color` styles the placeholder background and its initials/icon, visible while the image loads (or instead of one). `neutral` uses the plain elevated background, matching the rest of the library's soft neutral treatment.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar text="NT" color="neutral" />
    <SAvatar text="PR" color="primary" />
    <SAvatar text="SC" color="secondary" />
    <SAvatar text="OK" color="success" />
    <SAvatar text="NG" color="danger" />
    <SAvatar text="IF" color="info" />
    <SAvatar text="WG" color="warning" />
  </div>
</template>
```


```vue-html
<SAvatar text="OK" color="success" />
<SAvatar text="NG" color="danger" />
<SAvatar text="IF" color="info" />
```

### Shape

Avatars default to a circle; `shape="rounded"` uses the standard small radius instead.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar text="JD" />
    <SAvatar text="JD" shape="rounded" color="primary" />
    <SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" shape="rounded" />
  </div>
</template>
```


```vue-html
<SAvatar text="JD" />
<SAvatar text="JD" shape="rounded" color="primary" />
<SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" shape="rounded" />
```

### Status

`status` adds a small solid presence dot at the avatar's bottom-right corner. Its color is independent of `color` (`statusColor`, default `neutral`) since presence semantics - online, offline, busy - rarely match the avatar's identity color.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SAvatar text="JD" status status-color="success" />
    <SAvatar text="JD" status status-color="warning" />
    <SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" status status-color="danger" />
  </div>
</template>
```


```vue-html
<SAvatar text="JD" status status-color="success" />
<SAvatar text="JD" status />
<SAvatar src="https://i.pravatar.cc/96?img=3" alt="Jane Doe" status status-color="danger" />
```

### Accessibility

- When `src` is given, `alt` is forwarded to the image element.
- With no image, the avatar derives an accessible name from `alt` (falling back to `text`) and puts it on the root - override it any time with a direct `aria-label` fallthrough.
- The default user icon alone has no text at all, so a bare `<SAvatar />` used as a meaningful control (say, a profile link) should get an `aria-label`. The status dot is decorative; if its state carries meaning, give the avatar an `aria-label` that says so.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Avatar`'s own theme file:

:theme-source{name="avatar"}

## Props

| Prop             | Type                                                                                                                                                                             | Default     |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `as`             | `string | Component`                                                                                                                                                             | `'span'`    |
| `src`            | `string`                                                                                                                                                                         | -           |
| `alt`            | `string`                                                                                                                                                                         | -           |
| `text`           | `string`                                                                                                                                                                         | -           |
| `icon`           | `string`                                                                                                                                                                         | -           |
| `color`          | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                                                                                | `'neutral'` |
| `statusColor`    | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                                                                                | `'neutral'` |
| `size`           | `'sm' | 'md' | 'lg'`                                                                                                                                                             | `'md'`      |
| `shape`          | `'circle' | 'rounded'`                                                                                                                                                           | `'circle'`  |
| `status`         | `boolean`                                                                                                                                                                        | `false`     |
| `referrerPolicy` | `'' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url'` | -           |
| `crossOrigin`    | `'anonymous' | 'use-credentials' | ''`                                                                                                                                           | -           |
| `ui`             | `Partial<Record<AvatarSlot, string | object>>`                                                                                                                                   | -           |

## Slots

| Slot       | Props       | Description                                                                                                     |
| ---------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `fallback` | -           | Replaces the whole fallback content - initials, icon, or the default user icon                                  |
| `icon`     | `{ class }` | Replaces the fallback icon (when no `text` is given); the scoped class carries the icon's resolved size classes |

Customize the image itself (the `image` slot's classes) via `:ui="{ image: '...' }"`.


# AvatarGroup

## Usage

Wrap multiple `SAvatar` components inside `SAvatarGroup` to stack them with overlapping rings. The group propagates its `size` to every child avatar automatically — individual avatars that set their own `size` still take precedence.


```vue
<template>
  <SAvatarGroup>
    <SAvatar text="AB" color="primary" />
    <SAvatar text="CD" color="success" />
    <SAvatar text="EF" color="info" />
  </SAvatarGroup>
</template>
```


```vue-html
<SAvatarGroup>
  <SAvatar text="AB" color="primary" />
  <SAvatar text="CD" color="success" />
  <SAvatar text="EF" color="info" />
</SAvatarGroup>
```

### Max

`max` limits how many avatars are visible. Extra avatars collapse into a `+N` count indicator.
Static children, `v-for`, and `<template v-for>` lists use the same limit and
overlap styling. Whitespace and conditional placeholders aren't counted.


```vue
<script setup lang="ts">
const people = [
  { id: 'ab', text: 'AB', color: 'primary' },
  { id: 'cd', text: 'CD', color: 'success' },
  { id: 'ef', text: 'EF', color: 'info' },
  { id: 'gh', text: 'GH', color: 'warning' },
] as const
</script>

<template>
  <SAvatarGroup :max="2">
    <SAvatar v-for="person in people" :key="person.id" :text="person.text" :color="person.color" />
  </SAvatarGroup>
</template>
```


```vue
<script setup lang="ts">
const people = ['AB', 'CD', 'EF', 'GH']
</script>

<template>
  <SAvatarGroup :max="2">
    <SAvatar v-for="person in people" :key="person" :text="person" />
  </SAvatarGroup>
</template>
```

### Sizes

`size` controls the ring thickness and overlap spacing, and propagates to every child avatar that doesn't set its own size.


```vue
<template>
  <div class="flex items-center gap-4">
    <SAvatarGroup size="sm">
      <SAvatar text="AB" color="primary" />
      <SAvatar text="CD" color="success" />
    </SAvatarGroup>

    <SAvatarGroup>
      <SAvatar text="AB" color="primary" />
      <SAvatar text="CD" color="success" />
    </SAvatarGroup>

    <SAvatarGroup size="lg">
      <SAvatar text="AB" color="primary" />
      <SAvatar text="CD" color="success" />
    </SAvatarGroup>
  </div>
</template>
```


```vue-html
<SAvatarGroup size="sm">
  <SAvatar text="AB" color="primary" />
  <SAvatar text="CD" color="success" />
</SAvatarGroup>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `AvatarGroup`'s own theme file:

Global and scoped theme recipes use `ui.avatarGroup`; child avatars retain
their own `ui.avatar` recipe.

:theme-source{name="avatar-group"}

## Props

| Prop   | Type                                                          | Default |
| ------ | ------------------------------------------------------------- | ------- |
| `max`  | `number`                                                      | -       |
| `size` | `'sm' | 'md' | 'lg'`                                          | `'md'`  |
| `ui`   | `Partial<Record<'root' | 'item' | 'count', string | object>>` | -       |


# Badge

## Usage


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SBadge label="Default" />
    <SBadge label="Primary" color="primary" />
    <SBadge label="Solid" color="primary" variant="solid" />
    <SBadge label="Outline" color="danger" variant="outline" />
  </div>
</template>
```


```vue-html
<SBadge label="Primary" color="primary" />
<SBadge label="Solid" color="primary" variant="solid" />
<SBadge label="Outline" color="danger" variant="outline" />
<SBadge label="Subtle" color="primary" variant="subtle" />
```

### Icons

`icon` and `trailingIcon` add an icon before or after the label - useful for
a status glyph or a disclosure chevron. Badge is purely a display element,
though - for a dismissible tag, see [Chip](https://selarasui.my.id/components/elements/chip)
instead. The matching `icon`/`trailing-icon` slots replace the glyph
entirely when a plain icon name isn't enough (a spinner, for one).


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SBadge label="Verified" icon="hugeicons:tick-02" color="success" />
    <SBadge label="New" trailing-icon="hugeicons:arrow-right-01" color="primary" />
  </div>
</template>
```


```vue-html
<SBadge label="Verified" icon="hugeicons:tick-02" color="success" />
<SBadge label="New" trailing-icon="hugeicons:arrow-right-01" color="primary" />
```

### Icon only

An `icon` with no `label` (and no default slot content) drops the pill
shape for a circle instead - it reads as an avatar-adjacent status/count
indicator rather than a text label. Chip stays a pill even icon-only; this
is a deliberately different shape for a deliberately different role.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SBadge icon="hugeicons:notification-01" color="primary" />
    <SBadge icon="hugeicons:tick-02" color="success" size="lg" />
    <SBadge icon="hugeicons:notification-01" color="primary" variant="solid" />
    <SBadge icon="hugeicons:tick-02" color="success" variant="solid" size="lg" />
  </div>
</template>
```


```vue-html
<SBadge icon="hugeicons:notification-01" color="primary" />
<SBadge icon="hugeicons:tick-02" color="success" size="lg" />
<SBadge icon="hugeicons:notification-01" color="primary" variant="solid" />
<SBadge icon="hugeicons:tick-02" color="success" variant="solid" size="lg" />
```

### Status dot

`dot` adds a small solid-colored circle - the classic online/offline/away
indicator. Paired with a label, it sits in front of the text; alone, the
whole badge collapses to just the bare dot. Inline dots use the badge
foreground so they remain visible on solid pills; standalone dots use the
role text color regardless of `variant` for contrast against the stock surface.
Inline dots are decorative. A standalone
dot has an image role and needs an accessible name such as `aria-label`.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SBadge label="Online" dot color="success" />
    <SBadge label="Away" dot color="warning" />
    <SBadge label="Offline" dot color="neutral" />
    <SBadge dot color="success" aria-label="Online" />
  </div>
</template>
```


```vue-html
<SBadge label="Online" dot color="success" />
<SBadge label="Away" dot color="warning" />
<SBadge label="Offline" dot color="neutral" />

<!-- Bare dot, no visible label - give it an accessible name directly -->
<SBadge dot color="success" aria-label="Online" />
```

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-badge{...}` block works with no extra wiring, props
included (see [Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown"
section for how the pattern works generally):

```md
::s-badge{label="New" color="primary"}
::
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Badge`'s own theme file:

:theme-source{name="badge"}

## Props

| Prop           | Type                                               | Default     |
| -------------- | -------------------------------------------------- | ----------- |
| `label`        | `string`                                           | -           |
| `icon`         | `string`                                           | -           |
| `trailingIcon` | `string`                                           | -           |
| `dot`          | `boolean`                                          | `false`     |
| `color`        | `ColorRole` (built-in or registered semantic role) | `'neutral'` |
| `variant`      | `'solid' | 'soft' | 'outline' | 'subtle'`          | `'soft'`    |
| `size`         | `'sm' | 'md' | 'lg'`                               | `'md'`      |
| `ui`           | `Partial<Record<BadgeSlot, string | object>>`      | -           |

## Slots

| Slot            | Description                         |
| --------------- | ----------------------------------- |
| default         | Custom content, overrides `label`   |
| `icon`          | Replaces the leading icon entirely  |
| `trailing-icon` | Replaces the trailing icon entirely |


# Button

## Usage


```vue
<template>
  <SButton>
    Click me
  </SButton>
</template>
```


### Variants

`subtle` combines the tinted background of `soft` with a border. `link` uses
the same text color transitions as `text` and adds an underline on hover.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SButton variant="solid">
      Solid
    </SButton>
    <SButton variant="soft">
      Soft
    </SButton>
    <SButton variant="subtle">
      Subtle
    </SButton>
    <SButton variant="outline">
      Outline
    </SButton>
    <SButton variant="ghost">
      Ghost
    </SButton>
    <SButton variant="text">
      Text
    </SButton>
    <SButton variant="link">
      Link
    </SButton>
  </div>
</template>
```


### Colors

Every color across every variant, so it's easy to compare both within a
color (is soft/outline/ghost legible?) and across colors (do they stay
distinguishable at a glance?).


```vue
<script setup lang="ts">
const colors = ['primary', 'secondary', 'success', 'danger', 'info', 'warning', 'neutral'] as const
</script>

<template>
  <div class="flex flex-col gap-3">
    <div v-for="color in colors" :key="color" class="flex flex-wrap items-center gap-3">
      <span class="w-20 shrink-0 text-sm text-[var(--selaras-resolved-text-muted)] capitalize">{{ color }}</span>
      <SButton :color="color" variant="solid">
        Solid
      </SButton>
      <SButton :color="color" variant="soft">
        Soft
      </SButton>
      <SButton :color="color" variant="subtle">
        Subtle
      </SButton>
      <SButton :color="color" variant="outline">
        Outline
      </SButton>
      <SButton :color="color" variant="ghost">
        Ghost
      </SButton>
      <SButton :color="color" variant="text">
        Text
      </SButton>
      <SButton :color="color" variant="link">
        Link
      </SButton>
    </div>
  </div>
</template>
```


### Icons

`icon` and `trailingIcon` add an icon before or after the label - any
registered icon name works, not just `hugeicons:*`.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SButton icon="hugeicons:download-01">
      Download
    </SButton>
    <SButton trailing-icon="hugeicons:arrow-right-01">
      Continue
    </SButton>
  </div>
</template>
```


```vue-html
<SButton icon="hugeicons:download-01">Download</SButton>
<SButton trailing-icon="hugeicons:arrow-right-01">Continue</SButton>
```

### Icon only

There's no separate `iconOnly` prop - pass `icon` with no default slot
content and it shapes itself to a square automatically (matching its own
`size`), rather than requiring an explicit flag you could forget to set.
Always add `aria-label` yourself when there's no visible text - it falls
through to the root element like any other attr (see
[Accessibility](https://selarasui.my.id/#accessibility) below).


```vue
<template>
  <div class="flex items-center gap-3">
    <SButton icon="hugeicons:settings-01" variant="outline" aria-label="Settings" />
    <SButton icon="hugeicons:delete-02" color="danger" variant="ghost" aria-label="Delete" />
  </div>
</template>
```


```vue-html
<SButton icon="hugeicons:settings-01" variant="outline" aria-label="Settings" />
```

### Square

Icon-only buttons already shape themselves to a square automatically (see
above) - `square` is for when the content isn't an icon but should still get
that same equal-width/height treatment, like a page number or a calendar day.
Without it, each button sizes to its own text width and a row of them (a
pagination bar, a calendar grid) won't line up:


```vue
<template>
  <div class="flex flex-wrap items-start gap-6">
    <div class="flex flex-col gap-2">
      <span class="text-xs font-medium text-[var(--selaras-resolved-text-muted)]">Default sizing</span>
      <div class="flex gap-1">
        <SButton variant="outline" color="neutral">
          1
        </SButton>
        <SButton variant="outline" color="neutral">
          31
        </SButton>
      </div>
    </div>
    <div class="flex flex-col gap-2">
      <span class="text-xs font-medium text-[var(--selaras-resolved-text-muted)]">Square</span>
      <div class="flex gap-1">
        <SButton variant="outline" color="neutral" square>
          1
        </SButton>
        <SButton variant="outline" color="neutral" square>
          31
        </SButton>
      </div>
    </div>
  </div>
</template>
```


```vue-html
<SButton square>1</SButton>
<SButton square>31</SButton>
```

### Text

`text` never paints a background, at any state - only the label/icon color
shifts on hover. Meant for an action button that sits tight against another
control's own border, like a field's clear button - `ghost`'s hover-fill
would otherwise visually compete with that border right at the seam:

The border in this comparison belongs to the illustrative field, not either
button.


```vue
<template>
  <div class="flex flex-wrap gap-6">
    <div class="flex flex-col gap-1.5">
      <span class="text-xs font-medium text-[var(--selaras-resolved-text-muted)]">Ghost clear action</span>
      <div class="flex h-10 w-52 items-center gap-2 rounded-[var(--selaras-resolved-radius-md)] px-3 ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
        <span class="flex-1 text-sm text-[var(--selaras-resolved-text-muted)]">Example field</span>
        <SButton icon="hugeicons:cancel-01" size="sm" variant="ghost" color="neutral" aria-label="Clear" />
      </div>
    </div>
    <div class="flex flex-col gap-1.5">
      <span class="text-xs font-medium text-[var(--selaras-resolved-text-muted)]">Text clear action</span>
      <div class="flex h-10 w-52 items-center gap-2 rounded-[var(--selaras-resolved-radius-md)] px-3 ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
        <span class="flex-1 text-sm text-[var(--selaras-resolved-text-muted)]">Example field</span>
        <SButton icon="hugeicons:cancel-01" size="sm" variant="text" color="neutral" aria-label="Clear" />
      </div>
    </div>
  </div>
</template>
```


```vue-html
<div class="flex items-center rounded-[var(--selaras-resolved-radius-md)] ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
  <span>Example field</span>
  <SButton icon="hugeicons:cancel-01" variant="text" aria-label="Clear" />
</div>
```

`link` is the underlined text-action variant. Use it for an action that
navigates; `text` is the unadorned text action.

### Loading

`loading` swaps the leading icon for a spinner. It doesn't imply `disabled` -
combine both if a busy button shouldn't be clickable, the same split
[Select](https://selarasui.my.id/components/forms/select#states) and
[Autocomplete](https://selarasui.my.id/components/forms/autocomplete#sizes-and-states) already use
for their own `loading` prop.


```vue
<script setup lang="ts">
const saving = ref(false)

function save() {
  saving.value = true
  setTimeout(() => {
    saving.value = false
  }, 1500)
}
</script>

<template>
  <SButton icon="hugeicons:floppy-disk" :loading="saving" :disabled="saving" @click="save">
    {{ saving ? 'Saving...' : 'Save' }}
  </SButton>
</template>
```


```vue-html
<SButton icon="hugeicons:floppy-disk" :loading="saving" :disabled="saving" @click="save">
  {{ saving ? 'Saving...' : 'Save' }}
</SButton>
```

### As a link

`to` renders a NuxtLink for client-side navigation. Use `as="a"` with
`href` for external links, or set `as` explicitly to override automatic
routing. Disabled routed buttons expose `aria-disabled`, leave the tab order,
and ignore clicks.


```vue
<template>
  <SButton as="a" href="https://github.com" target="_blank" rel="noopener" variant="outline" trailing-icon="hugeicons:square-arrow-up-right">
    Open a link
  </SButton>
</template>
```


```vue-html
<SButton as="a" href="https://github.com" target="_blank" rel="noopener" trailing-icon="hugeicons:square-arrow-up-right">
  Open a link
</SButton>
<SButton to="/account">Account</SButton>
<SButton variant="link" to="/forgot-password">Forgot password?</SButton>
```

For the common internal-route case, `to` handles NuxtLink automatically. If
you need another routing component, pass its resolved component reference in
`as` - `Primitive` renders the explicit component via `h()`:

```vue
<script setup lang="ts">
const NuxtLinkComponent = resolveComponent('NuxtLink')
</script>

<template>
  <SButton :as="NuxtLinkComponent" to="/components/elements/button">
    Browse components
  </SButton>
</template>
```

### Raised

`raised` adds `--selaras-resolved-shadow-md`, independent of `variant` - useful for a solid
button that needs to lift off a busy background, or even a `soft`/`ghost`
one that wants some elevation without switching to `solid`.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SButton raised>
      Raised solid
    </SButton>
    <SButton raised variant="soft">
      Raised soft
    </SButton>
  </div>
</template>
```


```vue-html
<SButton raised>Raised solid</SButton>
<SButton raised variant="soft">Raised soft</SButton>
```

### Badge

There's no built-in badge slot - overlay a real [Badge](https://selarasui.my.id/components/elements/badge)
on an icon-only button with a `relative`/`absolute` pair:


```vue
<template>
  <div class="relative inline-flex">
    <SButton variant="outline" icon="hugeicons:notification-01" aria-label="Notifications" />
    <SBadge label="3" color="danger" size="sm" class="absolute -top-1.5 -right-1.5" />
  </div>
</template>
```


```vue-html
<div class="relative inline-flex">
  <SButton variant="outline" icon="hugeicons:notification-01" aria-label="Notifications" />
  <SBadge label="3" color="danger" size="sm" class="absolute -top-1.5 -right-1.5" />
</div>
```

### Button group

Adjacent buttons visually joined into one unit are their own component -
see [ButtonGroup](https://selarasui.my.id/components/elements/button-group).

### Sizes and states

`size` takes `sm` / `md` / `lg`, `disabled` prevents interaction and dims the
button - see the [Props](https://selarasui.my.id/#props) table below.

### Custom `:ui`

Every slot can be overridden without fighting the defaults — the override is
tailwind-merge'd, so conflicting utilities resolve instead of both applying.

```vue-html
<SButton :ui="{ base: 'rounded-full' }">Pill button</SButton>
```

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Button`'s own theme file:

:theme-source{name="button"}

### Accessibility

A default `as="button"` gets native button semantics (keyboard-activatable
with :kbd[Enter] / :kbd[Space], exposed as `role="button"`) for free -
nothing to configure. Rendering `as="a"` instead exposes link semantics and
keyboard behavior instead, which is exactly why [As a link](https://selarasui.my.id/#as-a-link) exists
rather than styling an `<a>` to merely look like a button. An icon-only button
has no accessible name of its own - always pass `aria-label` in that case, as
shown above.

## Props

| Prop           | Type                                                                        | Default    |
| -------------- | --------------------------------------------------------------------------- | ---------- |
| `as`           | `string | Component`                                                        | `'button'` |
| `color`        | `ColorRole` (built-in and registered roles)                                 | `primary`  |
| `to`           | `string`                                                                    | -          |
| `variant`      | `'solid' | 'soft' | 'subtle' | 'outline' | 'ghost' | 'text' | 'link'`       | `solid`    |
| `size`         | `'sm' | 'md' | 'lg'`                                                        | `md`       |
| `block`        | `boolean`                                                                   | `false`    |
| `raised`       | `boolean`                                                                   | `false`    |
| `disabled`     | `boolean`                                                                   | `false`    |
| `loading`      | `boolean`                                                                   | `false`    |
| `icon`         | `string`                                                                    | -          |
| `trailingIcon` | `string`                                                                    | -          |
| `square`       | `boolean`                                                                   | -          |
| `ui`           | `Partial<Record<'base' | 'leadingIcon' | 'trailingIcon', string | object>>` | -          |

## Slots

| Slot            | Props       | Description                                                                                    |
| --------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `icon`          | `{ class }` | Replaces the leading icon entirely; the scoped class carries the icon's resolved size classes  |
| `trailing-icon` | `{ class }` | Replaces the trailing icon entirely; the scoped class carries the icon's resolved size classes |


# ButtonGroup

## Usage

`SButtonGroup` squares off each button's inner corner and overlaps their
1px rings so the shared edge isn't double-thick, bumping the hovered/
focused button's edge on top of its neighbor's:


```vue
<template>
  <SButtonGroup>
    <SButton variant="outline">
      Day
    </SButton>
    <SButton variant="outline">
      Week
    </SButton>
    <SButton variant="outline">
      Month
    </SButton>
  </SButtonGroup>
</template>
```


```vue-html
<SButtonGroup>
  <SButton variant="outline">Day</SButton>
  <SButton variant="outline">Week</SButton>
  <SButton variant="outline">Month</SButton>
</SButtonGroup>
```

### Vertical

`orientation="vertical"` stacks buttons vertically, squaring off the top/
bottom corners instead:


```vue
<template>
  <SButtonGroup orientation="vertical">
    <SButton variant="outline">
      Submit
    </SButton>
    <SButton variant="outline">
      Cancel
    </SButton>
  </SButtonGroup>
</template>
```


```vue-html
<SButtonGroup orientation="vertical">
  <SButton variant="outline">Submit</SButton>
  <SButton variant="outline">Cancel</SButton>
</SButtonGroup>
```

`SButtonGroup` isn't limited to buttons - see [InputGroup](https://selarasui.my.id/components/forms/input-group)
for the same joining mechanism extended to Input/Select/Textarea, which
carry their own ring/radius one level deeper than a Button does.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `ButtonGroup`'s own theme file:

Global and scoped theme recipes use `ui.buttonGroup`.

:theme-source{name="button-group"}

## Props

| Prop          | Type                                       | Default        |
| ------------- | ------------------------------------------ | -------------- |
| `orientation` | `'horizontal' | 'vertical'`                | `'horizontal'` |
| `ui`          | `Partial<Record<'root', string | object>>` | -              |


# Chip

## Usage

Chip shares its color/variant/size system - and its default shape - with
[Badge](https://selarasui.my.id/components/elements/badge). The difference is `removable`, which
adds a dismiss button and a `remove` event. Chip doesn't track its own
value; the parent decides what "remove" means (splice it out of an array,
unset a filter, whatever fits).


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SChip label="Default" />
    <SChip label="Primary" color="primary" />
    <SChip label="Solid" color="primary" variant="solid" />
    <SChip label="Outline" color="danger" variant="outline" />
  </div>
</template>
```


```vue-html
<SChip label="Primary" color="primary" />
<SChip label="Solid" color="primary" variant="solid" />
<SChip label="Outline" color="danger" variant="outline" />
```

### Removable

`removable` adds a dismiss button; listen for `@remove` to react to it.


```vue
<script setup lang="ts">
const fruits = ref(['Apple', 'Banana', 'Cherry'])

function remove(fruit: string) {
  fruits.value = fruits.value.filter(f => f !== fruit)
}
</script>

<template>
  <div class="flex flex-wrap items-center gap-2">
    <SChip
      v-for="fruit in fruits"
      :key="fruit"
      :label="fruit"
      color="primary"
      removable
      @remove="remove(fruit)"
    />
    <span v-if="!fruits.length" class="text-sm text-[var(--selaras-resolved-text-muted)]">All cleared</span>
  </div>
</template>
```


```vue-html
<SChip
  v-for="fruit in fruits"
  :key="fruit"
  :label="fruit"
  removable
  @remove="fruits = fruits.filter((f) => f !== fruit)"
/>
```

### Icon

`icon` adds a leading icon, and combines with `removable` freely - the
matching `icon` slot replaces the glyph entirely when a plain icon name
isn't enough.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SChip label="Verified" icon="hugeicons:tick-02" color="success" />
    <SChip label="Starred" icon="hugeicons:star" color="warning" removable />
  </div>
</template>
```


```vue-html
<SChip label="Verified" icon="hugeicons:tick-02" color="success" />
<SChip label="Starred" icon="hugeicons:star" color="warning" removable />
```

### Rounded

`rounded` swaps the default small radius for a fully rounded pill shape.


```vue
<template>
  <div class="flex flex-wrap items-center gap-3">
    <SChip label="Primary" color="primary" rounded />
    <SChip label="Removable" removable rounded @remove="() => {}" />
  </div>
</template>
```


```vue-html
<SChip label="Primary" color="primary" rounded />
<SChip label="Removable" removable rounded @remove="() => {}" />
```

### Accessibility

The remove button is icon-only, so it needs an accessible name from
somewhere: by default it's derived as `Remove {label}` (or plain `Remove`
without a `label`) - override it directly with `removeLabel` when the
default slot's content isn't plain text `label` can describe.

Chip's own root is a `<span>`, so the remove button renders as a real
`<button>` inside it - nothing unusual to work around there, unlike a
control that has to live inside another interactive element.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Chip`'s own theme file:

:theme-source{name="chip"}

## Props

| Prop          | Type                                                                              | Default     |
| ------------- | --------------------------------------------------------------------------------- | ----------- |
| `label`       | `string`                                                                          | -           |
| `icon`        | `string`                                                                          | -           |
| `removable`   | `boolean`                                                                         | `false`     |
| `removeLabel` | `string`                                                                          | -           |
| `disabled`    | `boolean`                                                                         | `false`     |
| `rounded`     | `boolean`                                                                         | `false`     |
| `color`       | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'neutral'` |
| `variant`     | `'solid' | 'soft' | 'outline'`                                                    | `'soft'`    |
| `size`        | `'sm' | 'md' | 'lg'`                                                              | `'md'`      |
| `ui`          | `Partial<Record<ChipSlot, string | object>>`                                      | -           |

## Slots

| Slot          | Props        | Description                                                                                                                                                                                                                 |
| ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| default       | -            | Custom content, overrides `label`                                                                                                                                                                                           |
| `icon`        | -            | Replaces the leading icon entirely                                                                                                                                                                                          |
| `remove`      | `{ remove }` | Replaces the whole remove control (not just its icon) - needed when a host context must supply its own interactive element there. Call the scoped `remove` function to fire the same `remove` event the default button does |
| `remove-icon` | -            | Replaces the remove button's icon (default: `hugeicons:cancel-01`)                                                                                                                                                          |

## Emits

| Event    | Payload | Description                             |
| -------- | ------- | --------------------------------------- |
| `remove` | -       | Fired when the remove button is clicked |


# Icon

## Usage

Every icon-accepting prop across this library (`Button`'s `icon`, `Input`'s
`icon`, `Select`'s slots, ...) already renders through `SIcon` internally -
each one just supplies its own precise size class (`size-3.5`, `size-4.5`,
...) via `class`, the same way you would. `SIcon` doesn't have an opinion on
size at all; it's a bare pass-through to Nuxt Icon plus one optional
convenience prop for semantic color.


```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <SIcon name="hugeicons:star" class="size-4" />
    <SIcon name="hugeicons:star" class="size-5" />
    <SIcon name="hugeicons:star" class="size-6" />
    <SIcon name="hugeicons:favourite" color="danger" />
    <SIcon name="hugeicons:checkmark-circle-01" color="success" />
    <SIcon name="hugeicons:information-circle" color="info" />
  </div>
</template>
```


```vue-html
<SIcon name="hugeicons:star" class="size-4" />
<SIcon name="hugeicons:star" class="size-5" />
<SIcon name="hugeicons:star" class="size-6" />
<SIcon name="hugeicons:favourite" color="danger" />
```

`name` accepts any registered icon name, not just the `hugeicons:*` set
used throughout this library's own docs.

### Sizes

There's no `size` prop - pass whatever Tailwind size class you need via
`class` directly, same as any other icon usage. This library's own
components each pick their own scale internally (Badge's icons run
`size-2.5`/`size-3`/`size-3.5`, Button's `size-4`/`size-4.5`/`size-5`, and so
on) - none of those map cleanly onto one shared enum, so `SIcon` doesn't try
to impose one.

### Color

`color` is unset by default, so the icon inherits `currentColor` from
whatever text color surrounds it - the same behavior every internal icon
usage in this library already relies on (an input's leading icon takes
`--selaras-resolved-text-muted` from its wrapper, not a color prop of its own). Pass a
registered semantic role to force a specific color instead:

```vue-html
<SIcon name="hugeicons:checkmark-circle-01" color="success" />
```

A plain `class="text-[var(--selaras-resolved-color-danger-text)]"` still overrides `color` if you need
something the preset roles don't cover - both flow through the same
tailwind-merge, so whichever `text-*` class you add wins.

### Overriding the default icon set

`SIcon` itself only ever renders whatever `name` it's given - it has no
default of its own. But every icon a component renders *on its own*
(a button's loading spinner, a chip's remove glyph, a select's dropdown
chevron, ...) resolves from a separate semantic-purpose registry instead
of a hardcoded name - see [`useIcons`](https://selarasui.my.id/utilities/composables/use-icons)
for the full registry and how to override it globally in `app.config.ts`.

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-icon{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally). `Icon` has no body content, but the block
still needs its own closing line:

```md
::s-icon{name="hugeicons:star" color="warning"}
::
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.icon`. This is deliberately a
shared primitive hook: it affects direct `<SIcon>` instances and icons rendered
inside other Selaras components. The owning component's icon slot is merged
later, so its size and other conflicting Tailwind classes remain more specific.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Icon`'s own theme file:

:theme-source{name="icon"}

## Props

| Prop    | Type                                                                              | Default |
| ------- | --------------------------------------------------------------------------------- | ------- |
| `name`  | `string`                                                                          | -       |
| `color` | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | -       |
| `ui`    | `Partial<Record<'base', string | object>>`                                        | -       |


# Kbd

## Usage

`value` resolves a small set of common key names to their symbol -
anything else (a letter, a digit) renders as-is:


```vue
<template>
  <div class="flex items-center gap-1">
    <SKbd value="meta" />
    <SKbd>K</SKbd>
  </div>
</template>
```


```vue-html
<SKbd value="meta" /><SKbd>K</SKbd>
```

### Keys

Every built-in symbol `value` resolves:


```vue
<script setup lang="ts">
const keys = ['meta', 'shift', 'alt', 'ctrl', 'enter', 'backspace', 'escape', 'up', 'down', 'left', 'right']
</script>

<template>
  <div class="flex flex-wrap gap-2">
    <SKbd v-for="key in keys" :key="key" :value="key" />
  </div>
</template>
```


`meta`/`command`/`cmd` → ⌘, `ctrl`/`control` → ⌃, `alt`/`option` → ⌥,
`shift` → ⇧, `enter`/`return` → ↵, `backspace` → ⌫, `delete` → ⌦,
`tab` → ⇥, `capslock` → ⇪, `escape`/`esc` → Esc, `up`/`down`/`left`/`right`
→ ↑/↓/←/→, `space` → Space. Anything else - a bare `K`, a digit - is
kept as the literal string, so `value` also works as a plain shorthand
for the default slot.

### Sizes


```vue
<template>
  <div class="flex items-center gap-2">
    <SKbd size="sm" value="meta" />
    <SKbd size="md" value="meta" />
    <SKbd size="lg" value="meta" />
  </div>
</template>
```


```vue-html
<SKbd size="sm" value="meta" />
<SKbd size="md" value="meta" />
<SKbd size="lg" value="meta" />
```

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-kbd{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally):

```md
::s-kbd{value="meta"}
::
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Kbd`'s own theme file:

:theme-source{name="kbd"}

Global and scoped theme recipes use `ui.kbd`.

## Props

| Prop    | Type                                       | Default |
| ------- | ------------------------------------------ | ------- |
| `value` | `string`                                   | -       |
| `size`  | `'sm' | 'md' | 'lg'`                       | `'md'`  |
| `ui`    | `Partial<Record<'base', string | object>>` | -       |

## Slots

| Slot      | Props | Description                                                           |
| --------- | ----- | --------------------------------------------------------------------- |
| `default` | -     | Overrides `value` entirely - a pre-assembled combo, an icon, anything |


# Progress

## Usage


```vue
<script setup lang="ts">
const value = ref(40)
</script>

<template>
  <div class="flex w-64 flex-col gap-3">
    <SProgress :model-value="value" />
    <div class="flex items-center gap-2">
      <SButton size="sm" variant="outline" @click="value = Math.max(0, value - 10)">
        -10
      </SButton>
      <SButton size="sm" variant="outline" @click="value = Math.min(100, value + 10)">
        +10
      </SButton>
    </div>
  </div>
</template>
```


```vue-html
<SProgress :model-value="40" />
```

### Indeterminate

Omit `modelValue` (or set it `null`) for a busy indicator with no known
completion percentage - the bar slides continuously instead of
tracking a width:


```vue
<template>
  <div class="w-64">
    <SProgress />
  </div>
</template>
```


```vue-html
<SProgress />
```

### Color


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex w-64 flex-col gap-3">
    <SProgress v-for="color in colors" :key="color" :model-value="65" :color="color" />
  </div>
</template>
```


```vue-html
<SProgress :model-value="65" color="success" />
```

### Circular

`type="circular"` draws a ring instead of a bar - the default slot, if
given, centers inside it (there's no room to overlay text on an 8px
bar, so `linear` doesn't get this treatment):


```vue
<template>
  <div class="flex items-center gap-6">
    <SProgress type="circular" :model-value="70">
      <template #default="{ percent }">
        {{ Math.round(percent ?? 0) }}%
      </template>
    </SProgress>
    <SProgress type="circular" />
  </div>
</template>
```


```vue-html
<SProgress type="circular" :model-value="70">
  <template #default="{ percent }">{{ Math.round(percent) }}%</template>
</SProgress>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Progress`'s own theme file:

:theme-source{name="progress"}

Global and scoped theme recipes use `ui.progress`.

## Props

| Prop         | Type                                                                              | Default     |
| ------------ | --------------------------------------------------------------------------------- | ----------- |
| `modelValue` | `number | null`                                                                   | -           |
| `max`        | `number`                                                                          | `100`       |
| `type`       | `'linear' | 'circular'`                                                           | `'linear'`  |
| `size`       | `'sm' | 'md' | 'lg'`                                                              | `'md'`      |
| `color`      | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'primary'` |
| `ui`         | `Partial<Record<ProgressSlot, string | object>>`                                  | -           |

## Slots

| Slot      | Props         | Description                                             |
| --------- | ------------- | ------------------------------------------------------- |
| `default` | `{ percent }` | Label content - centered inside the ring for `circular` |


# Separator

## Usage


```vue
<template>
  <div class="flex w-full flex-col gap-4">
    <p class="text-sm text-[var(--selaras-resolved-text-default)]">
      Above the line
    </p>
    <SSeparator />
    <p class="text-sm text-[var(--selaras-resolved-text-default)]">
      Below the line
    </p>
  </div>
</template>
```


```vue-html
<p>Above the line</p>
<SSeparator />
<p>Below the line</p>
```

### Vertical

`orientation="vertical"` needs a real height to size against - a flex
row with a fixed height (or `items-stretch`) gives it one:


```vue
<template>
  <div class="flex h-5 items-center gap-3">
    <span class="text-sm text-[var(--selaras-resolved-text-default)]">Docs</span>
    <SSeparator orientation="vertical" />
    <span class="text-sm text-[var(--selaras-resolved-text-default)]">Utilities</span>
    <SSeparator orientation="vertical" />
    <span class="text-sm text-[var(--selaras-resolved-text-default)]">Components</span>
  </div>
</template>
```


```vue-html
<div class="flex h-5 items-center gap-3">
  <span>Docs</span>
  <SSeparator orientation="vertical" />
  <span>Utilities</span>
</div>
```

### Variant

`variant` switches the line style between `solid` (default), `dashed`,
`dotted`, and `double` - matching CSS's own `border-style` keywords,
since that's what each one maps to under the hood:


```vue
<script setup lang="ts">
const variants = ['solid', 'dashed', 'dotted', 'double'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <SSeparator v-for="variant in variants" :key="variant" :variant="variant" />
  </div>
</template>
```


```vue-html
<SSeparator variant="dashed" />
```

### Color

Unlike most components in this library, `color` isn't gated behind a
focus/hover state - the line is always visible, so it tints directly.
`neutral` (default) is the same subtle border color this component
always used; the rest give a divider real emphasis:


```vue
<script setup lang="ts">
const colors = ['neutral', 'primary', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <SSeparator v-for="color in colors" :key="color" :color="color" />
  </div>
</template>
```


```vue-html
<SSeparator color="danger" />
```

### With a label

Content in the default slot centers in the line, splitting it evenly on
both sides:


```vue
<template>
  <div class="flex w-full max-w-xs flex-col gap-4">
    <SButton block>
      Sign in with email
    </SButton>
    <SSeparator>Or continue with</SSeparator>
    <SButton variant="outline" color="neutral" block>
      Sign in with Google
    </SButton>
  </div>
</template>
```


```vue-html
<SSeparator>Or continue with</SSeparator>
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.separator`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Separator`'s own theme file:

:theme-source{name="separator"}

## Props

| Prop          | Type                                                                              | Default      |
| ------------- | --------------------------------------------------------------------------------- | ------------ |
| `orientation` | `'horizontal' | 'vertical'`                                                       | `horizontal` |
| `variant`     | `'solid' | 'dashed' | 'dotted' | 'double'`                                        | `solid`      |
| `color`       | `'neutral' | 'primary' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `neutral`    |
| `decorative`  | `boolean`                                                                         | `false`      |
| `ui`          | `Partial<Record<'root' | 'line' | 'label', string | object>>`                     | -            |

`decorative` renders `role="none"` instead of the default
`role="separator"` - use it when the line is purely visual (inside a
toolbar, say) rather than marking a real thematic break in content.

## Slots

| Slot      | Props | Description                  |
| --------- | ----- | ---------------------------- |
| `default` | -     | A label centered in the line |


# Skeleton

## Usage

`Skeleton` has no shape prop of its own - a text line, a circular avatar,
a rectangular block are all just different `class`/`:ui` sizing, the same
way sizing works everywhere else in this library:


```vue
<template>
  <div class="flex w-full flex-col gap-2">
    <SSkeleton class="h-4 w-full" />
    <SSkeleton class="h-4 w-full" />
    <SSkeleton class="h-4 w-2/3" />
  </div>
</template>
```


```vue-html
<SSkeleton class="h-4 w-full" />
<SSkeleton class="h-4 w-full" />
<SSkeleton class="h-4 w-2/3" />
```

### Animation

`animation` picks between `pulse` (default - a fading opacity) and
`shimmer` (a gradient sweeping across the block):


```vue
<template>
  <div class="flex w-full flex-col gap-2">
    <SSkeleton animation="shimmer" class="h-4 w-full" />
    <SSkeleton animation="shimmer" class="h-4 w-full" />
    <SSkeleton animation="shimmer" class="h-4 w-2/3" />
  </div>
</template>
```


```vue-html
<SSkeleton animation="shimmer" class="h-4 w-full" />
```

Both respect `prefers-reduced-motion` automatically - there's nothing to
opt into or configure.

### Composing a placeholder

A circular avatar next to a couple of text lines - `rounded-full` on a
square block gives the circle, everything else is layout:


```vue
<template>
  <div class="flex w-full items-center gap-3">
    <SSkeleton class="size-10 shrink-0 rounded-full" />
    <div class="flex flex-1 flex-col gap-2">
      <SSkeleton class="h-3 w-32" />
      <SSkeleton class="h-3 w-48" />
    </div>
  </div>
</template>
```


```vue-html
<div class="flex items-center gap-3">
  <SSkeleton class="size-10 rounded-full" />
  <div class="flex flex-col gap-2">
    <SSkeleton class="h-3 w-32" />
    <SSkeleton class="h-3 w-48" />
  </div>
</div>
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.skeleton`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Skeleton`'s own theme file:

:theme-source{name="skeleton"}

## Props

| Prop        | Type                                       | Default |
| ----------- | ------------------------------------------ | ------- |
| `animation` | `'pulse' | 'shimmer'`                      | `pulse` |
| `ui`        | `Partial<Record<'base', string | object>>` | -       |


# Toggle

## Usage


```vue
<template>
  <SToggle icon="hugeicons:text-bold">
    Bold
  </SToggle>
</template>
```


```vue-html
<SToggle icon="hugeicons:text-bold">Bold</SToggle>
```

### Icon only

Same auto-detection as `Button` - pass `icon` with no default slot
content and it shapes itself to a square automatically. Always add
`aria-label` when there's no visible text:


```vue
<template>
  <div class="flex gap-2">
    <SToggle icon="hugeicons:text-bold" aria-label="Bold" />
    <SToggle icon="hugeicons:text-italic" aria-label="Italic" />
    <SToggle icon="hugeicons:text-underline" aria-label="Underline" />
  </div>
</template>
```


```vue-html
<SToggle icon="hugeicons:text-bold" aria-label="Bold" />
```

### Color

`color` picks which of the seven semantic colors the pressed state
uses - unpressed always looks the same (muted, transparent) regardless
of `color`:


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex flex-wrap gap-2">
    <SToggle v-for="color in colors" :key="color" :color="color" default-value>
      {{ color }}
    </SToggle>
  </div>
</template>
```


```vue-html
<SToggle color="success" default-value>Enabled</SToggle>
```

### Disabled


```vue
<template>
  <div class="flex gap-2">
    <SToggle disabled>
      Off
    </SToggle>
    <SToggle disabled default-value>
      On
    </SToggle>
  </div>
</template>
```


```vue-html
<SToggle disabled>Off</SToggle>
<SToggle disabled default-value>On</SToggle>
```

### Multiple toggles

For a set of related toggles that share one selection model (single or
multiple), see [ToggleGroup](https://selarasui.my.id/components/elements/toggle-group) -
`Toggle` on its own has no relationship to any other `Toggle`.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Toggle`'s own theme file:

:theme-source{name="toggle"}

## Props

| Prop           | Type                                                                              | Default     |
| -------------- | --------------------------------------------------------------------------------- | ----------- |
| `modelValue`   | `boolean`                                                                         | -           |
| `defaultValue` | `boolean`                                                                         | `false`     |
| `disabled`     | `boolean`                                                                         | -           |
| `icon`         | `string`                                                                          | -           |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'primary'` |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `'md'`      |
| `square`       | `boolean`                                                                         | -           |
| `ui`           | `Partial<Record<ToggleSlot, string | object>>`                                    | -           |

## Emits

| Event               | Payload   |
| ------------------- | --------- |
| `update:modelValue` | `boolean` |

## Slots

| Slot      | Props         | Description              |
| --------- | ------------- | ------------------------ |
| `default` | `{ pressed }` | The toggle's own content |


# Toggle Group

## Usage

Joined into one segmented control, same visual technique as
[ButtonGroup](https://selarasui.my.id/components/elements/button-group). `type="single"`
(the default) behaves like a segmented radio group - selecting one
item deselects the rest:


```vue
<template>
  <SToggleGroup :items="['List', 'Grid', 'Kanban']" default-value="List" />
</template>
```


```vue-html
<SToggleGroup :items="['List', 'Grid', 'Kanban']" default-value="List" />
```

### Multiple selection

`type="multiple"` lets any number of items stay pressed at once -
`modelValue`/`defaultValue` become an array instead of a single value:


```vue
<script setup lang="ts">
const items = [
  { label: 'Bold', value: 'bold', icon: 'hugeicons:text-bold' },
  { label: 'Italic', value: 'italic', icon: 'hugeicons:text-italic' },
  { label: 'Underline', value: 'underline', icon: 'hugeicons:text-underline' },
]
</script>

<template>
  <SToggleGroup type="multiple" :items="items" :default-value="['bold']" />
</template>
```


```vue-html
<SToggleGroup type="multiple" :items="items" :default-value="['bold']" />
```

### Icon only

The `item` slot replaces an item's default icon+label content
entirely - pair it with a visually-hidden label so the item still has
an accessible name:


```vue
<script setup lang="ts">
const items = [
  { label: 'List view', value: 'list', icon: 'hugeicons:list-view' },
  { label: 'Grid view', value: 'grid', icon: 'hugeicons:grid-view' },
]
</script>

<template>
  <SToggleGroup :items="items" default-value="list">
    <template #item="{ item }">
      <SIcon :name="item.icon!" class="size-4.5" />
      <span class="sr-only">{{ item.label }}</span>
    </template>
  </SToggleGroup>
</template>
```


```vue-html
<SToggleGroup :items="items" default-value="list">
  <template #item="{ item }">
    <SIcon :name="item.icon" class="size-4.5" />
    <span class="sr-only">{{ item.label }}</span>
  </template>
</SToggleGroup>
```

### Orientation


```vue
<template>
  <SToggleGroup orientation="vertical" :items="['List', 'Grid', 'Kanban']" default-value="List" />
</template>
```


```vue-html
<SToggleGroup orientation="vertical" :items="['List', 'Grid', 'Kanban']" />
```

### Disabled

`disabled` on the group blocks every item; `disabled` on one item
blocks only that item:


```vue
<script setup lang="ts">
const items = [
  { label: 'List', value: 'list' },
  { label: 'Grid', value: 'grid', disabled: true },
  { label: 'Kanban', value: 'kanban' },
]
</script>

<template>
  <SToggleGroup :items="items" default-value="list" />
</template>
```


```vue-html
<SToggleGroup :items="[
  { label: 'List', value: 'list' },
  { label: 'Grid', value: 'grid', disabled: true },
]" />
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `ToggleGroup`'s own theme file:

:theme-source{name="toggle-group"}

## Props

| Prop           | Type                                                                              | Default        |
| -------------- | --------------------------------------------------------------------------------- | -------------- |
| `items`        | `(string | ToggleGroupItem)[]`                                                    | -              |
| `type`         | `'single' | 'multiple'`                                                           | `'single'`     |
| `modelValue`   | `string | string[]`                                                               | -              |
| `defaultValue` | `string | string[]`                                                               | -              |
| `disabled`     | `boolean`                                                                         | -              |
| `orientation`  | `'horizontal' | 'vertical'`                                                       | `'horizontal'` |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'primary'`    |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `'md'`         |
| `ui`           | `Partial<Record<ToggleGroupSlot, string | object>>`                               | -              |

`ToggleGroupItem` is `{ label: string, value: string, icon?: string, disabled?: boolean }`.

## Emits

| Event               | Payload             |
| ------------------- | ------------------- |
| `update:modelValue` | `string | string[]` |

## Slots

| Slot   | Props               | Description                                   |
| ------ | ------------------- | --------------------------------------------- |
| `item` | `{ item, pressed }` | Replaces an item's default icon+label content |


# Autocomplete

## Usage

Suggestions accept string/number arrays or option objects. A primitive is both
its label and value. Objects display `label` by default; their `value` field is
used when present, and objects without it are themselves the model value. Set
`labelKey` or `valueKey` to choose other fields. Existing suggestions preserve
numeric `1` versus string `"1"`. Newly created free text is always a string;
numeric suggestions do not cause typed text to be coerced. Use `forceSelection`
to disallow creating values.

Autocomplete infers models and update events from its suggestion identity field.
Numeric suggestions allow `number | string | undefined` in single mode and
`(number | string)[]` in multiple mode. A literal `forceSelection` narrows those
types to the suggestion identity; a dynamic boolean retains the string union.
Readonly option/group arrays and custom top-level `valueKey`/`labelKey` fields
are supported. Every suggestion identity must be unique across the whole list,
including disabled suggestions and suggestions in different groups; a duplicate
throws when Autocomplete reads the options. Numeric `1` and string `'1'` remain
distinct. Declare the item type for initially empty async arrays.

The exported types use an option entry type: `AutocompleteProps<number>`
describes numeric primitive items, while
`AutocompleteProps<{ value: number, label: string }>` describes option records.
The parameters are entry, identity key, multiple mode and forced mode.

Author suggestions as a readonly `Row[]`, or as `readonly (Row | SelectGroup<Row>)[]`
when mixing suggestions and groups; there are no separate `SelectItems`,
`SelectOption`, or `SelectOptionGroup` authoring aliases. A wrapper that needs
the exact validated items type can use `AutocompleteProps<Row, 'id'>['items']`. For example,
`AutocompleteProps<Row, 'id', true, true>` describes forced multiple selection.
`AutocompleteEmits` uses the same parameters. Render functions can specialize
`Autocomplete<Row, 'id', true, true>` directly; templates normally infer it.
Import public helpers from `@sewadah/selaras/types`; derive slot types through
`AutocompleteSlots`.

`forceSelection` blocks new unmatched text. It does not erase existing values
when toggled dynamically or require that a selected async identity already be
in the current options. Native reset restores the captured default, including
strings created before a dynamic switch. Idle inputs refresh their selected
label when options load; active queries and parent-controlled `searchTerm`
retain their text.

`defaultValue` initializes uncontrolled selection and is the native form reset
target. `modelValue` remains parent-controlled. With `name`, each selected value
submits as a field; primitives are strings and objects are JSON. Empty or
disabled selections submit none. `form` may reference an external form ID.

Unlike [Select](https://selarasui.my.id/components/forms/select), whatever the user types can become the
value even if it doesn't match a suggestion - picking a suggestion is a
shortcut, not a requirement.


```vue
<script setup lang="ts">
const value = ref('')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
]
</script>

<template>
  <SAutocomplete v-model="value" placeholder="Type anything" :items="fruitItems" />
</template>
```


```vue
<script setup lang="ts">
const value = ref('')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
]
</script>

<template>
  <SAutocomplete v-model="value" placeholder="Type anything" :items="fruitItems" />
</template>
```

The input itself is always the trigger - typing works immediately, with no
separate "open" step, since there's no equivalent of Select's
`searchable: false` mode here.

### Dropdown

There's no built-in "browse everything" button by default - typing is the
whole interaction. `dropdown` adds one anyway: a trailing chevron that opens
the popover and clears whatever's typed, so it always shows the full list
rather than staying scoped to the current filter.


```vue
<script setup lang="ts">
const value = ref('')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SAutocomplete v-model="value" dropdown placeholder="Type or browse" :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="value" dropdown placeholder="Type or browse" :items="fruitItems" />
```

### Multiple values

`multiple` uses a comma-separated display by default, with the editable query
beside the selected labels. `displayMode="chip"` shows removable chips instead.
Both modes offer a Create option for text that isn't already in `items`. Press
Enter to add it, or move to an existing suggestion first. Once the query
clears, the open list shows all available options again. Choosing an already
selected option leaves the selection in place; chip mode also offers a remove
button on each selected value. In comma mode, press Backspace with an empty
query to remove the last selected value.


```vue
<script setup lang="ts">
const fruits = ref<string[]>(['apple', 'banana'])

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SAutocomplete v-model="fruits" multiple :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="fruits" multiple :items="fruitItems" />
```


```vue
<script setup lang="ts">
const tags = ref<string[]>(['apple'])

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SAutocomplete v-model="tags" multiple display-mode="chip" :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="tags" multiple display-mode="chip" :items="fruitItems" />
```

### Changing selection mode

For an uncontrolled Autocomplete, changing `multiple` converts its local
selection once: single `value` becomes `[value]`, single `undefined` becomes
`[]`, a multiple selection becomes its first value, and an empty array becomes
`undefined`. Switching to single mode drops later active selections. That
conversion emits one `update:modelValue` event. The captured
`defaultValue` does not change after mount; reset projects it into the current
mode. For example, `defaultValue: [0, 1]` resets to `0` in single mode and to
`[0, 1]` after changing back to multiple mode.

A controlled parent must change `modelValue` and `multiple` in the same render:
an array when `multiple` is true, and a scalar or `undefined` when it is false.
`undefined` is allowed as the empty multiple value. A scalar value in
multiple mode, or any array in single mode, throws a descriptive error.
Each value in a multiple `modelValue` or `defaultValue` array must also be
unique, including created or unresolved async identities. Numeric `1` and
string `'1'` are distinct values.
Autocomplete does not convert controlled values or emit an update solely
because the mode changed. Changing modes also preserves an active query, open
popover, and focus when the input was focused. It does not take focus from a
mode button or another control. A parent-controlled `searchTerm` retains its
text; idle input labels follow `resetSearchTermOnSelect`.
Changing mode during IME composition cancels editing and requests that the
query and popup be cleared. Complete composition before changing mode to retain
the query.

### Clear

`clearable` works the same as [Select's](https://selarasui.my.id/components/forms/select#clear) - a
button that resets the selection once there's something to clear. Clearing
also blanks the displayed text back to the placeholder, the same way picking
a suggestion fills it in.


```vue
<script setup lang="ts">
const value = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
]
</script>

<template>
  <SAutocomplete v-model="value" clearable placeholder="Type anything" :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="value" clearable placeholder="Type anything" :items="fruitItems" />
```

### Force selection

This is the one real behavioral difference from Select, not just a shared
prop: `forceSelection` reverts typed text that doesn't match any option back
to blank on blur or Enter, instead of accepting it as a new value. It exists
for consumers who want Autocomplete's UX (input-as-trigger, inline filtering)
without actually allowing arbitrary values - if that's the goal from the
start, [Select](https://selarasui.my.id/components/forms/select) does the same job more directly.

In multiple mode, typing `bana` shows &#x2A;*Create "bana"** before the matching
**Banana** suggestion. :kbd[Enter] chooses the active option, so you can
create `bana` immediately or press :kbd[ArrowDown] then :kbd[Enter]
to select `Banana`. Clicking either option works too. In single mode, the list
shows matching suggestions without a Create row: Enter selects the active
suggestion, while unmatched text is accepted as free text on Enter or blur.
When no suggestions match in single mode, the popup hides. :kbd[Tab] moves
focus normally. `forceSelection` hides the Create option and rejects unmatched
text. An idle :kbd[Enter] does not remove an existing chip and can submit
a parent form normally.


```vue
<script setup lang="ts">
const value = ref('')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
]
</script>

<template>
  <SAutocomplete v-model="value" force-selection placeholder="Try typing something not in the list" :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="value" force-selection :items="fruitItems" />
```

### Arrow

`arrow` works the same as [Select's](https://selarasui.my.id/components/forms/select#arrow): use
`true` for the default pointer or an object to configure its size, rounded tip,
and corner clearance.


```vue
<script setup lang="ts">
const value = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
]
</script>

<template>
  <SAutocomplete v-model="value" arrow placeholder="Type anything" :items="fruitItems" />
</template>
```


```vue-html
<SAutocomplete v-model="value" arrow :items="fruitItems" />
<SAutocomplete v-model="value" :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }" :items="fruitItems" />
```

### Custom option rendering, objects, and groups

The `item`/`group` slots and `labelKey`/`valueKey` mapping all work
identically to Select's - see
[Custom option rendering](https://selarasui.my.id/components/forms/select#custom-option-rendering),
[Custom objects](https://selarasui.my.id/components/forms/select#custom-objects), and
[Grouped options](https://selarasui.my.id/components/forms/select#grouped-options).

Created text and async selections can be absent from `items`. Their chips use
the selected text until a complete option exists; the `item` slot receives only
real option records. Autocomplete's selection display is its editable input;
it has no `value` slot.

### Virtualization

Also identical to [Select's](https://selarasui.my.id/components/forms/select#virtualization) -
`virtualize` renders only the visible rows, grouped `items` flatten while
virtualized, and it windows what's already in `items` rather than
lazy-loading more of it.

### Search text

Since the input here IS the trigger, its text doubles as both the filter and
the display of the current value: single-select shows the picked option's
label after you choose one, multi-select clears after each commit (the chips
show the selection instead). Same `v-model:search-term` and
`resetSearchTermOnBlur`/`resetSearchTermOnSelect` escape hatches as
[Select](https://selarasui.my.id/components/forms/select#search-text) apply here too.

### Sizes and states

`size`, `loading`, `disabled`, `invalid`, and `color` all behave the same as
[Select's](https://selarasui.my.id/components/forms/select#sizes) - see the [Props](https://selarasui.my.id/#props) table
below.

### Adaptive presentation

`adaptive` uses the same breakpoint and open-time latch as
[Select](https://selarasui.my.id/components/forms/select#adaptive-presentation). On small screens, the
field opens a modal containing an input and suggestions. Single selection closes
the modal; multiple selection and free-text entry also provide a Done button.
The modal shares the field’s query and selection and restores focus when closed:


```vue
<script setup lang="ts">
const value = ref('')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SAutocomplete v-model="value" adaptive placeholder="Type or choose a fruit" :items="fruitItems" />
</template>
```


### Forms integration

Also the same as [Select's](https://selarasui.my.id/components/forms/select#forms-integration) -
wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) for `id`/`name`/`invalid`
and `aria-describedby` wired up automatically.

### Accessibility

Autocomplete renders the same Reka UI Combobox primitive as
[Select](https://selarasui.my.id/components/forms/select#accessibility), so the same ARIA combobox
semantics apply - `role="combobox"` with `aria-expanded`/`aria-controls` on
the input, `role="option"` per suggestion, arrow keys to move the highlight,
:kbd[Enter] to select. The one addition here is `aria-autocomplete="list"`,
since (unlike Select) the trigger is a real editable text field with live
suggestions as you type.

### Custom `:ui`

Autocomplete renders the same internal combobox base as
[Select](https://selarasui.my.id/components/forms/select#custom-ui), so they share one theme file:

Global and scoped overrides use the `ui.select` key for both components.

:theme-source{name="select"}

### Custom leading and trailing content

Use `#leading` and `#trailing` for text, icons, or buttons inside the field frame.
The slots receive `{ disabled, size, buttonSize }`; `buttonSize` fits a Button
inside the current field size. Give interactive controls an accessible label,
use `type="button"`, and pass `disabled` through to match the field state.

Custom content stays visible alongside the built-in clear button, loading indicator, and dropdown control.
The field reserves space for the rendered content, including suffixes whose
width changes. Use `ui.leading` and `ui.trailing` to customize its wrappers.


```vue
<script setup lang="ts">
const city = ref('Bandung')
const details = ref(false)
</script>

<template>
  <div class="w-full max-w-sm space-y-2">
    <SAutocomplete v-model="city" :items="['Bandung', 'Jakarta', 'Surabaya']" clearable dropdown adaptive aria-label="City">
      <template #leading>
        <span class="text-xs">City</span>
      </template>
      <template #trailing="{ disabled, buttonSize }">
        <SButton type="button" :disabled="disabled" :size="buttonSize" variant="text" color="neutral" square icon="hugeicons:information-circle" aria-label="City details" :aria-pressed="details" @click="details = !details" />
      </template>
    </SAutocomplete>
    <p v-if="details" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Select a suggestion or enter another city.
    </p>
  </div>
</template>
```


Custom controls render outside the trigger button, so they can receive keyboard
focus without creating nested buttons or opening the options list on click.
With `adaptive`, these slots customize the original field; the modal retains
its dedicated search and selection controls.

## Props

Same as [Select](https://selarasui.my.id/components/forms/select#props), minus `searchable` (always
on), plus these Autocomplete-only additions:

`positioning` and `portal` follow [Select's anchored panel contract](https://selarasui.my.id/components/forms/select#panel-positioning-and-portal).

| Prop             | Type      | Default |
| ---------------- | --------- | ------- |
| `dropdown`       | `boolean` | `false` |
| `forceSelection` | `boolean` | `false` |

## Slots

Autocomplete supports `leading`, `trailing`, `item`, `group`, `header`, `footer`, `empty`,
`empty-filter`, `clear-icon`, `loading-icon` and `dropdown-icon`. Its input
displays the selected label directly. Select's `value` and `filter-icon` slots
are specific to Select's trigger display and separate filter field.

`leading` and `trailing` receive `{ disabled, size, buttonSize }`, as described above.


# Checkbox

## Usage


```vue
<script setup lang="ts">
const accepted = ref(true)
</script>

<template>
  <SCheckbox v-model="accepted" label="Accept terms" />
</template>
```


```vue
<script setup lang="ts">
const accepted = ref(true)
</script>

<template>
  <SCheckbox v-model="accepted" label="Accept terms" />
</template>
```

### States

`modelValue` also takes `'indeterminate'`, for a "select all" checkbox
whose children are only partially selected - it renders a dash instead of
a checkmark and isn't a real toggle state a click can land on (clicking an
indeterminate checkbox goes straight to checked). `disabled` prevents
interaction and dims it, and `invalid` switches the ring and checked fill to
the semantic danger role:


```vue
<script setup lang="ts">
const indeterminate = ref<boolean | 'indeterminate'>('indeterminate')
const disabledChecked = ref(true)
const invalidChoice = ref(false)
</script>

<template>
  <div class="flex flex-col gap-4">
    <SCheckbox v-model="indeterminate" label="Select all" />
    <SCheckbox :model-value="false" disabled label="Disabled" />
    <SCheckbox v-model="disabledChecked" disabled label="Disabled, checked" />
    <SCheckbox v-model="invalidChoice" invalid label="You must accept to continue" />
  </div>
</template>
```


```vue-html
<SCheckbox v-model="indeterminate" label="Select all" />
<SCheckbox :model-value="false" disabled label="Disabled" />
<SCheckbox v-model="disabledChecked" disabled label="Disabled, checked" />
<SCheckbox v-model="invalidChoice" invalid label="You must accept to continue" />
```

See [Props](https://selarasui.my.id/#props).

### Sizes

`size` takes `sm` / `md` / `lg`, scaling the box, checkmark, and label
together:


```vue
<script setup lang="ts">
const sm = ref(true)
const md = ref(true)
const lg = ref(true)
</script>

<template>
  <div class="flex items-center gap-4">
    <SCheckbox v-model="sm" size="sm" label="Small" />
    <SCheckbox v-model="md" size="md" label="Medium" />
    <SCheckbox v-model="lg" size="lg" label="Large" />
  </div>
</template>
```


```vue-html
<SCheckbox v-model="sm" size="sm" label="Small" />
<SCheckbox v-model="md" size="md" label="Medium" />
<SCheckbox v-model="lg" size="lg" label="Large" />
```

### Colors

`color` sets the checked/indeterminate fill, ring, and checkmark color -
unchecked always stays the same neutral ring regardless:


```vue
<script setup lang="ts">
const primary = ref(true)
const success = ref(true)
const danger = ref(true)
</script>

<template>
  <div class="flex flex-col gap-4">
    <SCheckbox v-model="primary" color="primary" label="Primary" />
    <SCheckbox v-model="success" color="success" label="Success" />
    <SCheckbox v-model="danger" color="danger" label="Danger" />
  </div>
</template>
```


```vue-html
<SCheckbox v-model="primary" color="primary" label="Primary" />
<SCheckbox v-model="success" color="success" label="Success" />
<SCheckbox v-model="danger" color="danger" label="Danger" />
```

### Description

`description` adds a second, muted line under the label - for a
standalone checkbox (an "Accept terms" checkbox, say) where wrapping it in
its own [FormField](https://selarasui.my.id/components/forms/form-field) would be needless
ceremony:


```vue
<script setup lang="ts">
const accepted = ref(false)
</script>

<template>
  <SCheckbox
    v-model="accepted"
    label="Accept terms"
    description="You agree to our Terms of Service and Privacy Policy."
  />
</template>
```


```vue-html
<SCheckbox v-model="accepted" label="Accept terms" description="You agree to our Terms of Service and Privacy Policy." />
```

### Card style

`variant="card"` wraps the checkbox and label in a bordered box instead of
a plain inline row, highlighting it when checked - works the same with or
without `description`:


```vue
<script setup lang="ts">
const accepted = ref(false)
</script>

<template>
  <SCheckbox
    v-model="accepted"
    variant="card"
    label="Accept terms"
    description="You agree to our Terms of Service and Privacy Policy."
  />
</template>
```


```vue-html
<SCheckbox v-model="accepted" variant="card" label="Accept terms" description="You agree to our Terms of Service and Privacy Policy." />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` falls back to
FormField's own state when not set directly on the checkbox, and `size`
does the same (matching RadioGroup's/Switch's own inheritance).

### Accessibility

Checkbox renders Reka UI's Checkbox primitive, so the accessibility
semantics come from there rather than being reimplemented here: `role="checkbox"`
with `aria-checked` reflecting all three states (`true`/`false`, or `"mixed"`
for indeterminate). It's a single native-equivalent control, so it's just
one :kbd[Tab] stop with no roving focus to manage, and :kbd[Space]
toggles it - standard behavior for the
[ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/){rel="&#x22;nofollow&#x22;"},
not something to configure here.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Checkbox`'s own theme file:

:theme-source{name="checkbox"}

## Props

| Prop          | Type                                                                                                                                          | Default     |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `id`          | `string`                                                                                                                                      | -           |
| `name`        | `string`                                                                                                                                      | -           |
| `modelValue`  | `boolean | 'indeterminate'`                                                                                                                   | -           |
| `label`       | `string`                                                                                                                                      | -           |
| `description` | `string`                                                                                                                                      | -           |
| `disabled`    | `boolean`                                                                                                                                     | `false`     |
| `invalid`     | `boolean`                                                                                                                                     | `false`     |
| `required`    | `boolean`                                                                                                                                     | `false`     |
| `size`        | `'sm' | 'md' | 'lg'`                                                                                                                          | `'md'`      |
| `color`       | `ColorRole` (built-in or registered semantic role)                                                                                            | `'primary'` |
| `variant`     | `'default' | 'card'`                                                                                                                          | `'default'` |
| `ui`          | `Partial<Record<'root' | 'box' | 'indicator' | 'checkIcon' | 'indeterminateIcon' | 'label' | 'description' | 'labelGroup', string | object>>` | -           |

## Slots

| Slot          | Description                             |
| ------------- | --------------------------------------- |
| default       | Custom content, overrides `label`       |
| `description` | Custom content, overrides `description` |


# ColorPicker

## Usage

`v-model` is a hex color string (`#rrggbb`, or `#rrggbbaa` once alpha
drops below 1) - the trigger shows a live swatch preview plus the hex
value, and opens a popover with a saturation/brightness area, a hue
slider, an alpha slider, and a hex text field:


```vue
<script setup lang="ts">
const color = ref('#7c3aed')
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SColorPicker v-model="color" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ color }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const color = ref('#7c3aed')
</script>

<template>
  <SColorPicker v-model="color" />
</template>
```

### Alpha

`alpha` (default `true`) shows the opacity slider. Set it to `false`
for a consumer that only ever wants an opaque color:


```vue
<script setup lang="ts">
const color = ref('#22c55e')
</script>

<template>
  <SColorPicker v-model="color" :alpha="false" />
</template>
```


```vue-html
<SColorPicker v-model="color" :alpha="false" />
```

### Swatches

`swatches` renders a row of preset colors below the hex field - omitted
entirely unless given. Clicking one sets that exact color (including its
own alpha, if it has one):


```vue
<script setup lang="ts">
const color = ref('#ef4444')
const swatches = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#3b82f6', '#7c3aed', '#ec4899', '#000000']
</script>

<template>
  <SColorPicker v-model="color" :swatches="swatches" />
</template>
```


```vue-html
<SColorPicker v-model="color" :swatches="['#ef4444', '#f97316', '#eab308', '#22c55e', '#3b82f6']" />
```

### Color

Controls the trigger's own focus-ring color, same scope as every other
form control's `color` prop - it has no effect on the color being
picked:


```vue
<script setup lang="ts">
const color = ref('#f43f5e')
</script>

<template>
  <SColorPicker v-model="color" color="danger" />
</template>
```


```vue-html
<SColorPicker v-model="color" color="danger" />
```

### Size


```vue
<script setup lang="ts">
const color = ref('#0ea5e9')
</script>

<template>
  <div class="flex items-center gap-3">
    <SColorPicker v-model="color" size="sm" />
    <SColorPicker v-model="color" size="md" />
    <SColorPicker v-model="color" size="lg" />
  </div>
</template>
```


```vue-html
<SColorPicker v-model="color" size="sm" />
<SColorPicker v-model="color" size="md" />
<SColorPicker v-model="color" size="lg" />
```

### Adaptive presentation

Below your configured adaptive breakpoint, `adaptive` presents the popover as
a centered [Modal](https://selarasui.my.id/components/overlays/modal) instead of a small anchored
panel. It is opt-in (defaults `false`) and follows the shared adaptive
contract:


```vue
<script setup lang="ts">
const color = ref('#7c3aed')
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SColorPicker v-model="color" adaptive />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ color }}
    </p>
  </div>
</template>
```


### Arrow

`arrow` adds a pointer between the anchored picker and its trigger. It is off
by default and has no effect on the adaptive modal.

```vue-html
<SColorPicker v-model="color" arrow />
<SColorPicker v-model="color" :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }" />
```

Use `positioning` to place the anchored picker and `portal` to render it
inline (`false`) or teleport it to a CSS selector or `HTMLElement`. The
default portal target is the document body. These props apply to the anchored
popover, which starts aligned with its trigger by default; the adaptive modal
has its own layout. Set `positioning.align` to override the alignment.
`ui.content` styles the panel.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `ColorPicker`'s own theme file:

:theme-source{name="color-picker"}

## Props

| Prop           | Type                                                                              | Default                  |
| -------------- | --------------------------------------------------------------------------------- | ------------------------ |
| `name`         | `string`                                                                          | -                        |
| `form`         | `string`                                                                          | -                        |
| `modelValue`   | `string`                                                                          | -                        |
| `defaultValue` | `string`                                                                          | -                        |
| `open`         | `boolean`                                                                         | -                        |
| `defaultOpen`  | `boolean`                                                                         | `false`                  |
| `disabled`     | `boolean`                                                                         | `false`                  |
| `alpha`        | `boolean`                                                                         | `true`                   |
| `swatches`     | `string[]`                                                                        | -                        |
| `placeholder`  | `string`                                                                          | -                        |
| `adaptive`     | `boolean`                                                                         | `false`                  |
| `arrow`        | `boolean | RoundedArrowConfig`                                                    | `false`                  |
| `positioning`  | `OverlayPositioning`                                                              | anchored picker defaults |
| `portal`       | `boolean | string | HTMLElement`                                                  | `true` (document body)   |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `md`                     |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary`                |
| `ui`           | `Partial<Record<ColorPickerSlot, string | object>>`                               | -                        |

## Events

| Event               | Payload   | Description                                                                                                              |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `update:open`       | `boolean` | Fires when the picker requests opening or closing                                                                        |
| `update:modelValue` | `string`  | Fires whenever the color changes - dragging the area/sliders, typing (and committing) the hex field, or picking a swatch |


# DatePicker

## Usage

`v-model` is an `@internationalized/date` `DateValue` (typically a
`CalendarDate` for this component's date-only granularity), not a native
`Date` - the segmented field, calendar grid, `minValue`/`maxValue`, and
`isDateUnavailable` all share that same type, so there's no lossy
conversion at the boundary. It already has an ISO `.toString()`
(`2024-06-15`) and a matching `parseDate()` constructor if you need to
interop with a plain string, and `@internationalized/date`'s own `today()`/
`getLocalTimeZone()` cover the common "relative to now" cases:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

// shallowRef, not ref - DateValue instances carry real private class
// fields that a plain ref's type would strip, breaking assignability
// back into v-model. The value is always replaced wholesale anyway,
// never mutated in place.
const date = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="date" />
</template>
```


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

// shallowRef, not ref - DateValue instances carry real private class
// fields that a plain ref's type would strip, breaking assignability
// back into v-model. The value is always replaced wholesale anyway,
// never mutated in place.
const date = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="date" />
</template>
```

Click the calendar icon to open the popover, or type directly into the day/
month/year segments - both stay in sync with the same value.

### Min/max range

`min-value`/`max-value` disable every day outside the range (and block
selecting one, not just style it):


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { getLocalTimeZone, today } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
const now = today(getLocalTimeZone())
const min = now
const max = now.add({ days: 14 })
</script>

<template>
  <SDatePicker v-model="date" :min-value="min" :max-value="max" />
</template>
```


```vue-html
<SDatePicker v-model="date" :min-value="today(getLocalTimeZone())" :max-value="..." />
```

### Unavailable dates

`is-date-unavailable` takes a `(date: DateValue) => boolean` predicate. Unlike
`minValue`/`maxValue`, an unavailable day is still selectable - it's marked
(struck through, dimmed) rather than blocked, matching a constraint you want
to flag rather than hard-enforce (e.g. "no weekend deliveries" where the
consumer decides what happens next):


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { getLocalTimeZone, today } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
const now = today(getLocalTimeZone())

// Weekends unavailable - still selectable (isDateUnavailable only marks the
// day, it doesn't block clicking it), matching a "no weekend deliveries"
// style constraint where you'd validate the choice yourself afterward.
function isWeekend(value: DateValue) {
  const day = value.toDate(getLocalTimeZone()).getDay()
  return day === 0 || day === 6
}
</script>

<template>
  <SDatePicker v-model="date" :is-date-unavailable="isWeekend" :min-value="now" />
</template>
```


```vue-html
<SDatePicker v-model="date" :is-date-unavailable="(d) => isWeekend(d)" />
```

### Range selection

`range` switches to picking a start and end date together - `v-model`
becomes `{ start?: DateValue, end?: DateValue }` instead of a single
`DateValue`. Click a first day to set the start (the popover stays open -
the selection isn't finished yet), then a second day to complete the range
and close it. Defaults to showing two months side by side
(`number-of-months="2"`) rather than one, since that's what makes picking a
multi-week range comfortable - pass `:number-of-months="1"` to page through
a single month instead:


```vue
<script setup lang="ts">
import type { DateRange } from 'reka-ui'
import { shallowRef } from 'vue'

const range = shallowRef<DateRange>()
</script>

<template>
  <SDatePicker v-model="range" range />
</template>
```


```vue
<script setup lang="ts">
import type { DateRange } from 'reka-ui'
import { shallowRef } from 'vue'

const range = shallowRef<DateRange>()
</script>

<template>
  <SDatePicker v-model="range" range />
</template>
```

`allow-non-contiguous-ranges`, `fixed-date` (`'start' | 'end'`, locks one
end in place while re-picking the other), `maximum-days` (caps how far
apart start/end can be), and `is-date-highlightable` are all range-only
passthroughs to the underlying primitive.

`trigger-mode="button"` combines with `range` too - the button's text uses
`DateFormatter.formatRange()` (e.g. "Jun 15 – Jun 20, 2024") instead of a
single formatted date:


```vue
<script setup lang="ts">
import type { DateRange } from 'reka-ui'
import { shallowRef } from 'vue'

const range = shallowRef<DateRange>()
</script>

<template>
  <SDatePicker v-model="range" range trigger-mode="button" />
</template>
```


```vue-html
<SDatePicker v-model="range" range trigger-mode="button" />
```

### Button trigger

`trigger-mode="button"` replaces the typeable segments with a single button
showing the formatted date (or a placeholder message when empty) - a
plainer "click to open" trigger for when the segmented field's inline
typing isn't needed. `format` (an `Intl.DateTimeFormatOptions` object -
the same shape every other JS date-formatting API already uses, default
`{ dateStyle: 'medium' }`) controls how that button's text reads:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
const withFormat = shallowRef<DateValue>()
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SDatePicker v-model="date" trigger-mode="button" />
    <SDatePicker v-model="withFormat" trigger-mode="button" :format="{ year: 'numeric', month: '2-digit', day: '2-digit' }" />
  </div>
</template>
```


```vue-html
<SDatePicker v-model="date" trigger-mode="button" />
<SDatePicker v-model="date" trigger-mode="button" :format="{ year: 'numeric', month: '2-digit', day: '2-digit' }" />
```

### Month/year view

Click the calendar heading to drill down from the day grid to a month grid,
then a year grid - picking a month or year jumps the day grid straight
there instead of paging one month at a time. `view` sets which grid opens
initially (`'date'` by default); passing `'year'` starts a birthdate-style
picker straight at the year grid:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="date" view="year" />
</template>
```


```vue-html
<SDatePicker v-model="date" view="year" />
```

Single-date mode only - `range`'s own heading and navigation are
unaffected by `view`.

### Month/year granularity

`view` only changes which grid the popover *starts* on - picking a month
there still drills down to a day. `granularity` is different: it changes
what the *value itself* represents. Set it to `'month'` or `'year'` for a
picker whose value stops at that precision - the day grid never renders,
and picking a month or year is the final action, closing the popover
(subject to `closeOnSelect`) instead of drilling further:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const month = shallowRef<DateValue>()
const year = shallowRef<DateValue>()
</script>

<template>
  <div class="flex flex-wrap gap-4">
    <SDatePicker v-model="month" granularity="month" />
    <SDatePicker v-model="year" granularity="year" />
  </div>
</template>
```


```vue-html
<SDatePicker v-model="month" granularity="month" />
<SDatePicker v-model="year" granularity="year" />
```

The underlying date library has no month-only or year-only value type, so
`modelValue` stays the same `DateValue` either way - `granularity="month"`
fixes the day to `1`, and `granularity="year"` fixes both month and day to
`1`. Segmented field mode only shows the segments that matter
(month+year, or just year), and the button-mode/formatted text defaults
adjust too (`"June 2024"` / `"2024"`) - both still overridable via `format`.
The heading can still drill *up* (e.g. a month-granularity picker jumping
to year view to reach a distant year quickly) - only the terminal, "picking
this is the answer" direction changes. Single-date mode only.

### Custom month/year disabling

`is-month-disabled`/`is-year-disabled` (`view="month"`/`"year"` only)
disable a specific month/year on top of whatever `min-value`/`max-value`
already disable - useful for blocking out a specific month for a known
closure, independent of the overall allowed range:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()

// Blocks July for a known closure - independent of minValue/maxValue.
function isMonthDisabled(monthDate: DateValue) {
  return monthDate.month === 7
}
</script>

<template>
  <SDatePicker v-model="date" view="month" :is-month-disabled="isMonthDisabled" />
</template>
```


```vue-html
<SDatePicker v-model="date" view="month" :is-month-disabled="(d) => d.month === 7" />
```

### Date-time selection

`granularity="hour"`/`"minute"` add a time-of-day section below the day
grid instead of replacing it - picking a day and setting a time are two
independent things, so the day grid stays fully usable. `modelValue`
becomes a time-capable `CalendarDateTime` (still just a `DateValue`, same
prop type as always). Since there's no single action that means "done"
here, `close-on-select` no longer closes the popover on a day click while
a time granularity is set - a **Done** button appears instead (hidden
entirely if you pass `close-on-select="false"`, since that already means
"never auto-close"):


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const value = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="value" granularity="minute" />
</template>
```


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const value = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="value" granularity="minute" />
</template>
```

`granularity="hour"` shows only the hour stepper; `"minute"` adds a second
one next to it. Both are built from
[InputNumber](https://selarasui.my.id/components/forms/input-number) - type a value directly or
use its ±buttons/arrow keys. `minute-step` (default `1`) only affects the
minute stepper's click/arrow-key increment; typing still commits any exact
minute - pass `5`/`15`/etc for a coarser "pick an appointment time" step.
Picking a day preserves whatever time is already set, and
adjusting the time commits a value using today's date if none has been
picked yet - either can be touched first. Single-date mode only.

The hour stepper follows the same hour cycle as the typed field itself -
both default to whatever `locale` resolves to (12-hour with an AM/PM
toggle for `en-US`, 24-hour for most others), so the two surfaces always
agree instead of one showing "14" and the other "2:00 PM" for the same
moment. Pass `hour-cycle="12"` or `hour-cycle="24"` to force one
regardless of locale:

```vue-html
<SDatePicker v-model="value" granularity="minute" hour-cycle="24" />
```

### Time only

`time-only` drops the date entirely - `modelValue` becomes a bare
`Time` (from `@internationalized/date`, no date component at all, not a
`DateValue`). Everything date-grid-specific (`min-value`/`max-value`,
`view`, `number-of-months`, and so on) simply doesn't apply - the popover
is just the hour/minute steppers, the same ones `granularity="hour"`/
`"minute"` already use:


```vue
<script setup lang="ts">
import type { Time } from '@internationalized/date'
import { shallowRef } from 'vue'

const value = shallowRef<Time>()
</script>

<template>
  <SDatePicker v-model="value" time-only />
</template>
```


```vue
<script setup lang="ts">
import type { Time } from '@internationalized/date'
import { shallowRef } from 'vue'

const value = shallowRef<Time>()
</script>

<template>
  <SDatePicker v-model="value" time-only />
</template>
```

`granularity`, `hour-cycle`, `minute-step`, `trigger-mode`, `clearable`,
and `close-on-select` all carry over unchanged from the date-time case
above - `granularity` defaults to `'minute'` here (a bare hour is a less
useful default for a *dedicated* time picker than as an add-on to a date).
Single-date mode only - `range` and `time-only` aren't combinable.

### Sizes

`size` takes `sm` / `md` / `lg`, scaling the field, segments, and calendar-
day buttons together:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const sm = shallowRef<DateValue>()
const md = shallowRef<DateValue>()
const lg = shallowRef<DateValue>()
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SDatePicker v-model="sm" size="sm" />
    <SDatePicker v-model="md" size="md" />
    <SDatePicker v-model="lg" size="lg" />
  </div>
</template>
```


```vue-html
<SDatePicker v-model="date" size="sm" />
<SDatePicker v-model="date" size="md" />
<SDatePicker v-model="date" size="lg" />
```

### Colors

`color` sets the chrome color - the clear/trigger buttons and prev/next
month nav; `active-color` sets the color of whatever's currently "active" -
the selected day/month/year cell and the Done button:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>(new CalendarDate(2024, 6, 15))
</script>

<template>
  <SDatePicker v-model="date" color="primary" active-color="danger" />
</template>
```


```vue-html
<SDatePicker v-model="date" color="primary" active-color="danger" />
```

### Arrow

`arrow` shows a small pointer triangle connecting the panel to its trigger
across single-date, range, and time-only modes. Pass an object to configure
its width, height, rounded tip, or corner clearance (`padding`):


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const value = shallowRef<DateValue>(new CalendarDate(2024, 6, 15))
</script>

<template>
  <SDatePicker v-model="value" arrow />
</template>
```


```vue-html
<SDatePicker v-model="value" arrow />
<SDatePicker v-model="value" :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }" />
```

`positioning` controls the anchored calendar's side, alignment, offsets, and
collision behavior. For the single-date calendar, an arrow defaults the panel
to center alignment so it remains visible; an explicit `positioning.align`
overrides that choice. `portal` defaults to the document body; set it to
`false` for inline rendering or pass a CSS selector or `HTMLElement` as the
teleport target. These props affect the anchored calendar in single, range,
and time-only modes. The adaptive modal has its own presentation.

```vue-html
<SDatePicker v-model="value" :positioning="{ side: 'top', align: 'start' }" portal="#overlay-root" />
```

### Clearable & disabled

`clearable` adds a dismiss button once a value is set; `disabled` disables
the whole control:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const clearable = shallowRef<DateValue>(new CalendarDate(2024, 6, 15))
const disabled = shallowRef<DateValue>()
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SDatePicker v-model="clearable" clearable />
    <SDatePicker v-model="disabled" disabled />
  </div>
</template>
```


```vue-html
<SDatePicker v-model="date" clearable />
<SDatePicker v-model="date" disabled />
```

### Read-only

`readonly` shows the value and blocks edits without disabling the control -
unlike `disabled`, it stays focusable/readable, just not changeable. Not
applicable to `time-only` (there's no readonly concept for a bare time
field):


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>(new CalendarDate(2024, 6, 15))
</script>

<template>
  <SDatePicker v-model="date" readonly />
</template>
```


```vue-html
<SDatePicker v-model="date" readonly />
```

### Preventing deselection

`prevent-deselect` stops a click on the only selected day from clearing it
entirely - useful when the control should always land on *some* value
rather than allowing an empty state. Not applicable to `time-only`:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>(new CalendarDate(2024, 6, 15))
</script>

<template>
  <SDatePicker v-model="date" prevent-deselect />
</template>
```


```vue-html
<SDatePicker v-model="date" prevent-deselect />
```

### Custom day content

The `day` slot replaces a day cell's content (in both single-date and range
grids) - the cell itself, including its selection/keyboard behavior, is
untouched. Scoped with `date`, `dayValue`, `selected`, `disabled`, and (range
mode only) `selectionStart`/`selectionEnd`/`highlighted`:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { getLocalTimeZone, today } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
const now = today(getLocalTimeZone())
const eventDates = [now.add({ days: 3 }), now.add({ days: 10 })]

function hasEvent(value: DateValue) {
  return eventDates.some(d => d.compare(value) === 0)
}
</script>

<template>
  <SDatePicker v-model="date">
    <template #day="{ date: cellDate, dayValue }">
      <span class="relative flex flex-col items-center">
        {{ dayValue }}
        <span v-if="hasEvent(cellDate)" class="absolute -bottom-1.5 size-1 rounded-full bg-[var(--selaras-resolved-color-primary-fill)]" />
      </span>
    </template>
  </SDatePicker>
</template>
```


```vue-html
<SDatePicker v-model="date">
  <template #day="{ date: cellDate, dayValue }">
    <span class="relative flex flex-col items-center">
      {{ dayValue }}
      <span v-if="hasEvent(cellDate)" class="absolute -bottom-1.5 size-1 rounded-full bg-[var(--selaras-resolved-color-primary-fill)]" />
    </span>
  </template>
</SDatePicker>
```

### Adaptive presentation

`adaptive` switches the calendar to a centered
[Modal](https://selarasui.my.id/components/overlays/modal) below your configured adaptive breakpoint.
It is opt-in (defaults `false`), chooses the presentation on open, and works
across single-date, range, and time-only mode:


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const date = shallowRef<DateValue>()
</script>

<template>
  <SDatePicker v-model="date" adaptive />
</template>
```


### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/
`invalid` and `aria-describedby` wired up automatically - `invalid` and
`size` both fall back to FormField's own state when not set directly.

### Accessibility

DatePicker renders Reka UI's DatePicker primitive, so the accessibility
semantics come from there rather than being reimplemented here: each date
segment is a real `contenteditable` element you can type into directly
(arrow keys/digits cycle a segment's value and auto-advance to the next),
the calendar grid is keyboard-navigable (arrow keys move between days,
paging past a grid edge advances the month), and the current/selected/
unavailable/disabled state of each day is exposed via `aria-selected`/
`aria-disabled` in addition to the visual styling.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `DatePicker`'s own theme file:

:theme-source{name="date-picker"}

### Time section styling

`ui.timeSection` styles the time controls below a calendar, including their divider.
`ui.timeSectionStandalone` styles time-only controls without adding a divider or
spacing for an absent calendar. Both slots also support global theme overrides.

```vue-html
<SDatePicker time-only :ui="{ timeSectionStandalone: 'gap-3' }" />
```

## Props

| Prop                       | Type                                                                                                                                                                                                                             | Default                         |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `id`                       | `string`                                                                                                                                                                                                                         | -                               |
| `name`                     | `string`                                                                                                                                                                                                                         | -                               |
| `form`                     | `string`                                                                                                                                                                                                                         | -                               |
| `open`                     | `boolean`                                                                                                                                                                                                                        | -                               |
| `defaultOpen`              | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `modelValue`               | `DateValue | DateRange | Time` (`DateRange` when `range` is set, `Time` when `timeOnly` is set)                                                                                                                                  | -                               |
| `defaultValue`             | `DateValue | DateRange | Time`                                                                                                                                                                                                   | -                               |
| `range`                    | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `timeOnly`                 | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `minValue`                 | `DateValue`                                                                                                                                                                                                                      | -                               |
| `maxValue`                 | `DateValue`                                                                                                                                                                                                                      | -                               |
| `isDateUnavailable`        | `(date: DateValue) => boolean`                                                                                                                                                                                                   | -                               |
| `isDateDisabled`           | `(date: DateValue) => boolean`                                                                                                                                                                                                   | -                               |
| `isDateHighlightable`      | `(date: DateValue) => boolean` (range only)                                                                                                                                                                                      | -                               |
| `locale`                   | `string`                                                                                                                                                                                                                         | -                               |
| `numberOfMonths`           | `number`                                                                                                                                                                                                                         | `1`, or `2` when `range` is set |
| `pagedNavigation`          | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `weekStartsOn`             | `0 | 1 | 2 | 3 | 4 | 5 | 6`                                                                                                                                                                                                      | -                               |
| `weekdayFormat`            | `'narrow' | 'short' | 'long'`                                                                                                                                                                                                    | `narrow`                        |
| `fixedWeeks`               | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `closeOnSelect`            | `boolean`                                                                                                                                                                                                                        | `true`                          |
| `triggerMode`              | `'field' | 'button'`                                                                                                                                                                                                             | `field`                         |
| `view`                     | `'date' | 'month' | 'year'` (single-date mode only)                                                                                                                                                                              | `date`                          |
| `isMonthDisabled`          | `(date: DateValue) => boolean` (`view="month"` only)                                                                                                                                                                             | -                               |
| `isYearDisabled`           | `(year: number) => boolean` (`view="year"` only)                                                                                                                                                                                 | -                               |
| `granularity`              | `'year' | 'month' | 'day' | 'hour' | 'minute'` (single-date mode only)                                                                                                                                                           | `day`                           |
| `minuteStep`               | `number` (hour/minute granularity only)                                                                                                                                                                                          | `1`                             |
| `hourCycle`                | `12 | 24` (hour/minute granularity only)                                                                                                                                                                                         | locale default                  |
| `format`                   | `Intl.DateTimeFormatOptions`                                                                                                                                                                                                     | `{ dateStyle: 'medium' }`       |
| `allowNonContiguousRanges` | `boolean` (range only)                                                                                                                                                                                                           | `false`                         |
| `fixedDate`                | `'start' | 'end'` (range only)                                                                                                                                                                                                   | -                               |
| `maximumDays`              | `number` (range only)                                                                                                                                                                                                            | -                               |
| `disabled`                 | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `readonly`                 | `boolean` (not `timeOnly`)                                                                                                                                                                                                       | `false`                         |
| `preventDeselect`          | `boolean` (not `timeOnly`)                                                                                                                                                                                                       | `false`                         |
| `invalid`                  | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `clearable`                | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `color`                    | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                                                                                                                                | `'neutral'`                     |
| `activeColor`              | same as `color`                                                                                                                                                                                                                  | `'primary'`                     |
| `size`                     | `'sm' | 'md' | 'lg'`                                                                                                                                                                                                             | `md`                            |
| `arrow`                    | `boolean | RoundedArrowConfig`                                                                                                                                                                                                   | `false`                         |
| `positioning`              | `OverlayPositioning`                                                                                                                                                                                                             | anchored calendar defaults      |
| `portal`                   | `boolean | string | HTMLElement`                                                                                                                                                                                                 | `true` (document body)          |
| `adaptive`                 | `boolean`                                                                                                                                                                                                                        | `false`                         |
| `ui`                       | `Partial<Record<'root' | 'field' | 'segment' | 'separator' | 'content' | 'mobileContent' | 'header' | 'heading' | 'grids' | 'grid' | 'gridHead' | 'headCell' | 'cell' | 'viewGrid' | 'timeSection' | 'arrow', string | object>>` | -                               |

## Slots

| Slot           | Props                                                                                                      | Description                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `day`          | `{ date, dayValue, selected, disabled }` (range mode adds `selectionStart`, `selectionEnd`, `highlighted`) | Custom content inside a day-cell button (single-date and range grids)                                            |
| `clear-icon`   | -                                                                                                          | Replaces the clear button's icon (default: `hugeicons:cancel-01`)                                                |
| `trigger-icon` | -                                                                                                          | Replaces the trigger button's icon in both trigger modes (default: `hugeicons:calendar-01`/`hugeicons:clock-01`) |
| `footer`       | -                                                                                                          | Content appended below the calendar/time content, above the Done button                                          |

## Emits

| Emit                | Payload                             | Description                                                                        |
| ------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| `update:open`       | `boolean`                           | Fires when the picker requests opening or closing                                  |
| `update:modelValue` | `DateValue | DateRange | undefined` | Fires when a day is picked, typed into the field's segments, or cleared            |
| `update:view`       | `'date' | 'month' | 'year'`         | Fires when the heading or a month/year cell drills the popover to a different view |


# FileUpload

## Usage

`v-model` is always a `File[]`, even for a single file - click the
dropzone or drag files onto it:


```vue
<script setup lang="ts">
const files = ref<File[]>([])
</script>

<template>
  <SFileUpload v-model="files" class="max-w-md" />
</template>
```


```vue
<script setup lang="ts">
const files = ref<File[]>([])
</script>

<template>
  <SFileUpload v-model="files" />
</template>
```

`FileUpload` only selects and validates files - actually sending them
to a server is up to you (a plain `fetch`/`FormData` call using
whatever's in `v-model`, whenever you want to trigger it).

### Multiple files

`multiple` allows selecting more than one file at once (each new
selection or drop adds to the list rather than replacing it);
`max-files` caps how many are allowed in total:


```vue
<script setup lang="ts">
const files = ref<File[]>([])
</script>

<template>
  <SFileUpload v-model="files" multiple :max-files="4" class="max-w-md" />
</template>
```


```vue-html
<SFileUpload v-model="files" multiple :max-files="4" />
```

### Validation

`accept` (comma-separated MIME types/wildcards like `image/*`, or
extensions like `.pdf`) and `max-size` (bytes) reject files that don't
match - applied to both the native file dialog and anything dropped
(drops bypass the dialog's own filtering entirely). Rejected files
never reach `v-model` - listen for `@error` to find out why and surface
it however you like:


```vue
<script setup lang="ts">
const files = ref<File[]>([])
const errors = ref<string[]>([])

function onError(rejected: { file: File, reason: string }[]) {
  errors.value = rejected.map(r => r.reason)
}
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-2">
    <SFileUpload
      v-model="files"
      accept="image/*"
      :max-size="1024 * 1024"
      @error="onError"
      @update:model-value="errors = []"
    />
    <p v-for="(error, index) in errors" :key="index" class="text-sm text-[var(--selaras-resolved-color-danger-text)]">
      {{ error }}
    </p>
  </div>
</template>
```


```vue-html
<SFileUpload
  v-model="files"
  accept="image/*"
  :max-size="1024 * 1024"
  @error="(rejected) => console.log(rejected)"
/>
```

### Color


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
const files = reactive<Record<(typeof colors)[number], File[]>>({
  primary: [],
  neutral: [],
  secondary: [],
  success: [],
  danger: [],
  info: [],
  warning: [],
})
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-3">
    <SFileUpload v-for="color in colors" :key="color" v-model="files[color]" :color="color" size="sm" />
  </div>
</template>
```


```vue-html
<SFileUpload color="success" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` falls back to
FormField's own state when not set directly on the file upload, and `size`
does the same.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `FileUpload`'s own theme file:

:theme-source{name="file-upload"}

## Props

| Prop         | Type                                                                              | Default   |
| ------------ | --------------------------------------------------------------------------------- | --------- |
| `id`         | `string`                                                                          | -         |
| `modelValue` | `File[]`                                                                          | -         |
| `accept`     | `string`                                                                          | -         |
| `multiple`   | `boolean`                                                                         | `false`   |
| `maxFiles`   | `number`                                                                          | -         |
| `maxSize`    | `number`                                                                          | -         |
| `preview`    | `boolean`                                                                         | `true`    |
| `disabled`   | `boolean`                                                                         | `false`   |
| `invalid`    | `boolean`                                                                         | `false`   |
| `size`       | `'sm' | 'md' | 'lg'`                                                              | `md`      |
| `color`      | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary` |
| `name`       | `string`                                                                          | -         |
| `required`   | `boolean`                                                                         | `false`   |
| `ui`         | `Partial<Record<FileUploadSlot, string | object>>`                                | -         |

## Events

| Event               | Payload                            | Description                               |
| ------------------- | ---------------------------------- | ----------------------------------------- |
| `update:modelValue` | `File[]`                           | Fires when files are added or removed     |
| `error`             | `{ file: File, reason: string }[]` | Fires when one or more files are rejected |

## Slots

| Slot      | Props                     | Description                                                |
| --------- | ------------------------- | ---------------------------------------------------------- |
| `default` | `{ isDragging }`          | Replaces the dropzone's own icon/label/description content |
| `file`    | `{ file, index, remove }` | Replaces one file row's content                            |


# FormField

## Usage

Wrap any single form control - Input, Textarea, Select, Autocomplete, Checkbox,
RadioGroup, or Switch - and FormField generates a matching `id`, links the
label to it, and computes `aria-describedby` from whichever of `hint`/`error`
is currently showing. The wrapped control picks all of this up automatically;
you don't pass `id` or `aria-describedby` yourself.

```vue
<script setup lang="ts">
const email = ref('')
</script>

<template>
  <SFormField label="Email" name="email" hint="We'll never share this.">
    <SInput v-model="email" type="email" placeholder="you@example.com" />
  </SFormField>
</template>
```

### Description

`description` adds a second, muted line under the label, before the
control - for context the user should read before reaching it (unlike
`hint`, which sits below the control instead):

```vue-html
<SFormField label="Email" description="We'll use this to send your receipt.">
  <SInput v-model="email" type="email" />
</SFormField>
```

### Error state

Set `error` to a string to show a message in place of the hint and mark the
control `invalid` (a red ring/outline, `aria-invalid="true"`). Passing
`error` as `true` (no message) still marks the control invalid without
rendering any text.

```vue-html
<SFormField label="Email" error="Enter a valid email address">
  <SInput v-model="email" type="email" />
</SFormField>
```

### Required indicator

```vue-html
<SFormField label="Name" required>
  <SInput v-model="name" />
</SFormField>
```

### Sizes

`size` also scales FormField's own label/description/hint/error text
(`sm` / `md` / `lg`) - it's the same prop already forwarded to the
wrapped control's own `size`, so both stay visually in sync without
setting it twice:

```vue-html
<SFormField label="Email" size="sm">
  <SInput v-model="email" size="sm" />
</SFormField>

<SFormField label="Email" size="lg">
  <SInput v-model="email" size="lg" />
</SFormField>
```

### Orientation

`orientation="horizontal"` places the label beside the control instead
of above it, with the control filling the remaining row width - useful
for settings-page-style label-left forms. `hint`/`error` still render
full-width below the row either way:

```vue-html
<SFormField label="Email" orientation="horizontal">
  <SInput v-model="email" />
</SFormField>
```

### Floating label

`label-mode="floating"` places the label over an empty control and moves it
above the border when the control is focused or has a value. It keeps the same
native label association, hint, and error behavior. Input and Textarea detect
their native value state; Select, Autocomplete, and DatePicker expose their
selection state to the field. For a custom control, pass `:filled` when it has
a value. Floating mode uses the vertical layout even if `orientation` is set
to `horizontal`. DatePicker's editable segmented field keeps the label raised
while empty so its day, month, and year placeholders remain visible and typeable.


```vue
<script setup lang="ts">
import type { DateValue } from '@internationalized/date'
import { shallowRef } from 'vue'

const email = ref('')
const name = ref('Maya Putri')
const notes = ref('')
const plan = ref<string>()
const appointment = shallowRef<DateValue>()
const dueDate = shallowRef<DateValue>()
const search = ref('')

const plans = [
  { label: 'Starter', value: 'starter' },
  { label: 'Team', value: 'team' },
]
</script>

<template>
  <div class="grid max-w-lg gap-5 sm:grid-cols-2">
    <SFormField label="Email" label-mode="floating" hint="We'll send your receipt here.">
      <SInput v-model="email" type="email" />
    </SFormField>
    <SFormField label="Name" label-mode="floating">
      <SInput v-model="name" icon="hugeicons:user" />
    </SFormField>
    <SFormField label="Plan" label-mode="floating">
      <SInputGroup class="w-full">
        <SSelect v-model="plan" :items="plans" class="min-w-0 flex-1" />
        <SButton type="button" variant="outline" color="neutral">
          Apply
        </SButton>
      </SInputGroup>
    </SFormField>
    <SFormField label="Appointment" label-mode="floating">
      <SDatePicker v-model="appointment" trigger-mode="button" />
    </SFormField>
    <SFormField label="Due date" label-mode="floating">
      <SDatePicker v-model="dueDate" />
    </SFormField>
    <SFormField label="Search" label-mode="floating">
      <SInputGroup class="w-full">
        <SInput v-model="search" />
        <SButton variant="outline" color="neutral">
          Go
        </SButton>
      </SInputGroup>
    </SFormField>
    <SFormField label="Notes" label-mode="floating">
      <STextarea v-model="notes" />
    </SFormField>
  </div>
</template>
```


```vue-html
<SFormField label="Email" label-mode="floating" hint="We'll send your receipt here.">
  <SInput v-model="email" type="email" />
</SFormField>
```

An `SInputGroup` containing one Input or Select plus an addon button also
works when the control comes first. For two editable controls, wrap **each**
input in its own `SFormField` so both have independent labels, names, and
validation state. This works with either InputGroup orientation:


```vue
<script setup lang="ts">
const horizontalFirst = ref('')
const horizontalLast = ref('')
const verticalFirst = ref('')
const verticalLast = ref('')
</script>

<template>
  <div class="grid max-w-lg gap-6">
    <div class="grid gap-2">
      <p class="text-sm font-medium">
        Horizontal
      </p>
      <SInputGroup class="w-full">
        <SFormField label="First name" name="horizontal-first-name" label-mode="floating" class="min-w-0 flex-1">
          <SInput v-model="horizontalFirst" autocomplete="given-name" />
        </SFormField>
        <SFormField label="Last name" name="horizontal-last-name" label-mode="floating" class="min-w-0 flex-1">
          <SInput v-model="horizontalLast" autocomplete="family-name" />
        </SFormField>
      </SInputGroup>
    </div>

    <div class="grid gap-2">
      <p class="text-sm font-medium">
        Vertical
      </p>
      <SInputGroup orientation="vertical" class="w-full">
        <SFormField label="First name" name="vertical-first-name" label-mode="floating">
          <SInput v-model="verticalFirst" autocomplete="given-name" />
        </SFormField>
        <SFormField label="Last name" name="vertical-last-name" label-mode="floating">
          <SInput v-model="verticalLast" autocomplete="family-name" />
        </SFormField>
      </SInputGroup>
    </div>
  </div>
</template>
```


### Works with any control

```vue-html
<SFormField label="Plan" name="plan">
  <SSelect v-model="plan" :items="planItems" />
</SFormField>

<SFormField error="You must accept the terms">
  <SCheckbox v-model="accepted" label="Accept terms" />
</SFormField>
```

A control's own `id`/`name` still win over FormField's if you set them
explicitly. `invalid` is OR'd with the field's error state instead, so a
control can opt into looking invalid on its own even without an error, but
can't be forced back to valid while its FormField has one.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `FormField`'s own theme file:

:theme-source{name="form-field"}

## Props

| Prop          | Type                                                                                                                                   | Default    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `label`       | `string`                                                                                                                               | -          |
| `name`        | `string`                                                                                                                               | -          |
| `description` | `string`                                                                                                                               | -          |
| `hint`        | `string`                                                                                                                               | -          |
| `error`       | `string | boolean`                                                                                                                     | -          |
| `required`    | `boolean`                                                                                                                              | `false`    |
| `size`        | `'sm' | 'md' | 'lg'`                                                                                                                   | -          |
| `orientation` | `'vertical' | 'horizontal'`                                                                                                            | `vertical` |
| `labelMode`   | `'static' | 'floating'`                                                                                                                | `static`   |
| `filled`      | `boolean`                                                                                                                              | `false`    |
| `ui`          | `Partial<Record<'root' | 'body' | 'header' | 'label' | 'required' | 'description' | 'container' | 'hint' | 'error', string | object>>` | -          |

## Slots

| Slot          | Props                          | Description                                                                      |
| ------------- | ------------------------------ | -------------------------------------------------------------------------------- |
| default       | `{ id, invalid, describedBy }` | The wrapped control. Props are also available if you need to bind them manually. |
| `description` | -                              | Custom content, overrides `description`                                          |


# Input

## Usage


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <SInput v-model="value" placeholder="Type something..." class="max-w-xs" />
</template>
```


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <SInput v-model="value" placeholder="Type something..." />
</template>
```

Input is full-width by default, rather than needing an opt-in flag to make
it so - constrain it with a class on the component itself (as the examples
on this page do with `max-w-xs`), not a wrapping element.

### Icons

`icon` and `trailingIcon` add an icon before or after the text - the same
props [Button](https://selarasui.my.id/components/elements/button#icons) uses for its own.


```vue
<script setup lang="ts">
const search = ref('')
const amount = ref('')
</script>

<template>
  <div class="flex flex-wrap items-center gap-3">
    <SInput v-model="search" icon="hugeicons:search-01" placeholder="Search..." class="max-w-xs" />
    <SInput v-model="amount" trailing-icon="hugeicons:dollar-01" placeholder="0.00" class="max-w-xs" />
  </div>
</template>
```


```vue-html
<SInput v-model="search" icon="hugeicons:search-01" placeholder="Search..." />
<SInput v-model="amount" trailing-icon="hugeicons:dollar-01" placeholder="0.00" />
```

### Custom leading and trailing content

Use `#leading` and `#trailing` for text, icons, or buttons inside the field frame.
The slots receive `{ disabled, size, buttonSize }`; `buttonSize` fits a Button
inside the current field size. Give interactive controls an accessible label,
use `type="button"`, and pass `disabled` through to match the field state.

Custom content stays visible alongside the built-in clear button. It replaces the corresponding decorative `icon` or `trailingIcon`.
The field reserves space for the rendered content, including suffixes whose
width changes. Use `ui.leading` and `ui.trailing` to customize its wrappers.


```vue
<script setup lang="ts">
const password = ref('A little secret')
const visible = ref(false)
</script>

<template>
  <SInput v-model="password" :type="visible ? 'text' : 'password'" clearable aria-label="Password" class="max-w-sm">
    <template #trailing="{ disabled, buttonSize }">
      <SButton
        type="button" :disabled="disabled" :size="buttonSize" variant="text" color="neutral" square
        :icon="visible ? 'hugeicons:view-off-slash' : 'hugeicons:view'"
        :aria-label="visible ? 'Hide password' : 'Show password'" :aria-pressed="visible"
        @click="visible = !visible"
      />
    </template>
  </SInput>
</template>
```


```vue
<script setup lang="ts">
const password = ref('')
const visible = ref(false)
</script>

<template>
  <SInput v-model="password" :type="visible ? 'text' : 'password'" clearable aria-label="Password">
    <template #trailing="{ disabled, buttonSize }">
      <SButton
        type="button" :disabled="disabled" :size="buttonSize" variant="text" color="neutral" square
        :icon="visible ? 'hugeicons:view-off-slash' : 'hugeicons:view'"
        :aria-label="visible ? 'Hide password' : 'Show password'" :aria-pressed="visible"
        @click="visible = !visible"
      />
    </template>
  </SInput>
</template>
```

Text prefixes and suffixes use the same slots:


```vue
<script setup lang="ts">
const amount = ref('125')
</script>

<template>
  <SInput v-model="amount" inputmode="decimal" aria-label="Amount in rupiah" class="max-w-sm" :ui="{ trailing: 'pe-3' }">
    <template #leading>
      <span>Rp</span>
    </template>
    <template #trailing>
      <span>per month</span>
    </template>
  </SInput>
</template>
```


### Clear

`clearable` adds a button that empties the value, once there's something to
clear - it takes over the trailing position from `trailingIcon` while active,
the same way [Select's](https://selarasui.my.id/components/forms/select#clear) does.


```vue
<script setup lang="ts">
const value = ref('Clear me')
</script>

<template>
  <SInput v-model="value" clearable placeholder="Type something..." class="max-w-xs" />
</template>
```


```vue-html
<SInput v-model="value" clearable placeholder="Type something..." />
```

### Sizes and states

`size` takes `sm` / `md` / `lg`, `disabled` prevents interaction and dims the
input, and `invalid` switches the ring to the danger role's focus color:


```vue
<script setup lang="ts">
const email = ref('')
</script>

<template>
  <SInput v-model="email" invalid placeholder="you@example.com" class="max-w-xs" />
</template>
```


```vue-html
<SInput v-model="email" invalid placeholder="you@example.com" />
```

See the [Props](https://selarasui.my.id/#props) table below.

### Colors

`color` sets the focus-ring color - the resting (unfocused) ring stays
`--selaras-resolved-border-default` regardless, and `invalid` always wins over a custom `color`:


```vue
<script setup lang="ts">
const primary = ref('')
const success = ref('')
const danger = ref('')
</script>

<template>
  <div class="flex w-full max-w-xs flex-col gap-4">
    <SInput v-model="primary" color="primary" placeholder="Primary" />
    <SInput v-model="success" color="success" placeholder="Success" />
    <SInput v-model="danger" color="danger" placeholder="Danger" />
  </div>
</template>
```


```vue-html
<SInput v-model="primary" color="primary" placeholder="Primary" />
<SInput v-model="success" color="success" placeholder="Success" />
<SInput v-model="danger" color="danger" placeholder="Danger" />
```

### Masking

Use the [`v-mask`](https://selarasui.my.id/utilities/directives/mask) directive to format the text as
it's typed. `v-model` keeps the raw value, while the field shows the
formatted one - typing `5551234567` below shows `(555) 123-4567`, and
`phone` is `5551234567`:


```vue
<script setup lang="ts">
const phone = ref('')
</script>

<template>
  <div class="grid gap-2">
    <SInput v-model="phone" v-mask="'(###) ###-####'" inputmode="tel" placeholder="(555) 123-4567" />
    <p class="text-sm text-content-muted">
      Value: {{ phone || '—' }}
    </p>
  </div>
</template>
```


```vue-html
<SInput v-model="phone" v-mask="'(###) ###-####'" inputmode="tel" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid`
and `aria-describedby` wired up automatically, plus a `hint`/`error` message
underneath - FormField is also where `size` and `invalid` fall back to when
not set directly on the input.

### Accessibility

Input renders a plain native `<input>`, so browser and screen-reader support
for typing, selection, and autofill all come for free. `aria-invalid` and
`aria-describedby` are set automatically once `invalid` is true or the input
is wrapped in [FormField](https://selarasui.my.id/components/forms/form-field) - nothing to
configure by hand for the common case.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Input`'s own theme file:

:theme-source{name="input"}

## Props

| Prop           | Type                                                                                                                    | Default   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |
| `id`           | `string`                                                                                                                | -         |
| `name`         | `string`                                                                                                                | -         |
| `modelValue`   | `string | number`                                                                                                       | -         |
| `type`         | `string`                                                                                                                | `text`    |
| `placeholder`  | `string`                                                                                                                | -         |
| `size`         | `'sm' | 'md' | 'lg'`                                                                                                    | `md`      |
| `disabled`     | `boolean`                                                                                                               | `false`   |
| `invalid`      | `boolean`                                                                                                               | `false`   |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                       | `primary` |
| `clearable`    | `boolean`                                                                                                               | `false`   |
| `icon`         | `string`                                                                                                                | -         |
| `trailingIcon` | `string`                                                                                                                | -         |
| `ui`           | `Partial<Record<'root' | 'base' | 'leadingIcon' | 'trailingIcon' | 'leading' | 'trailing' | 'clear', string | object>>` | -         |

## Slots

| Slot         | Props                            | Description                                                                        |
| ------------ | -------------------------------- | ---------------------------------------------------------------------------------- |
| `leading`    | `{ disabled, size, buttonSize }` | Custom content before the text; replaces `icon`                                    |
| `trailing`   | `{ disabled, size, buttonSize }` | Custom content after the text, alongside the clear button; replaces `trailingIcon` |
| `clear-icon` | -                                | Replaces the clear button's icon (default: `hugeicons:cancel-01`)                  |


# InputGroup

## Usage

`SInputGroup` takes any mix of children in its default slot and squares off
their shared inner corners, overlapping their 1px borders so they read as
one control instead of several stacked side by side.


```vue
<template>
  <div class="flex flex-col gap-4">
    <SInputGroup>
      <span class="inline-flex items-center rounded-[var(--selaras-resolved-radius-md)] bg-[var(--selaras-resolved-surface-elevated)] px-3 text-sm text-[var(--selaras-resolved-text-muted)] ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
        $
      </span>
      <SInput placeholder="0.00" />
      <span class="inline-flex items-center rounded-[var(--selaras-resolved-radius-md)] bg-[var(--selaras-resolved-surface-elevated)] px-3 text-sm text-[var(--selaras-resolved-text-muted)] ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
        USD
      </span>
    </SInputGroup>

    <SInputGroup>
      <SInput placeholder="Search..." />
      <SButton>
        Search
      </SButton>
    </SInputGroup>
  </div>
</template>
```


```vue-html
<SInputGroup>
  <span class="inline-flex items-center rounded-[var(--selaras-resolved-radius-md)] bg-[var(--selaras-resolved-surface-elevated)] px-3 text-sm text-[var(--selaras-resolved-text-muted)] ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
    $
  </span>
  <SInput placeholder="0.00" />
  <span class="inline-flex items-center rounded-[var(--selaras-resolved-radius-md)] bg-[var(--selaras-resolved-surface-elevated)] px-3 text-sm text-[var(--selaras-resolved-text-muted)] ring-1 ring-inset ring-[var(--selaras-resolved-border-default)]">
    USD
  </span>
</SInputGroup>

<SInputGroup>
  <SInput placeholder="Search..." />
  <SButton>Search</SButton>
</SInputGroup>
```

### With a Select

Any groupable component works, not just Input and Button - here a
`SSelect` is joined to an `SInput`:


```vue
<script setup lang="ts">
const countryCode = ref('+1')

const countryCodes = [
  { label: '+1', value: '+1' },
  { label: '+44', value: '+44' },
  { label: '+61', value: '+61' },
]
</script>

<template>
  <SInputGroup class="max-w-xs">
    <SSelect v-model="countryCode" :items="countryCodes" class="w-24 shrink-0" />
    <SInput placeholder="Phone number" />
  </SInputGroup>
</template>
```


```vue-html
<SInputGroup>
  <SSelect v-model="countryCode" :items="countryCodes" class="w-24 shrink-0" />
  <SInput placeholder="Phone number" />
</SInputGroup>
```

### Vertical

With two editable controls, give each its own `SFormField` so the labels and
form names remain independent. The group joins their borders vertically. See
[FormField's grouped example](https://selarasui.my.id/components/forms/form-field#floating-label) for
the same pair in both orientations.


```vue
<script setup lang="ts">
const firstName = ref('')
const lastName = ref('')
</script>

<template>
  <SInputGroup orientation="vertical" class="w-64">
    <SFormField label="First name" name="firstName" label-mode="floating">
      <SInput v-model="firstName" autocomplete="given-name" />
    </SFormField>
    <SFormField label="Last name" name="lastName" label-mode="floating">
      <SInput v-model="lastName" autocomplete="family-name" />
    </SFormField>
  </SInputGroup>
</template>
```


```vue-html
<SInputGroup orientation="vertical">
  <SFormField label="First name" name="firstName" label-mode="floating">
    <SInput v-model="firstName" autocomplete="given-name" />
  </SFormField>
  <SFormField label="Last name" name="lastName" label-mode="floating">
    <SInput v-model="lastName" autocomplete="family-name" />
  </SFormField>
</SInputGroup>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `InputGroup`'s own theme file:

Global and scoped theme recipes use `ui.inputGroup`.

:theme-source{name="input-group"}

## Props

| Prop          | Type                                               | Default        |
| ------------- | -------------------------------------------------- | -------------- |
| `orientation` | `'horizontal' | 'vertical'`                        | `'horizontal'` |
| `ui`          | `Partial<Record<InputGroupSlot, string | object>>` | -              |


# InputNumber

## Usage

`v-model` is a plain `number | undefined` - an empty field commits as
`undefined`, not `0` or `NaN`:


```vue
<script setup lang="ts">
const value = ref<number>()
</script>

<template>
  <SInputNumber v-model="value" class="max-w-32" />
</template>
```


```vue
<script setup lang="ts">
const value = ref<number>()
</script>

<template>
  <SInputNumber v-model="value" />
</template>
```

Type a value directly, use the arrow keys while focused, or click the
±buttons - all three commit through the same `min`/`max`/`step` clamping.

### Min, max, and step

`min`/`max` clamp the committed value and disable the button at whichever
boundary is reached; `step` controls how much each click or arrow-key press
changes the value (default `1`):


```vue
<script setup lang="ts">
const value = ref(4)
</script>

<template>
  <SInputNumber v-model="value" :min="0" :max="10" :step="2" class="max-w-32" />
</template>
```


```vue-html
<SInputNumber v-model="value" :min="0" :max="10" :step="2" />
```

`wrap` changes what happens at the boundary - instead of clamping and
disabling the button there, stepping past `max` cycles to `min` (and past
`min` cycles to `max`), the same way an hour-of-day or a compass heading
wraps around rather than getting stuck:


```vue
<script setup lang="ts">
const hour = ref(12)
</script>

<template>
  <SInputNumber v-model="hour" :min="1" :max="12" wrap class="max-w-32" />
</template>
```


```vue-html
<SInputNumber v-model="hour" :min="1" :max="12" wrap />
```

### Format options

`format-options` is a plain `Intl.NumberFormatOptions` object - the same
shape every other JS number-formatting API already uses - applied to the
value once it's no longer being edited. Typing itself always shows the
plain number, so the two never fight each other:


```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <SInputNumber v-model="value" :min="0" :max="59" :format-options="{ minimumIntegerDigits: 2 }" class="max-w-32" />
</template>
```


```vue-html
<SInputNumber v-model="value" :format-options="{ minimumIntegerDigits: 2 }" />
```

### Orientation

`orientation="vertical"` replaces the two full-height flanking buttons with
a single compact up/down pair pinned to the field's end edge - useful when
horizontal space is tight:


```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <SInputNumber v-model="value" orientation="vertical" class="max-w-32" />
</template>
```


```vue-html
<SInputNumber v-model="value" orientation="vertical" />
```

### Sizes and states

`size` takes `sm` / `md` / `lg`, `disabled` prevents interaction and dims
the control, and `invalid` switches the ring to the danger role's focus color:


```vue
<script setup lang="ts">
const sm = ref<number>()
const disabled = ref(3)
const invalid = ref<number>()
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SInputNumber v-model="sm" size="sm" class="max-w-32" />
    <SInputNumber v-model="disabled" disabled class="max-w-32" />
    <SInputNumber v-model="invalid" invalid class="max-w-32" />
  </div>
</template>
```


```vue-html
<SInputNumber v-model="value" size="sm" />
<SInputNumber v-model="value" disabled />
<SInputNumber v-model="value" invalid />
```

### Colors

`color` sets the focus-ring color - the resting (unfocused) ring stays
`--selaras-resolved-border-default` regardless, and `invalid` always wins over a custom `color`:


```vue
<script setup lang="ts">
const primary = ref<number>()
const success = ref<number>()
const danger = ref<number>()
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SInputNumber v-model="primary" color="primary" class="max-w-32" />
    <SInputNumber v-model="success" color="success" class="max-w-32" />
    <SInputNumber v-model="danger" color="danger" class="max-w-32" />
  </div>
</template>
```


```vue-html
<SInputNumber v-model="primary" color="primary" />
<SInputNumber v-model="success" color="success" />
<SInputNumber v-model="danger" color="danger" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/
`invalid` and `aria-describedby` wired up automatically - `invalid` and
`size` both fall back to FormField's own state when not set directly.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `InputNumber`'s own theme file:

:theme-source{name="input-number"}

## Props

| Prop            | Type                                                                               | Default      |
| --------------- | ---------------------------------------------------------------------------------- | ------------ |
| `id`            | `string`                                                                           | -            |
| `name`          | `string`                                                                           | -            |
| `modelValue`    | `number`                                                                           | -            |
| `min`           | `number`                                                                           | -            |
| `max`           | `number`                                                                           | -            |
| `step`          | `number`                                                                           | `1`          |
| `wrap`          | `boolean`                                                                          | `false`      |
| `placeholder`   | `string`                                                                           | -            |
| `formatOptions` | `Intl.NumberFormatOptions`                                                         | -            |
| `locale`        | `string`                                                                           | -            |
| `disabled`      | `boolean`                                                                          | `false`      |
| `invalid`       | `boolean`                                                                          | `false`      |
| `color`         | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`  | `primary`    |
| `size`          | `'sm' | 'md' | 'lg'`                                                               | `md`         |
| `orientation`   | `'horizontal' | 'vertical'`                                                        | `horizontal` |
| `ui`            | `Partial<Record<'root' | 'input' | 'stepper' | 'stepperButton', string | object>>` | -            |

## Emits

| Emit                | Payload              | Description                                                                       |
| ------------------- | -------------------- | --------------------------------------------------------------------------------- |
| `update:modelValue` | `number | undefined` | Fires on increment/decrement click, ArrowUp/ArrowDown, or blur/Enter after typing |


# Listbox

## Usage

Listbox presents its options directly on the page. Use it when choices should
remain visible; use [Select](https://selarasui.my.id/components/forms/select) when they should open in
a popup. Selection is single by default.


```vue
<script setup lang="ts">
const selected = ref('Design')
const items = ['Design', 'Engineering', 'Operations', 'Support']
</script>

<template>
  <div class="w-full max-w-sm space-y-3">
    <SListbox v-model="selected" :items="items" label="Department" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Selected: {{ selected ?? 'None' }}
    </p>
  </div>
</template>
```


`items` accepts strings, finite numbers, and objects. A primitive is both its
label and value. Objects display `label` and use their `value` property when
present; otherwise the complete object is the value. Explicit `labelKey` and
`valueKey` select different properties. Numeric `1` and string `'1'` are distinct.
Values must be unique across all groups. Whole objects compare by identity;
use a stable `valueKey` when replacing records fetched from an API.

### Multiple selection

`multiple` uses an array model. Clicking or pressing Space toggles a row without
requiring a modifier key. `selectionBehavior="replace"` enables replacement
selection with modifier keys for additive selection. `checkbox` shows decorative
checkbox indicators; the option remains the only interactive element in each row.


```vue
<script setup lang="ts">
const selected = ref(['read'])
const items = [
  { label: 'Workspace', items: [{ label: 'Read projects', value: 'read' }, { label: 'Create projects', value: 'create' }, { label: 'Delete projects', value: 'delete', disabled: true }] },
  { label: 'Team', items: [{ label: 'Invite members', value: 'invite' }, { label: 'Manage roles', value: 'roles' }] },
]
</script>

<template>
  <div class="w-full max-w-sm space-y-3">
    <SListbox v-model="selected" :items="items" label="Permissions" multiple checkbox searchable select-all />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ selected.length }} permissions selected
    </p>
  </div>
</template>
```


`selectAll` adds a header checkbox in multiple mode. It checks or unchecks only
visible, enabled options and preserves selections outside the current filter.
Ctrl/Cmd+A within the list follows the same rules.
Groups use the same `{ label, items }` shape as Select.

### Search and empty states

`searchable` adds a filter input. Bind `v-model:search-term` to control its text.
Search matches labels without case or accent sensitivity. Filtering preserves
selection, and choosing an item leaves the search text intact.
Use `empty` for an empty collection and `empty-filter` for no matching results.

### Rich items and custom keys

Objects can include `description`, `icon`, and `disabled`. `descriptionKey`
defaults to `description`. The `item` slot receives the original item plus
`index`, `selected`, and `disabled`; the index identifies its position in the
complete flattened collection. Use `group` to replace a group label.


```vue
<script setup lang="ts">
const selected = ref(1)
const items = [
  { id: 1, name: 'Product design', description: 'Interfaces and user experience', icon: 'hugeicons:paint-brush-01' },
  { id: 2, name: 'Engineering', description: 'Application development', icon: 'hugeicons:code' },
  { id: 3, name: 'Support', description: 'Customer care', icon: 'hugeicons:customer-support' },
]
</script>

<template>
  <SListbox v-model="selected" :items="items" value-key="id" label-key="name" label="Teams" class="w-full max-w-sm" />
</template>
```


Keep custom options to display content. Put independent links or action buttons
in a regular list or table rather than inside a listbox option.

### Virtualization

`virtualize` renders a window of options for large collections. Pass `true` or
`{ estimateSize, overscan }`. Group headers are omitted while virtualized.
This does not fetch additional pages.


```vue
<script setup lang="ts">
const selected = ref<number[]>([])
const items = Array.from({ length: 5000 }, (_, index) => ({ label: `Item ${index + 1}`, value: index + 1 }))
</script>

<template>
  <SListbox v-model="selected" :items="items" label="Large collection" multiple searchable virtualize class="w-full max-w-sm" />
</template>
```


### Controlled values and forms

Use `v-model` for controlled selection, or `defaultValue` for initial uncontrolled
selection. Explicit `modelValue: undefined` stays controlled and empty until the
parent accepts an update. Missing async values remain selected as options load.

An uncontrolled change to `multiple` converts a scalar to an array or keeps the
first array item for single mode. Controlled parents must update the model shape
and mode together. Duplicate model/default values are rejected.

Wrap Listbox in [FormField](https://selarasui.my.id/components/forms/form-field) for its label,
description, invalid state, size, and name. `name` submits each selected value;
objects serialize as JSON. `form` associates an external form, and `required`
requires a nonempty selection. Native reset restores the mount-captured default
in the current selection mode and clears search. Canceled resets are ignored.

### Accessibility

`label` or `aria-label` names the listbox; FormField can supply its label instead.
Arrow keys move focus, Home/End reach the edges, and Enter/Space select an option.
Focus and selection remain separate. Search uses an editable combobox linked to
the inline options. Listbox stays inline at every viewport size.

### Styling

`size` accepts `sm`, `md`, or `lg`; `color` controls selection and focus tokens.
`invalid` uses the danger role. Override `ui.listbox` globally or within Theme,
or pass `:ui` to a single instance.

:theme-source{name="listbox"}

## Props

| Prop                               | Type                                           | Default                                              |
| ---------------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
| `items`                            | readonly primitive, object, or grouped entries | required                                             |
| `modelValue` / `defaultValue`      | selected value or array                        | -                                                    |
| `labelKey` / `valueKey`            | object property                                | `label` / `value` when present, otherwise the object |
| `descriptionKey`                   | object property                                | `description`                                        |
| `multiple`                         | boolean                                        | `false`                                              |
| `selectionBehavior`                | `toggle` / `replace`                           | `toggle`                                             |
| `checkbox` / `selectAll`           | boolean                                        | `false`                                              |
| `searchable`                       | boolean                                        | `false`                                              |
| `searchTerm`                       | string                                         | empty                                                |
| `virtualize`                       | boolean or `{ estimateSize, overscan }`        | `false`                                              |
| `label`                            | string                                         | form label or configured select message              |
| `disabled` / `loading` / `invalid` | boolean                                        | `false`                                              |
| `size` / `color`                   | control size / semantic role                   | `md` / `primary`                                     |
| `id` / `name` / `form`             | string                                         | -                                                    |
| `required`                         | boolean                                        | `false`                                              |
| `ui`                               | slot overrides                                 | -                                                    |

## Slots

| Slot                     | Props                                 | Purpose                             |
| ------------------------ | ------------------------------------- | ----------------------------------- |
| `item`                   | `{ item, index, selected, disabled }` | Original option content             |
| `group`                  | `{ group }`                           | Group heading                       |
| `header` / `footer`      | -                                     | Content surrounding the list        |
| `empty` / `empty-filter` | -                                     | Empty collection / unmatched search |

Public `ListboxProps`, `ListboxEmits`, and `ListboxSlots` types are available from
`@sewadah/selaras/types`. They infer the item, identity key, and multiple mode in
the same way as Select.


# PinInput

## Usage

`v-model` is an array of strings, one entry per box - typing
auto-advances focus, backspace on an empty box moves back to and clears
the previous one, and pasting a multi-character value fills several
boxes at once:


```vue
<script setup lang="ts">
const value = ref<string[]>([])
</script>

<template>
  <SPinInput v-model="value" aria-label="Verification code" />
</template>
```


```vue
<script setup lang="ts">
const value = ref<string[]>([])
</script>

<template>
  <SPinInput v-model="value" aria-label="Verification code" />
</template>
```

`length` sets how many boxes render (`5` by default).

### OTP autofill

`otp` sets `autocomplete="one-time-code"`, letting the browser/OS offer
to autofill a code from an incoming SMS, and auto-focuses the first
empty box whenever focus lands anywhere in the group:


```vue
<script setup lang="ts">
const value = ref<string[]>([])
</script>

<template>
  <SPinInput v-model="value" otp :length="6" aria-label="SMS code" />
</template>
```


```vue-html
<SPinInput v-model="value" otp :length="6" />
```

### Masked

`mask` renders each box as a password field (dots instead of the typed
character) - a PIN code someone might be entering in public:


```vue
<script setup lang="ts">
const value = ref<string[]>([])
</script>

<template>
  <SPinInput v-model="value" mask aria-label="PIN code" />
</template>
```


```vue-html
<SPinInput v-model="value" mask />
```

### Numeric

`type="number"` gets the mobile numeric keypad (`inputmode="numeric"`)
and filters out non-digit input - but stores each box as a real
`number`, not a string, so a leading zero is lost (`"0"` becomes `0`,
and a code like `"007"` becomes `7`). Stick with the default `type="text"`
whenever leading zeros are significant, which is the common case for a
PIN/OTP code:


```vue
<script setup lang="ts">
const value = ref<number[]>([])
</script>

<template>
  <SPinInput v-model="value" type="number" aria-label="Numeric code" />
</template>
```


```vue-html
<SPinInput v-model="value" type="number" />
```

### Color

The `color` variant recolors the focus ring only - the resting ring
stays neutral regardless, matching `Input`:


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SPinInput v-for="color in colors" :key="color" :color="color" :aria-label="color" />
  </div>
</template>
```


```vue-html
<SPinInput color="success" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` falls back to
FormField's own state when not set directly on the pin input, and `size`
does the same.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `PinInput`'s own theme file:

:theme-source{name="pin-input"}

## Props

| Prop           | Type                                                                              | Default   |
| -------------- | --------------------------------------------------------------------------------- | --------- |
| `id`           | `string`                                                                          | -         |
| `modelValue`   | `(string | number)[]`                                                             | -         |
| `defaultValue` | `(string | number)[]`                                                             | -         |
| `length`       | `number`                                                                          | `5`       |
| `placeholder`  | `string`                                                                          | -         |
| `mask`         | `boolean`                                                                         | `false`   |
| `otp`          | `boolean`                                                                         | `false`   |
| `type`         | `'text' | 'number'`                                                               | `text`    |
| `disabled`     | `boolean`                                                                         | `false`   |
| `invalid`      | `boolean`                                                                         | `false`   |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `md`      |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary` |
| `name`         | `string`                                                                          | -         |
| `required`     | `boolean`                                                                         | `false`   |
| `ui`           | `Partial<Record<'root' | 'input', string | object>>`                              | -         |

## Events

| Event               | Payload               | Description                            |
| ------------------- | --------------------- | -------------------------------------- |
| `update:modelValue` | `(string | number)[]` | Fires on every keystroke/paste         |
| `complete`          | `(string | number)[]` | Fires once, when every box has a value |


# RadioGroup

## Usage


```vue
<script setup lang="ts">
const choice = ref('one')
</script>

<template>
  <SRadioGroup
    v-model="choice"
    :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]"
  />
</template>
```


```vue
<script setup lang="ts">
const choice = ref('one')
</script>

<template>
  <SRadioGroup
    v-model="choice"
    :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]"
  />
</template>
```

### Simple options

A plain string in `items` is shorthand for `{ label: value, value }`, for
when the label and value are the same:


```vue
<script setup lang="ts">
const size = ref('md')
</script>

<template>
  <SRadioGroup v-model="size" :items="['sm', 'md', 'lg']" />
</template>
```


```vue-html
<SRadioGroup v-model="size" :items="['sm', 'md', 'lg']" />
```

### Orientation

`orientation` switches the layout between a vertical stack (the default)
and a horizontal row - it's also forwarded to the underlying primitive, so
arrow-key navigation follows the same axis (left/right instead of up/down):


```vue
<script setup lang="ts">
const shipping = ref('standard')
</script>

<template>
  <SRadioGroup v-model="shipping" orientation="horizontal" :items="['standard', 'express', 'overnight']" />
</template>
```


```vue-html
<SRadioGroup v-model="shipping" orientation="horizontal" :items="['standard', 'express', 'overnight']" />
```

### Description

A `description` on an item renders as a second, muted line under its
label - the item top-aligns with the label's first line instead of
centering against the whole two-line block whenever it's present:


```vue
<script setup lang="ts">
const plan = ref('pro')
</script>

<template>
  <SRadioGroup
    v-model="plan"
    :items="[
      { label: 'Free', value: 'free', description: 'Basic features, community support.' },
      { label: 'Pro', value: 'pro', description: 'Everything in Free, plus priority support.' },
    ]"
  />
</template>
```


```vue-html
<SRadioGroup
  v-model="plan"
  :items="[
    { label: 'Free', value: 'free', description: 'Basic features, community support.' },
    { label: 'Pro', value: 'pro', description: 'Everything in Free, plus priority support.' },
  ]"
/>
```

For anything beyond plain text - a price, a badge, custom markup - replace
the whole label block with the `label` slot instead; see [Slots](https://selarasui.my.id/#slots).

### Card style

`variant="card"` wraps each option in its own bordered box instead of a
plain inline row, highlighting whichever one is selected. Works the same
with or without `description`:


```vue
<script setup lang="ts">
const plan = ref('pro')
</script>

<template>
  <SRadioGroup
    v-model="plan"
    variant="card"
    :items="[
      { label: 'Free', value: 'free', description: 'Basic features, community support.' },
      { label: 'Pro', value: 'pro', description: 'Everything in Free, plus priority support.' },
    ]"
  />
</template>
```


```vue-html
<SRadioGroup
  v-model="plan"
  variant="card"
  :items="[
    { label: 'Free', value: 'free', description: 'Basic features, community support.' },
    { label: 'Pro', value: 'pro', description: 'Everything in Free, plus priority support.' },
  ]"
/>
```

### Colors

`color` sets the checked-state ring/dot color (and, combined with
`variant="card"`, the card's own highlight border/tint) - unchecked always
stays the same neutral ring regardless:


```vue
<script setup lang="ts">
const primary = ref('one')
const success = ref('one')
const danger = ref('one')
</script>

<template>
  <div class="flex flex-col gap-4">
    <SRadioGroup v-model="primary" color="primary" orientation="horizontal" :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]" />
    <SRadioGroup v-model="success" color="success" orientation="horizontal" :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]" />
    <SRadioGroup v-model="danger" color="danger" orientation="horizontal" :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]" />
  </div>
</template>
```


```vue-html
<SRadioGroup v-model="primary" color="primary" :items="['one', 'two']" />
<SRadioGroup v-model="success" color="success" :items="['one', 'two']" />
<SRadioGroup v-model="danger" color="danger" :items="['one', 'two']" />
```

### States

Setting `disabled` on an individual item (rather than the whole
`SRadioGroup`) disables just that one, leaving the rest of the group
interactive - including when that item happens to already be the selected
one, e.g. a plan a consumer picked before it was discontinued:


```vue
<script setup lang="ts">
const shipping = ref('standard')
const plan = ref('legacy')
const frozen = ref('one')
const invalidChoice = ref<string>()
</script>

<template>
  <div class="flex flex-col gap-6">
    <SRadioGroup
      v-model="shipping"
      :items="[
        { label: 'Standard', value: 'standard' },
        { label: 'Express', value: 'express', disabled: true },
        { label: 'Overnight', value: 'overnight' },
      ]"
    />
    <SRadioGroup
      v-model="plan"
      :items="[
        { label: 'Legacy (discontinued)', value: 'legacy', disabled: true },
        { label: 'Starter', value: 'starter' },
        { label: 'Pro', value: 'pro' },
      ]"
    />
    <SRadioGroup v-model="frozen" disabled :items="['one', 'two', 'three']" />
    <SRadioGroup v-model="invalidChoice" invalid :items="['one', 'two', 'three']" />
  </div>
</template>
```


```vue-html
<SRadioGroup
  v-model="shipping"
  :items="[
    { label: 'Standard', value: 'standard' },
    { label: 'Express', value: 'express', disabled: true },
    { label: 'Overnight', value: 'overnight' },
  ]"
/>
<SRadioGroup
  v-model="plan"
  :items="[
    { label: 'Legacy (discontinued)', value: 'legacy', disabled: true },
    { label: 'Starter', value: 'starter' },
    { label: 'Pro', value: 'pro' },
  ]"
/>
```

`disabled` on the group itself disables every item at once instead of just
one, and `invalid` switches every item's ring and card state to the semantic
danger role:

```vue-html
<SRadioGroup v-model="frozen" disabled :items="['one', 'two', 'three']" />
<SRadioGroup v-model="invalidChoice" invalid :items="['one', 'two', 'three']" />
```

See [Props](https://selarasui.my.id/#props).

### Sizes

`size` takes `sm` / `md` / `lg`, scaling the item, indicator, hover/focus
halo, and label text together:


```vue
<script setup lang="ts">
const sm = ref('one')
const md = ref('one')
const lg = ref('one')
</script>

<template>
  <div class="flex flex-col gap-4">
    <SRadioGroup v-model="sm" size="sm" orientation="horizontal" :items="['one', 'two']" />
    <SRadioGroup v-model="md" size="md" orientation="horizontal" :items="['one', 'two']" />
    <SRadioGroup v-model="lg" size="lg" orientation="horizontal" :items="['one', 'two']" />
  </div>
</template>
```


```vue-html
<SRadioGroup v-model="size" size="sm" :items="['one', 'two']" />
<SRadioGroup v-model="size" size="md" :items="['one', 'two']" />
<SRadioGroup v-model="size" size="lg" :items="['one', 'two']" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` and `size` both fall
back to FormField's own state when not set directly on the radio group.

### Accessibility

RadioGroup renders Reka UI's RadioGroup primitive, so the accessibility
semantics come from there rather than being reimplemented here: the group
itself is `role="radiogroup"` and each item is `role="radio"` with
`aria-checked`. The whole group is a single :kbd[Tab] stop (roving
tabindex, not one stop per item) - once focus is inside, the arrow keys move
focus between items and immediately select whichever one it lands on (up/
down for the default vertical layout, left/right when `orientation` is
`horizontal`), the standard behavior for the
[ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/){rel="&#x22;nofollow&#x22;"},
not something to configure here.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `RadioGroup`'s own theme file:

:theme-source{name="radio-group"}

## Props

| Prop          | Type                                                                                                                       | Default    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `id`          | `string`                                                                                                                   | -          |
| `name`        | `string`                                                                                                                   | -          |
| `items`       | `(string | { label: string; value: string; disabled?: boolean; description?: string })[]`                                  | -          |
| `modelValue`  | `string`                                                                                                                   | -          |
| `disabled`    | `boolean`                                                                                                                  | `false`    |
| `invalid`     | `boolean`                                                                                                                  | `false`    |
| `size`        | `'sm' | 'md' | 'lg'`                                                                                                       | `md`       |
| `color`       | `ColorRole` (built-in or registered semantic role)                                                                         | `primary`  |
| `orientation` | `'vertical' | 'horizontal'`                                                                                                | `vertical` |
| `variant`     | `'default' | 'card'`                                                                                                       | `default`  |
| `ui`          | `Partial<Record<'root' | 'itemWrapper' | 'item' | 'indicator' | 'label' | 'description' | 'labelGroup', string | object>>` | -          |

## Slots

| Slot    | Props                         | Description                                                                                                                                                                     |
| ------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | `{ item, checked, disabled }` | Replaces an item's whole label block (its label text and, if set, `description`) - useful for a price, badge, or other rich content (default: the item's `label`/`description`) |


# Rating

## Usage

`v-model` is a plain `number` between `0` and `length` (`5` by
default):


```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <SRating v-model="value" aria-label="Rate your experience" />
</template>
```


```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <SRating v-model="value" aria-label="Rate your experience" />
</template>
```

### Half-star precision

`step` sets how fine-grained a single star's own value can be - one of
`1` (default), `0.5`, `0.25`, or `0.1`. `0.5` splits each star into a
left (half) and right (whole) half, each its own clickable region:


```vue
<script setup lang="ts">
const value = ref(3.5)
</script>

<template>
  <SRating v-model="value" :step="0.5" aria-label="Rate your experience" />
</template>
```


```vue-html
<SRating v-model="value" :step="0.5" />
```

### Clearable

Clicking the currently-selected star again resets the value to `0`:


```vue
<script setup lang="ts">
const value = ref(4)
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SRating v-model="value" clearable aria-label="Rate your experience" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ value === 0 ? 'No rating' : `${value} out of 5` }} - click the current star again to clear
    </p>
  </div>
</template>
```


```vue-html
<SRating v-model="value" clearable />
```

### Sizes


```vue
<script setup lang="ts">
const sizes = ['sm', 'md', 'lg'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SRating v-for="size in sizes" :key="size" :default-value="4" :size="size" :aria-label="size" />
  </div>
</template>
```


```vue-html
<SRating :default-value="4" size="lg" />
```

### Color


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-3">
    <SRating v-for="color in colors" :key="color" :default-value="4" :color="color" :aria-label="color" />
  </div>
</template>
```


```vue-html
<SRating :default-value="4" color="success" />
```

### Read-only display

`disabled` blocks interaction entirely - paired with a fractional
`model-value`/`step`, this is the same component used purely to
*display* a rating (an average review score, for one), not just collect
one:


```vue
<template>
  <SRating :model-value="4.5" :step="0.5" disabled aria-label="4.5 out of 5" />
</template>
```


```vue-html
<SRating :model-value="4.5" :step="0.5" disabled aria-label="4.5 out of 5" />
```

### Vertical


```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <SRating v-model="value" orientation="vertical" aria-label="Rate your experience" />
</template>
```


```vue-html
<SRating v-model="value" orientation="vertical" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` falls back to
FormField's own state when not set directly on the rating, and `size`
does the same.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Rating`'s own theme file:

:theme-source{name="rating"}

## Props

| Prop           | Type                                                                              | Default      |
| -------------- | --------------------------------------------------------------------------------- | ------------ |
| `id`           | `string`                                                                          | -            |
| `modelValue`   | `number`                                                                          | -            |
| `defaultValue` | `number`                                                                          | -            |
| `length`       | `number`                                                                          | `5`          |
| `step`         | `1 | 0.5 | 0.25 | 0.1`                                                            | `1`          |
| `clearable`    | `boolean`                                                                         | `false`      |
| `hoverable`    | `boolean`                                                                         | `true`       |
| `disabled`     | `boolean`                                                                         | `false`      |
| `invalid`      | `boolean`                                                                         | `false`      |
| `orientation`  | `'horizontal' | 'vertical'`                                                       | `horizontal` |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `md`         |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary`    |
| `name`         | `string`                                                                          | -            |
| `required`     | `boolean`                                                                         | `false`      |
| `ui`           | `Partial<Record<RatingSlot, string | object>>`                                    | -            |

## Events

| Event               | Payload  | Description                                 |
| ------------------- | -------- | ------------------------------------------- |
| `update:modelValue` | `number` | Fires when a star (or half-star) is clicked |


# Select

## Usage

`items` accepts primitive string/number arrays or option objects. A primitive
is both its displayed label and model value; numbers must be finite, and
numeric `1` and string `"1"` remain distinct. Object options display `label`
by default. If an object has a `value` field, that field is its model value;
otherwise the complete object is the model value. Set `labelKey` or `valueKey`
to use different fields.

```vue
<script setup lang="ts">
const role = ref('admin')
const count = ref(0)
const roles = ['admin', 'editor', 'viewer']
const counts = [0, 1, 2]
</script>

<template>
  <SSelect v-model="role" :items="roles" />
  <SSelect v-model="count" :items="counts" />
</template>
```

Use `modelValue` for parent-controlled selection or `defaultValue` for an
uncontrolled initial selection. A form reset restores `defaultValue` (or the
empty selection) and emits an update; a controlled parent decides whether to
accept it. Pass `name` to submit one field per selected value. Primitive values
are submitted as strings and object values as JSON. An empty selection submits
no fields; disabled controls submit none. Use `form` to associate the control
with an external form ID.


```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry', disabled: true },
]
</script>

<template>
  <SSelect v-model="fruit" placeholder="Pick a fruit" :items="fruitItems" />
</template>
```


New selections come from `items`; for free text with suggestions, use
[Autocomplete](https://selarasui.my.id/components/forms/autocomplete) instead. An async or
parent-controlled selection may temporarily name an identity whose option has
not loaded yet; Select retains that identity and uses its text as a fallback.

```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry', disabled: true },
]
</script>

<template>
  <SSelect v-model="fruit" placeholder="Pick a fruit" :items="fruitItems" />
</template>
```

Selected options always show a checkmark in the list, via Reka UI's
`ComboboxItemIndicator` - this is on by default rather than an opt-in
alternative to a highlighted row.

### Filtering

Clicking anywhere on the trigger opens it - not just an icon. When `searchable`
is set, the filter input lives inside the popover, not in the trigger itself.


```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry', disabled: true },
]
</script>

<template>
  <SSelect v-model="fruit" searchable placeholder="Pick a fruit" :items="fruitItems" />
</template>
```


```vue-html
<SSelect v-model="fruit" searchable placeholder="Pick a fruit" :items="fruitItems" />
```

### Multiple selection

`multiple` turns `modelValue` into an array of option identities, preserving
string and numeric values. `displayMode` controls how selected values render
in the trigger - `comma` (default) joins labels as text, `chip` renders
removable pills. Both modes truncate at `maxChips` (default 3) and show a "+N
more" summary - hovering it reveals the rest in a tooltip, and clicking it
still opens the popover like the rest of the trigger.


```vue
<script setup lang="ts">
const fruits = ref(['apple', 'banana', 'cherry'])

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
  { label: 'Date', value: 'date' },
  { label: 'Elderberry', value: 'elderberry' },
]
</script>

<template>
  <SSelect v-model="fruits" multiple :max-chips="2" :items="fruitItems" />
</template>
```


```vue-html
<SSelect v-model="fruits" multiple :max-chips="2" :items="fruitItems" />
```


```vue
<script setup lang="ts">
const fruits = ref(['apple', 'banana', 'cherry'])

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
  { label: 'Date', value: 'date' },
  { label: 'Elderberry', value: 'elderberry' },
]
</script>

<template>
  <SSelect v-model="fruits" multiple display-mode="chip" :max-chips="2" :items="fruitItems" />
</template>
```


```vue-html
<SSelect v-model="fruits" multiple display-mode="chip" :max-chips="2" :items="fruitItems" />
```

### Changing selection mode

For an uncontrolled Select, changing `multiple` converts its local selection
once: single `value` becomes `[value]`, single `undefined` becomes `[]`, a
multiple selection becomes its first value, and an empty array becomes
`undefined`. Switching to single mode drops later active selections. That
conversion emits one `update:modelValue` event.

`defaultValue` is captured at mount and is not retargeted by later prop
changes. A native reset projects that captured default into the current mode:
with `defaultValue: [0, 1]`, reset in single mode yields `0`; after changing
back to multiple mode, reset yields `[0, 1]` again.

A controlled parent must change `modelValue` and `multiple` in the same render:
an array when `multiple` is true, and a scalar or `undefined` when it is false.
`undefined` is allowed as the empty multiple value. A scalar value in
multiple mode, or any array in single mode, throws a descriptive error. Select
also requires every value in a multiple `modelValue` or `defaultValue` array to
be unique. This includes unresolved async identities; numeric `1` and string
`'1'` are distinct values.
does not convert controlled values or emit an update solely because the mode
changed.

### Checkbox selection

There's no separate "checkbox mode" prop - the `item` slot already gives you
the option to render whatever you want per row, including a purely visual
[Checkbox](https://selarasui.my.id/components/forms/checkbox) that mirrors the row's selected state:


```vue
<script setup lang="ts">
const fruits = ref(['apple'])

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SSelect v-model="fruits" multiple :items="fruitItems" placeholder="Pick fruits">
    <template #item="{ item }">
      <SCheckbox :model-value="fruits.includes(item.value)" class="pointer-events-none" tabindex="-1" />
      {{ item.label }}
    </template>
  </SSelect>
</template>
```


```vue-html
<SSelect v-model="fruits" multiple :items="fruitItems">
  <template #item="{ item }">
    <SCheckbox :model-value="fruits.includes(item.value)" class="pointer-events-none" tabindex="-1" />
    {{ item.label }}
  </template>
</SSelect>
```

The checkbox is decorative (`pointer-events-none`, `tabindex="-1"`) - clicking
the row is still what drives selection, same as any other option.

### Clear

`clearable` adds a button that resets the selection - `undefined` for a single
select, an empty array for `multiple`. It only renders once there's something
to clear, and clicking it never opens the popover.


```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SSelect v-model="fruit" clearable placeholder="Pick a fruit" :items="fruitItems" />
</template>
```


```vue-html
<SSelect v-model="fruit" clearable placeholder="Pick a fruit" :items="fruitItems" />
```

### Custom option rendering

The `item` slot replaces an option's content in the list (and doubles as a
chip's content in `displayMode="chip"`); the `value` slot replaces the
trigger's own display for a single select. Together they let a select carry
more than plain text end to end:


```vue
<script setup lang="ts">
const status = ref('online')

const statusItems = [
  { label: 'Online', value: 'online', color: 'bg-[var(--selaras-resolved-color-success-fill)]' },
  { label: 'Away', value: 'away', color: 'bg-[var(--selaras-resolved-color-warning-fill)]' },
  { label: 'Offline', value: 'offline', color: 'bg-[var(--selaras-resolved-text-muted)]' },
]
</script>

<template>
  <SSelect v-model="status" :items="statusItems">
    <template #item="{ item }">
      <span class="size-2 rounded-full" :class="item.color" />
      {{ item.label }}
    </template>
    <template #value="{ selected }">
      <span v-if="selected" class="inline-flex items-center gap-2">
        <span class="size-2 rounded-full" :class="selected.raw?.color" />
        {{ selected.label }}
      </span>
    </template>
  </SSelect>
</template>
```


```vue-html
<SSelect v-model="status" :items="statusItems">
  <template #item="{ item }">
    <span class="size-2 rounded-full" :class="item.color" />
    {{ item.label }}
  </template>
  <template #value="{ selected }">
    <span v-if="selected" class="inline-flex items-center gap-2">
      <span class="size-2 rounded-full" :class="selected.raw?.color" />
      {{ selected.label }}
    </span>
  </template>
</SSelect>
```

### Custom objects

Select infers its model and update event from the option identity field. Set
`valueKey` to use a specific field; without it, `value` is used when present,
and the complete object is used when it is absent. `labelKey` defaults to
`label`. Single selection emits the selected identity or object, `multiple`
emits an array, and a dynamic boolean accepts either shape. Readonly arrays
and groups are supported. Every identity must be unique across the whole list,
including disabled options and options in different groups; a duplicate throws
when Select reads the options. Numeric `1` and string `'1'` are distinct
identities.
Records with both a string `label` and an `items` array represent groups; avoid
that reserved combination on individual options.

For async options, declare the item type even when the array starts empty.
Missing selected values remain intact until an option loads. The `value` slot
receives `selected.raw` as `undefined` during that time; use optional chaining
when reading metadata. The `item` slot receives a complete option, and an
unresolved object selection can still display its configured label field.

The exported types take an option entry type: `SelectProps<number>` describes
numeric primitive items, while `SelectProps<{ value: number, label: string }>`
describes option records. Author object items as a readonly `Row[]`, or as
`readonly (Row | SelectGroup<Row>)[]` when mixing
options and groups; there are no separate `SelectItems`, `SelectOption`, or
`SelectOptionGroup` authoring aliases. A wrapper that needs the exact validated
items type can use `SelectProps<Row, 'id'>['items']`. Custom keys and multiple
mode can be declared as `SelectProps<Row, 'id', true>`; `SelectEmits` uses the
same parameters. Render functions can specialize the component directly with
`h(Select<Row, 'id', true>, props)`. Template consumers normally need no explicit
generic parameters.

Import public helpers from `@sewadah/selaras/types`. `SelectEntryItem`,
`SelectEntryGroup`, and `SelectIdentityKeys` are removed internal mechanics;
derive slot types through `SelectSlots` (or `AutocompleteSlots`). The internal
normalization functions `useComboboxSelect`, `flattenItems`, and `isOptionGroup`
are no longer auto-imported.

`items` doesn't have to be `{ label, value }` - point `labelKey`/`valueKey` at
whatever fields your data already has:


```vue
<script setup lang="ts">
const userId = ref('')

const users = [
  { id: '1', fullName: 'Ada Lovelace' },
  { id: '2', fullName: 'Grace Hopper' },
  { id: '3', fullName: 'Margaret Hamilton' },
]
</script>

<template>
  <SSelect v-model="userId" placeholder="Pick a user" :items="users" label-key="fullName" value-key="id" />
</template>
```


```vue-html
<SSelect
  v-model="userId"
  :items="users"
  label-key="fullName"
  value-key="id"
/>
```

### Grouped options

Nest string, number, or object options under `{ label, items }` entries:


```vue
<script setup lang="ts">
const value = ref('')

const items = [
  { label: 'Fruits', items: [{ label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }] },
  { label: 'Vegetables', items: [{ label: 'Carrot', value: 'carrot' }, { label: 'Potato', value: 'potato' }] },
]
</script>

<template>
  <SSelect v-model="value" placeholder="Pick one" :items="items" />
</template>
```


```js
const items = [
  { label: 'Fruits', items: ['Apple', 'Banana'] },
  { label: 'Vegetables', items: [{ label: 'Carrot', value: 'carrot' }] },
]
```

The group header is plain text by default, but the `group` slot can replace
it entirely - it receives the whole `{ label, items }` entry:


```vue
<script setup lang="ts">
const value = ref('')

const items = [
  { label: 'Fruits', items: [{ label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }] },
  { label: 'Vegetables', items: [{ label: 'Carrot', value: 'carrot' }, { label: 'Potato', value: 'potato' }] },
]
</script>

<template>
  <SSelect v-model="value" placeholder="Pick one" :items="items">
    <template #group="{ group }">
      <span class="flex items-center justify-between">
        <span>{{ group.label }}</span>
        <span class="text-[var(--selaras-resolved-text-muted)]">{{ group.items.length }}</span>
      </span>
    </template>
  </SSelect>
</template>
```


```vue-html
<SSelect :items="items">
  <template #group="{ group }">
    <span class="flex items-center justify-between">
      <span>{{ group.label }}</span>
      <span class="text-[var(--selaras-resolved-text-muted)]">{{ group.items.length }}</span>
    </span>
  </template>
</SSelect>
```

### Virtualization

For large option lists, `virtualize` renders only the visible rows (backed by
`@tanstack/vue-virtual` via Reka UI's `ComboboxVirtualizer`). Pass `true` for
defaults, or an object to tune `estimateSize`/`overscan`.


```vue
<script setup lang="ts">
const value = ref('')

const manyItems = Array.from({ length: 5000 }, (_, i) => ({ label: `Item ${i + 1}`, value: `item-${i + 1}` }))
</script>

<template>
  <SSelect v-model="value" searchable virtualize placeholder="Pick an item" :items="manyItems" />
</template>
```


```vue-html
<SSelect v-model="value" searchable virtualize :items="fiveThousandItems" />
```

One caveat: virtualizing a grouped `items` list flattens the groups (a Reka UI
limitation) - group headers won't render while virtualized.

This only windows what's already in `items` - it doesn't fetch more data as
you scroll. There's no built-in lazy-loading of additional pages; fetch or
page into `items` yourself if the full set can't live in memory.

### Search text

The popover's search field is a pure filter, not a display of the current
selection - it always resets to empty when you pick an option or close the
popover. Bind `v-model:search-term` if you need to read or control the typed
text yourself (e.g. to drive a remote search):

```vue-html
<SSelect v-model="fruit" v-model:search-term="query" searchable :items="fruitItems" />
```

`resetSearchTermOnBlur`/`resetSearchTermOnSelect` (both default `true`,
forwarded from Reka UI's `ComboboxRoot`) control whether it resets at all -
set either to `false` if you're driving the field yourself and don't want it
cleared out from under you.

### Sizes

`size` takes `sm` / `md` / `lg`, matching every other form control in this
library - see the [Props](https://selarasui.my.id/#props) table below.

### States

`loading` swaps the trailing chevron for a spinner (the trigger stays
clickable - it doesn't disable the select), `disabled` prevents opening it
entirely, and `invalid` switches the ring to the danger role's focus color. All three compose
with everything above them on this page - see [Props](https://selarasui.my.id/#props).

### Colors

`color` sets the focus-ring color - the resting (unfocused) ring stays
`--selaras-resolved-border-default` regardless, and `invalid` always wins over a custom `color`:


```vue
<script setup lang="ts">
const items = ['Apple', 'Banana', 'Cherry'].map(label => ({ value: label, label }))
const primary = ref()
const success = ref()
const danger = ref()
</script>

<template>
  <div class="flex w-full max-w-xs flex-col gap-4">
    <SSelect v-model="primary" :items="items" color="primary" placeholder="Primary" />
    <SSelect v-model="success" :items="items" color="success" placeholder="Success" />
    <SSelect v-model="danger" :items="items" color="danger" placeholder="Danger" />
  </div>
</template>
```


```vue-html
<SSelect v-model="primary" color="primary" :items="items" />
<SSelect v-model="success" color="success" :items="items" />
<SSelect v-model="danger" color="danger" :items="items" />
```

### Arrow

`arrow` shows a small pointer triangle connecting the panel to its trigger.
An object sets its width, height, rounded tip, or corner clearance
(`padding`):


```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SSelect v-model="fruit" arrow placeholder="Pick a fruit" :items="fruitItems" />
</template>
```


```vue-html
<SSelect v-model="fruit" arrow :items="items" />
<SSelect v-model="fruit" :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }" :items="items" />
```

### Adaptive presentation

`adaptive` switches the popover to a centered [Modal](https://selarasui.my.id/components/overlays/modal)
below your configured adaptive breakpoint. It is opt-in (defaults `false`),
chooses the presentation on open, and holds it until close:


```vue
<script setup lang="ts">
const fruit = ref('apple')

const fruitItems = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
]
</script>

<template>
  <SSelect v-model="fruit" adaptive placeholder="Pick a fruit" :items="fruitItems" />
</template>
```


### Panel positioning and portal

Use `positioning` for the anchored list's side, alignment, offsets, and collision
behavior. `portal` defaults to the document body; set it to `false` to render
inline, or to a CSS selector or `HTMLElement` to choose a teleport target.
These options affect the anchored list; the adaptive Select modal has its own
presentation. Use `ui.content` for visual styling.

```vue-html
<SSelect :items="fruitItems" :positioning="{ side: 'top', align: 'end', sideOffset: 8 }" portal="#overlay-root" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` and `size` both fall
back to FormField's own state when not set directly on the select.

### Accessibility

Select renders Reka UI's Combobox primitive, so the accessibility semantics
come from there rather than being reimplemented here: the trigger/search
input exposes `role="combobox"` with `aria-expanded`/`aria-controls`, each
option is `role="option"`, and each group is `aria-labelledby` its header.
Arrow keys move the highlighted option, :kbd[Enter] selects it,
:kbd[Escape] closes the popover, and typing while closed (or while
`searchable`) filters the list - all standard behavior for the
[ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/){rel="&#x22;nofollow&#x22;"},
not something to configure here.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Select`'s own theme file:

Global and scoped overrides use `ui.select`; Autocomplete intentionally reads
the same key because both components use this recipe.

:theme-source{name="select"}

### Custom leading and trailing content

Use `#leading` and `#trailing` for text, icons, or buttons inside the field frame.
The slots receive `{ disabled, size, buttonSize }`; `buttonSize` fits a Button
inside the current field size. Give interactive controls an accessible label,
use `type="button"`, and pass `disabled` through to match the field state.

Custom content stays visible alongside the built-in clear button, loading indicator, and dropdown control.
The field reserves space for the rendered content, including suffixes whose
width changes. Use `ui.leading` and `ui.trailing` to customize its wrappers.


```vue
<script setup lang="ts">
const currency = ref<'IDR' | 'USD' | 'EUR'>('IDR')
const details = ref(false)
</script>

<template>
  <div class="w-full max-w-sm space-y-2">
    <SSelect v-model="currency" :items="['IDR', 'USD', 'EUR']" clearable aria-label="Currency">
      <template #leading>
        <span class="text-xs">Pay in</span>
      </template>
      <template #trailing="{ disabled, buttonSize }">
        <SButton type="button" :disabled="disabled" :size="buttonSize" variant="text" color="neutral" square icon="hugeicons:information-circle" aria-label="Currency details" :aria-pressed="details" @click="details = !details" />
      </template>
    </SSelect>
    <p v-if="details" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Choose the currency used for your payment.
    </p>
  </div>
</template>
```


Custom controls render outside the trigger button, so they can receive keyboard
focus without creating nested buttons or opening the options list on click.
With `adaptive`, these slots customize the original field; the modal retains
its dedicated search and selection controls.

## Props

| Prop                      | Type                                                                              | Default                                                         |
| ------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `id`                      | `string`                                                                          | -                                                               |
| `name`                    | `string`                                                                          | -                                                               |
| `items`                   | `readonly Entry[]`                                                                | -                                                               |
| `valueKey` / `labelKey`   | `string`                                                                          | `'value'` when present, otherwise the option object / `'label'` |
| `modelValue`              | identity, identity array, or `undefined`                                          | -                                                               |
| `multiple`                | `boolean`                                                                         | `false`                                                         |
| `searchable`              | `boolean`                                                                         | `false`                                                         |
| `searchTerm`              | `string`                                                                          | -                                                               |
| `resetSearchTermOnBlur`   | `boolean`                                                                         | `true`                                                          |
| `resetSearchTermOnSelect` | `boolean`                                                                         | `true`                                                          |
| `virtualize`              | `boolean | { estimateSize?: number; overscan?: number }`                          | `false`                                                         |
| `displayMode`             | `'comma' | 'chip'`                                                                | `'comma'`                                                       |
| `maxChips`                | `number`                                                                          | `3`                                                             |
| `clearable`               | `boolean`                                                                         | `false`                                                         |
| `loading`                 | `boolean`                                                                         | `false`                                                         |
| `placeholder`             | `string`                                                                          | -                                                               |
| `disabled`                | `boolean`                                                                         | `false`                                                         |
| `size`                    | `'sm' | 'md' | 'lg'`                                                              | `md`                                                            |
| `invalid`                 | `boolean`                                                                         | `false`                                                         |
| `color`                   | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary`                                                       |
| `arrow`                   | `boolean | RoundedArrowConfig`                                                    | `false`                                                         |
| `positioning`             | `OverlayPositioning`                                                              | anchored list defaults                                          |
| `portal`                  | `boolean | string | HTMLElement`                                                  | `true` (document body)                                          |
| `adaptive`                | `boolean`                                                                         | `false`                                                         |
| `ui`                      | `Partial<Record<SelectSlot, string | object>>`                                    | -                                                               |

## Slots

| Slot                   | Props                            | Description                                                                  |
| ---------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `leading` / `trailing` | `{ disabled, size, buttonSize }` | Custom field content alongside built-in controls                             |
| `item`                 | `{ item }`                       | Custom option rendering (also used for chips)                                |
| `value`                | `{ selected }`                   | Custom trigger display (single-select only)                                  |
| `group`                | `{ group }`                      | Custom group header (replaces the plain label text)                          |
| `empty`                | -                                | Shown when `items` is empty                                                  |
| `empty-filter`         | -                                | Shown when a search yields no matches                                        |
| `header` / `footer`    | -                                | Content above/below the option list                                          |
| `clear-icon`           | -                                | Replaces the clear button's icon (default: `hugeicons:cancel-01`)            |
| `dropdown-icon`        | -                                | Replaces the trigger's chevron (default: `hugeicons:arrow-down-01`)          |
| `loading-icon`         | -                                | Replaces the spinner shown while `loading` (default: `hugeicons:loading-02`) |
| `filter-icon`          | -                                | Replaces the popover search field's icon (default: `hugeicons:search-01`)    |


# Slider

## Usage

`v-model` is a plain `number` for a single handle:


```vue
<script setup lang="ts">
const value = ref(30)
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SSlider v-model="value" aria-label="Volume" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ value }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const value = ref(30)
</script>

<template>
  <SSlider v-model="value" aria-label="Volume" />
</template>
```

### Range

Pass an array instead to get a range slider with one handle per entry -
`minStepsBetweenThumbs` keeps them from crossing (or getting closer than
that many steps apart). The value you get back always matches the shape
you passed in - an array in, an array out:


```vue
<script setup lang="ts">
const priceRange = ref([20, 80])
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SSlider v-model="priceRange" :min-steps-between-thumbs="5" :aria-label="['Minimum price', 'Maximum price']" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      ${{ priceRange[0] }} - ${{ priceRange[1] }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const priceRange = ref([20, 80])
</script>

<template>
  <SSlider v-model="priceRange" :min-steps-between-thumbs="5" />
</template>
```

### Min, max, and step

`min`/`max` (default `0`/`100`) bound the value, `step` (default `1`)
controls the increment - both the drag and the arrow keys snap to it.

### Ticks

`show-ticks` marks every step along the track - a Selaras addition, not
part of Reka's own primitive:


```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <SSlider v-model="value" :step="25" show-ticks aria-label="Quality" />
</template>
```


```vue-html
<SSlider v-model="value" :step="25" show-ticks />
```

### Color


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <SSlider v-for="color in colors" :key="color" :model-value="60" :color="color" :aria-label="color" />
  </div>
</template>
```


```vue-html
<SSlider :model-value="60" color="danger" />
```

### Vertical

`orientation="vertical"` needs a real height to size against - the theme
gives it a sensible default (override via `:ui.root` for a taller/shorter
one):


```vue
<script setup lang="ts">
const value = ref(40)
</script>

<template>
  <SSlider v-model="value" orientation="vertical" aria-label="Height" />
</template>
```


```vue-html
<SSlider v-model="value" orientation="vertical" />
```

### Inverted

`inverted` visually (and directionally) flips the slider - the max end
renders where the min end normally would, and dragging is reversed to
match:


```vue
<script setup lang="ts">
const value = ref(30)
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <SSlider v-model="value" aria-label="Volume" />
    <SSlider v-model="value" inverted aria-label="Volume (inverted)" />
  </div>
</template>
```


```vue-html
<SSlider v-model="value" inverted aria-label="Volume (inverted)" />
```

### Thumb variant

`thumb-variant="bar"` swaps the default circular thumb for a thin bar,
sized off the track's own `size` and `orientation`:


```vue
<script setup lang="ts">
const value = ref(30)
</script>

<template>
  <SSlider v-model="value" thumb-variant="bar" aria-label="Volume" />
</template>
```


```vue-html
<SSlider v-model="value" thumb-variant="bar" />
```

### Start and end slots

`#start`/`#end` render content flanking the track - an icon, an emoji,
a unit label:


```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <SSlider v-model="value" aria-label="Rate your experience">
      <template #start>
        😞
      </template>
      <template #end>
        😄
      </template>
    </SSlider>
    <p class="text-center text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ value < 33 ? 'Not great' : value < 67 ? 'Okay' : 'Great' }}
    </p>
  </div>
</template>
```


```vue-html
<SSlider v-model="value">
  <template #start>😞</template>
  <template #end>😄</template>
</SSlider>
```

### Tooltip

`tooltip` wraps each thumb in a tooltip showing its current value on
hover or focus:


```vue
<script setup lang="ts">
const value = ref(30)
</script>

<template>
  <SSlider v-model="value" tooltip aria-label="Volume" />
</template>
```


```vue-html
<SSlider v-model="value" tooltip />
```

### Controls

`controls` adds `-`/`+` buttons flanking the track that step the value
by `step`, disabling at `min`/`max` - only rendered for a single-value
slider, since stepping two independent range thumbs with one shared
button pair has no obvious single meaning:


```vue
<script setup lang="ts">
const value = ref(105)
</script>

<template>
  <div class="flex w-full flex-col gap-2">
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ value }} credits/mo
    </p>
    <SSlider v-model="value" :min="0" :max="500" :step="5" controls aria-label="Credits per month" />
  </div>
</template>
```


```vue-html
<SSlider v-model="value" controls />
```

### Side labels

Plain text either side of the track composes with no extra API:


```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <div class="flex w-full items-center gap-3">
    <span class="text-sm text-[var(--selaras-resolved-text-muted)]">Low</span>
    <SSlider v-model="value" aria-label="Priority" />
    <span class="text-sm text-[var(--selaras-resolved-text-muted)]">High</span>
  </div>
</template>
```


```vue-html
<div class="flex items-center gap-3">
  <span>Low</span>
  <SSlider v-model="value" />
  <span>High</span>
</div>
```

### Paired with a number input

`SSlider` and `SInputNumber` sharing one `v-model` gives an exact,
typeable value alongside the drag control:


```vue
<script setup lang="ts">
const value = ref(25)
</script>

<template>
  <div class="flex w-full items-center gap-3">
    <SSlider v-model="value" aria-label="Quantity" />
    <SInputNumber v-model="value" :min="0" :max="100" class="w-24 shrink-0" />
  </div>
</template>
```


```vue-html
<div class="flex items-center gap-3">
  <SSlider v-model="value" />
  <SInputNumber v-model="value" :min="0" :max="100" />
</div>
```

### Accessible labeling

A slider thumb has no visible text of its own, so it needs an accessible
name from somewhere. `aria-label` (a single string) applies to every
thumb - fine for a single-handle slider. For a range slider, Reka's own
primitive already falls back to "Minimum"/"Maximum" for a two-thumb
slider with no label at all; pass an array to `aria-label` to say
something more specific instead (`['Low priority', 'High priority']`, for
one):

```vue-html
<SSlider v-model="priceRange" :aria-label="['Minimum price', 'Maximum price']" />
```

### Committing vs. continuous updates

`update:model-value` (what `v-model` uses) fires continuously while
dragging. `value-commit` fires once, only when a drag finishes with an
actually-changed value - useful for anything that shouldn't run on every
intermediate frame, like a debounced request:

```vue-html
<SSlider v-model="value" @value-commit="(v) => fetchResultsFor(v)" />
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Slider`'s own theme file:

:theme-source{name="slider"}

## Props

| Prop                    | Type                                                                                                       | Default        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- |
| `modelValue`            | `number | number[]`                                                                                        | -              |
| `defaultValue`          | `number | number[]`                                                                                        | -              |
| `min`                   | `number`                                                                                                   | `0`            |
| `max`                   | `number`                                                                                                   | `100`          |
| `step`                  | `number`                                                                                                   | `1`            |
| `minStepsBetweenThumbs` | `number`                                                                                                   | -              |
| `disabled`              | `boolean`                                                                                                  | `false`        |
| `orientation`           | `'horizontal' | 'vertical'`                                                                                | `'horizontal'` |
| `inverted`              | `boolean`                                                                                                  | `false`        |
| `showTicks`             | `boolean`                                                                                                  | `false`        |
| `size`                  | `'sm' | 'md' | 'lg'`                                                                                       | `md`           |
| `color`                 | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                          | `primary`      |
| `thumbVariant`          | `'circle' | 'bar'`                                                                                         | `circle`       |
| `tooltip`               | `boolean`                                                                                                  | `false`        |
| `controls`              | `boolean`                                                                                                  | `false`        |
| `ariaLabel`             | `string | string[]`                                                                                        | -              |
| `name`                  | `string` (submitted via a hidden input Reka renders internally - only takes effect inside a real `<form>`) | -              |
| `ui`                    | `Partial<Record<SliderSlot, string | object>>`                                                             | -              |

## Events

| Event               | Payload             | Description                                           |
| ------------------- | ------------------- | ----------------------------------------------------- |
| `update:modelValue` | `number | number[]` | Fires continuously while dragging                     |
| `valueCommit`       | `number | number[]` | Fires once, when a drag finishes with a changed value |

## Slots

| Slot    | Props | Description                             |
| ------- | ----- | --------------------------------------- |
| `start` | -     | Content flanking the start of the track |
| `end`   | -     | Content flanking the end of the track   |


# Switch

## Usage


```vue
<script setup lang="ts">
const notifications = ref(true)
</script>

<template>
  <SSwitch v-model="notifications" label="Notifications" />
</template>
```


```vue
<script setup lang="ts">
const notifications = ref(true)
</script>

<template>
  <SSwitch v-model="notifications" label="Notifications" />
</template>
```

### States

`disabled` prevents interaction and dims it, and `invalid` switches the
track to the danger semantic role:


```vue
<script setup lang="ts">
const disabledOff = ref(false)
const disabledOn = ref(true)
const invalidChoice = ref(false)
</script>

<template>
  <div class="flex flex-col gap-4">
    <SSwitch v-model="disabledOff" disabled label="Disabled" />
    <SSwitch v-model="disabledOn" disabled label="Disabled, on" />
    <SSwitch v-model="invalidChoice" invalid label="You must enable this to continue" />
  </div>
</template>
```


```vue-html
<SSwitch v-model="disabledOff" disabled label="Disabled" />
<SSwitch v-model="disabledOn" disabled label="Disabled, on" />
<SSwitch v-model="invalidChoice" invalid label="You must enable this to continue" />
```

See [Props](https://selarasui.my.id/#props).

### Sizes

`size` takes `sm` / `md` / `lg`, scaling the track, thumb, and label
together:


```vue
<script setup lang="ts">
const sm = ref(true)
const md = ref(true)
const lg = ref(true)
</script>

<template>
  <div class="flex items-center gap-4">
    <SSwitch v-model="sm" size="sm" label="Small" />
    <SSwitch v-model="md" size="md" label="Medium" />
    <SSwitch v-model="lg" size="lg" label="Large" />
  </div>
</template>
```


```vue-html
<SSwitch v-model="sm" size="sm" label="Small" />
<SSwitch v-model="md" size="md" label="Medium" />
<SSwitch v-model="lg" size="lg" label="Large" />
```

### Colors

`color` sets the checked-state track/thumb color - unchecked always stays
the same neutral track regardless:


```vue
<script setup lang="ts">
const primary = ref(true)
const success = ref(true)
const danger = ref(true)
</script>

<template>
  <div class="flex flex-col gap-4">
    <SSwitch v-model="primary" color="primary" label="Primary" />
    <SSwitch v-model="success" color="success" label="Success" />
    <SSwitch v-model="danger" color="danger" label="Danger" />
  </div>
</template>
```


```vue-html
<SSwitch v-model="primary" color="primary" label="Primary" />
<SSwitch v-model="success" color="success" label="Success" />
<SSwitch v-model="danger" color="danger" label="Danger" />
```

### Loading

`loading` shows a spinner in the thumb - useful while an async toggle (an
API call behind the switch) is in flight. It doesn't imply `disabled` -
combine `:loading="x" :disabled="x"` if a busy switch shouldn't be
touchable in the meantime:


```vue
<script setup lang="ts">
const enabled = ref(false)
const loading = ref(false)

async function onUpdate(value: boolean) {
  loading.value = true
  await new Promise(resolve => setTimeout(resolve, 800))
  enabled.value = value
  loading.value = false
}
</script>

<template>
  <SSwitch :model-value="enabled" :loading="loading" label="Sync with server" @update:model-value="onUpdate" />
</template>
```


```vue-html
<SSwitch :model-value="enabled" :loading="loading" label="Sync with server" @update:model-value="onUpdate" />
```

### Icons

`checked-icon`/`unchecked-icon` render inside the thumb for each state -
useful when a plain on/off doesn't read as clearly as a semantic pair of
icons:


```vue
<script setup lang="ts">
const airplaneMode = ref(true)
</script>

<template>
  <SSwitch
    v-model="airplaneMode"
    checked-icon="hugeicons:airplane-mode"
    unchecked-icon="hugeicons:airplane-mode-off"
    label="Airplane mode"
  />
</template>
```


```vue-html
<SSwitch v-model="airplaneMode" checked-icon="hugeicons:airplane-mode" unchecked-icon="hugeicons:airplane-mode-off" label="Airplane mode" />
```

### Description

`description` adds a second, muted line under the label - for a
standalone toggle (a settings list, say) where wrapping every switch in
its own [FormField](https://selarasui.my.id/components/forms/form-field) would be needless
ceremony:


```vue
<script setup lang="ts">
const marketing = ref(false)
</script>

<template>
  <SSwitch
    v-model="marketing"
    label="Marketing emails"
    description="Occasional product updates and offers - unsubscribe any time."
  />
</template>
```


```vue-html
<SSwitch v-model="marketing" label="Marketing emails" description="Occasional product updates and offers - unsubscribe any time." />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid` and
`aria-describedby` wired up automatically - `invalid` falls back to
FormField's own state when not set directly on the switch, and `size`
does the same (matching RadioGroup's own inheritance).

### Accessibility

Switch renders Reka UI's Switch primitive, so the accessibility semantics
come from there rather than being reimplemented here: `role="switch"` with
a boolean `aria-checked` (unlike Checkbox, there's no third "mixed" state).
It's a single native-equivalent control, so it's just one :kbd[Tab]
stop with no roving focus to manage, and :kbd[Space] toggles it -
standard behavior for the
[ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/){rel="&#x22;nofollow&#x22;"},
not something to configure here.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Switch`'s own theme file:

:theme-source{name="switch"}

## Props

| Prop            | Type                                                                                                             | Default     |
| --------------- | ---------------------------------------------------------------------------------------------------------------- | ----------- |
| `id`            | `string`                                                                                                         | -           |
| `name`          | `string`                                                                                                         | -           |
| `modelValue`    | `boolean`                                                                                                        | -           |
| `label`         | `string`                                                                                                         | -           |
| `description`   | `string`                                                                                                         | -           |
| `disabled`      | `boolean`                                                                                                        | `false`     |
| `invalid`       | `boolean`                                                                                                        | `false`     |
| `required`      | `boolean`                                                                                                        | `false`     |
| `size`          | `'sm' | 'md' | 'lg'`                                                                                             | `'md'`      |
| `color`         | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                | `'primary'` |
| `loading`       | `boolean`                                                                                                        | `false`     |
| `checkedIcon`   | `string`                                                                                                         | -           |
| `uncheckedIcon` | `string`                                                                                                         | -           |
| `ui`            | `Partial<Record<'root' | 'track' | 'thumb' | 'icon' | 'label' | 'description' | 'labelGroup', string | object>>` | -           |

## Slots

| Slot          | Description                             |
| ------------- | --------------------------------------- |
| default       | Custom content, overrides `label`       |
| `description` | Custom content, overrides `description` |


# Textarea

## Usage


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <STextarea v-model="value" placeholder="Write something..." />
</template>
```


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <STextarea v-model="value" placeholder="Write something..." />
</template>
```

Textarea is full-width by default, the same as [Input](https://selarasui.my.id/components/forms/input) -
constrain it with a class on the component itself, not a wrapping element.
Native `<textarea>` attributes not listed below (`maxlength`, `pattern`,
`readonly`, `spellcheck`, ...) already pass straight through to the real
element - no dedicated prop needed for them.

### Icons

`icon` and `trailingIcon` add an icon before or after the text, the same
props [Input](https://selarasui.my.id/components/forms/input#icons) uses for its own - anchored
to the top corner here rather than vertically centered, since centering
against the whole box would drift away from the first line once content
wraps past one line:


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <STextarea v-model="value" icon="hugeicons:chat" placeholder="Leave a comment..." />
</template>
```


```vue-html
<STextarea v-model="value" icon="hugeicons:chat" placeholder="Leave a comment..." />
```

### Custom leading and trailing content

Use `#leading` and `#trailing` for text, icons, or buttons inside the field frame.
The slots receive `{ disabled, size, buttonSize }`; `buttonSize` fits a Button
inside the current field size. Give interactive controls an accessible label,
use `type="button"`, and pass `disabled` through to match the field state.

Custom content stays visible alongside the built-in clear button. It replaces the corresponding decorative `icon` or `trailingIcon`.
The field reserves space for the rendered content, including suffixes whose
width changes. Use `ui.leading` and `ui.trailing` to customize its wrappers.


```vue
<script setup lang="ts">
const message = ref('A short note')
</script>

<template>
  <STextarea v-model="message" :maxlength="200" clearable aria-label="Note" class="max-w-sm" :ui="{ trailing: 'pe-3' }">
    <template #trailing>
      <span>{{ message.length }}/200</span>
    </template>
  </STextarea>
</template>
```


### Clear

`clearable` adds a button that empties the value, once there's something to
clear - the same behavior as [Input's](https://selarasui.my.id/components/forms/input#clear):


```vue
<script setup lang="ts">
const value = ref('Some text to clear')
</script>

<template>
  <STextarea v-model="value" clearable placeholder="Write something..." />
</template>
```


```vue-html
<STextarea v-model="value" clearable placeholder="Write something..." />
```

### Autoresize

`autoresize` grows the box to fit its content instead of a fixed height with
a scrollbar/drag-handle; `maxrows` caps how far it can grow before falling
back to a scrollbar (unset or `0` grows indefinitely). Manual resizing
(the drag-handle in the box's own corner) is disabled while `autoresize` is
on - the two would otherwise fight each other on the very next keystroke:


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <STextarea v-model="value" autoresize :maxrows="6" placeholder="Keep typing - this grows up to 6 rows, then scrolls..." />
</template>
```


```vue-html
<STextarea v-model="value" autoresize :maxrows="6" placeholder="Keep typing..." />
```

### Sizes and states

`size` takes `sm` / `md` / `lg`, `disabled` prevents interaction and dims the
textarea, and `invalid` switches the ring to the danger role's focus color:


```vue
<script setup lang="ts">
const value = ref('')
</script>

<template>
  <STextarea v-model="value" invalid placeholder="Write something..." />
</template>
```


```vue-html
<STextarea v-model="value" invalid placeholder="Write something..." />
```

See the [Props](https://selarasui.my.id/#props) table below.

### Colors

`color` sets the focus-ring color - the resting (unfocused) ring stays
`--selaras-resolved-border-default` regardless, and `invalid` always wins over a custom `color`:


```vue
<script setup lang="ts">
const primary = ref('')
const success = ref('')
const danger = ref('')
</script>

<template>
  <div class="flex w-full max-w-xs flex-col gap-4">
    <STextarea v-model="primary" color="primary" placeholder="Primary" />
    <STextarea v-model="success" color="success" placeholder="Success" />
    <STextarea v-model="danger" color="danger" placeholder="Danger" />
  </div>
</template>
```


```vue-html
<STextarea v-model="primary" color="primary" placeholder="Primary" />
<STextarea v-model="success" color="success" placeholder="Success" />
<STextarea v-model="danger" color="danger" placeholder="Danger" />
```

### Forms integration

Wrap it in [FormField](https://selarasui.my.id/components/forms/form-field) to get `id`/`name`/`invalid`
and `aria-describedby` wired up automatically, plus a `hint`/`error` message
underneath - FormField is also where `size` and `invalid` fall back to when
not set directly on the textarea.

### Accessibility

Textarea renders a plain native `<textarea>`, so browser and screen-reader
support for typing, selection, and autofill all come for free. `aria-invalid`
and `aria-describedby` are set automatically once `invalid` is true or the
textarea is wrapped in [FormField](https://selarasui.my.id/components/forms/form-field) - nothing
to configure by hand for the common case.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Textarea`'s own theme file:

:theme-source{name="textarea"}

## Props

| Prop           | Type                                                                                                                    | Default   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |
| `id`           | `string`                                                                                                                | -         |
| `name`         | `string`                                                                                                                | -         |
| `modelValue`   | `string`                                                                                                                | -         |
| `placeholder`  | `string`                                                                                                                | -         |
| `rows`         | `number`                                                                                                                | `3`       |
| `size`         | `'sm' | 'md' | 'lg'`                                                                                                    | `md`      |
| `disabled`     | `boolean`                                                                                                               | `false`   |
| `invalid`      | `boolean`                                                                                                               | `false`   |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'`                                       | `primary` |
| `clearable`    | `boolean`                                                                                                               | `false`   |
| `icon`         | `string`                                                                                                                | -         |
| `trailingIcon` | `string`                                                                                                                | -         |
| `autoresize`   | `boolean`                                                                                                               | `false`   |
| `maxrows`      | `number`                                                                                                                | -         |
| `ui`           | `Partial<Record<'root' | 'base' | 'leadingIcon' | 'trailingIcon' | 'leading' | 'trailing' | 'clear', string | object>>` | -         |

## Slots

| Slot         | Props                            | Description                                                                        |
| ------------ | -------------------------------- | ---------------------------------------------------------------------------------- |
| `leading`    | `{ disabled, size, buttonSize }` | Custom content before the text; replaces `icon`                                    |
| `trailing`   | `{ disabled, size, buttonSize }` | Custom content after the text, alongside the clear button; replaces `trailingIcon` |
| `clear-icon` | -                                | Replaces the clear button's icon (default: `hugeicons:cancel-01`)                  |


# TransferList

## Usage

TransferList separates available items from assigned items. `items` is the
complete collection; `v-model` contains the destination values. Checking a row
marks it for transfer, and pressing the add or remove arrow button updates the
destination model. The component never mutates the supplied collection.


```vue
<script setup lang="ts">
const assigned = ref([2])
const items = [
  { id: 1, name: 'Alex Morgan', description: 'Product designer' },
  { id: 2, name: 'Sam Lee', description: 'Software engineer' },
  { id: 3, name: 'Dina Sari', description: 'Project manager' },
  { id: 4, name: 'Taylor Kim', description: 'Workspace owner', disabled: true },
]
</script>

<template>
  <div class="w-full space-y-4">
    <STransferList v-model="assigned" :items="items" value-key="id" label-key="name" source-label="Available members" target-label="Project team" searchable />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Assigned member IDs: {{ assigned.join(', ') || 'None' }}
    </p>
  </div>
</template>
```


## Values and selection

Value rules match [Listbox](https://selarasui.my.id/components/forms/listbox) and Select: strings and
finite numbers are their own values; objects use `value` when present and
otherwise the whole object. Set `valueKey` and `labelKey` for custom fields.
Groups use `{ label, items }`, and identities must be unique across the collection.
Use a stable `valueKey` for records loaded from an API.

```vue-html
<STransferList v-model="assignedRoles" :items="['admin', 'editor', 'viewer']" />
<STransferList v-model="assignedIds" :items="users" value-key="id" label-key="name" />
```

Checked rows are internal by default. Bind `v-model:checked` when the application
needs to control them separately. Destination values absent from `items` are
preserved and appear in the assigned panel when their records arrive. Both
controlled models can reject updates without adopting the proposed state.

Disabled items cannot be checked or moved. Select all affects only visible,
enabled items in its panel. Transfer actions move all checked, enabled items
from that panel, including checked items hidden by a subsequent search.
Both panels retain the original collection order; model array order does not
reorder the displayed rows. Drag-and-drop and manual reordering are not provided.

## Search and layout

`searchable` adds independent label filters. Bind `v-model:source-search-term`
and `v-model:target-search-term` to control their text. Search preserves both
destination membership and checked rows.

`layout="auto"` places panels beside each other on larger screens and stacks
them on smaller screens. `horizontal` and `vertical` force a layout. The panels
remain inline; no modal presentation or adaptive prop is needed.

## Custom content

The `item` slot provides original item metadata, selection state, and `side`:


```vue
<script setup lang="ts">
const assigned = ref(['editor'])
const items = [
  { label: 'Administrator', value: 'admin', description: 'Full workspace access' },
  { label: 'Editor', value: 'editor', description: 'Create and edit content' },
  { label: 'Viewer', value: 'viewer', description: 'Read-only access' },
]
</script>

<template>
  <STransferList v-model="assigned" :items="items" source-label="Available roles" target-label="Assigned roles" class="w-full">
    <template #item="{ item, side }">
      <div class="min-w-0 flex-1">
        <p class="font-medium">
          {{ item.label }}
        </p>
        <p class="text-xs text-[var(--selaras-resolved-text-muted)]">
          {{ item.description }}
        </p>
      </div>
      <SBadge v-if="side === 'target'" size="sm" variant="soft" label="Assigned" />
    </template>
  </STransferList>
</template>
```


`source-header` and `target-header` receive `count` and `checkedCount`. Panel
footers and empty states are also customizable. Options should contain display
content rather than independently interactive links or buttons.

## Forms and accessibility

Use `name`, `form`, and `required` as with Listbox. Only destination values are
submitted; checked panel values are excluded. Object values serialize as JSON.
FormField supplies size, name, descriptions, and validation state.
Native reset restores the captured destination default and clears checked rows
and searches. Controlled parents receive reset proposals; canceled resets do
not update state.

Each panel has an accessible name from `sourceLabel` or `targetLabel`. Transfer
buttons use arrow icons with accessible labels and hover titles. Keyboard focus
moves to the receiving panel after
a transfer. A live region announces the number of transferred items.

The `transfer` event receives `{ direction, items, values }`, where direction is
`to-target` or `to-source` and the arrays contain only the moved items/values.
For a controlled model, events propose changes for the parent to accept.

## Styling and messages

Override `ui.transferList` for the layout and panel chrome; `ui.listbox` styles
the selection panels. Both support global app config, scoped Theme overrides,
and local `:ui` values. `ui.listbox` on a transfer instance can include attributes
such as `{ ui: { content: 'max-h-96' } }` to configure its panels.

Labels use the message registry: `transferSource`, `transferTarget`,
`moveToTarget`, `moveToSource`, `selectAll`, `listSelectionCount`, and
`transferItems`. Search and empty messages reuse `search`, `noOptions`, and
`noResultsFound`. Action icons use the shared chevron registry.

:theme-source{name="transfer-list"}

## Props

| Prop                                       | Type                                           | Default                         |
| ------------------------------------------ | ---------------------------------------------- | ------------------------------- |
| `items`                                    | readonly primitive, object, or grouped entries | required                        |
| `modelValue` / `defaultValue`              | destination value array                        | empty                           |
| `checked`                                  | temporarily checked value array                | internal                        |
| `labelKey` / `valueKey` / `descriptionKey` | object property                                | same as Listbox                 |
| `sourceLabel` / `targetLabel`              | string                                         | configured Available / Assigned |
| `searchable`                               | boolean                                        | `false`                         |
| `sourceSearchTerm` / `targetSearchTerm`    | string                                         | empty                           |
| `showSelectAll`                            | boolean                                        | `true`                          |
| `layout`                                   | `auto` / `horizontal` / `vertical`             | `auto`                          |
| `virtualize`                               | boolean or `{ estimateSize, overscan }`        | `false`                         |
| `disabled` / `loading` / `invalid`         | boolean                                        | `false`                         |
| `size` / `color`                           | control size / semantic role                   | `md` / `primary`                |
| `id` / `name` / `form`                     | string                                         | -                               |
| `required`                                 | boolean                                        | `false`                         |
| `ui`                                       | slot overrides                                 | -                               |

## Slots

| Slot                              | Props                                       | Purpose                        |
| --------------------------------- | ------------------------------------------- | ------------------------------ |
| `item`                            | `{ item, index, selected, disabled, side }` | Original option content        |
| `source-header` / `target-header` | `{ count, checkedCount }`                   | Panel heading                  |
| `source-footer` / `target-footer` | -                                           | Panel footer                   |
| `empty` / `empty-filter`          | `{ side }`                                  | Empty panel / unmatched search |

`TransferListProps`, `TransferListEmits`, `TransferListSlots`, `TransferSide`, and
`TransferDirection` are exported from `@sewadah/selaras/types`.


# Form Validation

[FormField](https://selarasui.my.id/components/forms/form-field)'s `error` prop is just a plain
`string | boolean` - it doesn't care where the value comes from. That's
deliberate: rather than building in a schema-validation engine of its own,
Selaras leaves that choice to you, and wires into whichever validation
library you already use by passing that library's own per-field error
message straight into `error`.

## VeeValidate

[VeeValidate v4](https://vee-validate.logaretm.com/v4/guide/composition-api/custom-inputs/){rel="&#x22;nofollow&#x22;"}
connects to Selaras through field values, blur handlers, and per-field errors.

```vue
<script setup lang="ts">
import { useField, useForm } from 'vee-validate'

const { handleSubmit, resetForm } = useForm({ initialValues: { email: '' } })
const { value: email, errorMessage, handleBlur } = useField<string>(
  'email',
  value => value.includes('@') || 'Enter a valid email address',
)

const onSubmit = handleSubmit((values) => {
  // values.email is validated and fully typed
})

function onReset(event: Event) {
  event.preventDefault()
  resetForm()
}
</script>

<template>
  <form novalidate @submit="onSubmit" @reset="onReset">
    <SFormField name="email" label="Email" :error="errorMessage">
      <SInput v-model="email" type="email" @blur="handleBlur($event, true)" />
    </SFormField>
    <SButton type="submit">
      Submit
    </SButton>
    <SButton type="reset">
      Reset
    </SButton>
  </form>
</template>
```

`novalidate` lets this example's validation library handle submission errors.
Canceling the native reset lets `resetForm()` restore field values, errors and
touched state together. This also keeps controlled file/date fields aligned
with the library's initial values instead of applying a second native reset.
Without a validation library, native `required` validation remains available.

## TanStack Form

[TanStack Form](https://tanstack.com/form){rel="&#x22;nofollow&#x22;"} is a newer, framework-agnostic
form library from the TanStack team, with schema validation through Zod,
Valibot, or any other Standard Schema-compatible library.

```vue
<script setup lang="ts">
import { useForm } from '@tanstack/vue-form'
import { z } from 'zod'

const form = useForm({
  defaultValues: { email: '' },
  onSubmit: async ({ value }) => {
    // value.email
  },
})
</script>

<template>
  <form @submit.prevent="form.handleSubmit">
    <form.Field
      name="email"
      :validators="{ onChange: z.string().email('Enter a valid email address') }"
    >
      <template #default="{ field }">
        <SFormField label="Email" :error="field.state.meta.errors[0]">
          <SInput
            :model-value="field.state.value"
            type="email"
            @update:model-value="field.handleChange"
            @blur="field.handleBlur"
          />
        </SFormField>
      </template>
    </form.Field>

    <form.Subscribe>
      <template #default="{ canSubmit, isSubmitting }">
        <SButton type="submit" :disabled="!canSubmit" :loading="isSubmitting">
          Submit
        </SButton>
      </template>
    </form.Subscribe>
  </form>
</template>
```

Unlike VeeValidate's `value` ref, TanStack Form's `field.state.value` isn't
itself a ref - `:model-value`/`@update:model-value` is the same binding
`v-model` would generate, just written out explicitly so the update goes
through `field.handleChange` instead of reassigning a ref.

## Other options

[Vuelidate](https://vuelidate-next.netlify.app){rel="&#x22;nofollow&#x22;"} is a longer-standing,
model-based alternative. The same pattern applies regardless of which
library you pick - read its per-field error message out and pass it to
`error`, whatever shape that library happens to return it in.


# App

## Usage

`SApp` wraps your root `app.vue`, once, around everything else:

```vue-html
<!-- app.vue -->
<template>
  <SApp>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </SApp>
</template>
```

This isn't optional for most of what Selaras ships - without it:

- **Tooltip** loses its shared hover-delay behavior (quickly moving between
  adjacent tooltips should skip the full delay the second time) - it needs
  Reka UI's `TooltipProvider` context, which only exists inside `SApp`.
- **Toast** has nothing to render into - `ToastProvider`'s own context lives
  here too (you still place `<SToast />` yourself, see below).
- **`useModal()`, `useDrawer()`, and `useSlideover()`** (the programmatic,
  "open from anywhere" APIs) have nothing to render the dialog/panel into -
  `SApp` mounts their renderer components internally. A plain declarative
  `<SModal>`/`<SDrawer>`/`<SSlideover>` placed directly in a page doesn't
  need this - only the `useX()` composable versions do.

If you generated your project via `npx nuxt module add @sewadah/selaras`, or copied
the Quick Setup snippet from the [installation guide](https://selarasui.my.id/overview/getting-started/installation),
this is already done for you.

### Toast and CommandPalette still need to be placed yourself

`SApp` establishes the *context* these two need, but doesn't render them for
you the way it does for Modal/Drawer/Slideover - place `<SToast />` and
`<SCommandPalette>` yourself, once, usually right alongside `SApp` itself:

```vue-html
<!-- app.vue -->
<template>
  <SApp>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
    <SToast />
    <SCommandPalette :groups="searchGroups" />
  </SApp>
</template>
```

See [Toast](https://selarasui.my.id/components/overlays/toast) and
[CommandPalette](https://selarasui.my.id/components/overlays/command-palette) for their own setup
details.

### Reading direction (RTL)

`dir` does two things at once, both needed for real right-to-left support:

- passed to Reka UI's `ConfigProvider`, which every primitive underneath
  inherits for its own internal direction-aware logic (arrow-key roving
  focus in RadioGroup/Tabs, Floating UI positioning, ...);
- set as the real `dir` attribute on `<html>` - this is what actually
  drives native browser behavior (text direction, scrollbar side) and any
  CSS logical-property utility (`ms-*`/`ps-*`/`text-start`/...), none of
  which resolve from Reka's own Vue-level context alone.

```vue-html
<SApp dir="rtl">
  ...
</SApp>
```

`lang` on `<html>` is set automatically too, tracking whatever locale
[`useLocale`](https://selarasui.my.id/utilities/composables/use-locale) is already resolving text
and date formatting against - there's no separate prop for it, since it
should always match.

## Props

| Prop  | Type            | Default |
| ----- | --------------- | ------- |
| `dir` | `'ltr' | 'rtl'` | `'ltr'` |

## Slots

| Slot    | Description    |
| ------- | -------------- |
| default | Your whole app |


# Card

## Usage


```vue
<template>
  <SCard>
    A card is a simple container for grouping related content.
  </SCard>
</template>
```


```vue-html
<SCard>
  A card is a simple container for grouping related content.
</SCard>
```

### Header and footer

`header` and `footer` are optional - each only renders (with its own
separating border) when you actually pass it:


```vue
<template>
  <SCard>
    <template #header>
      <p class="font-semibold text-[var(--selaras-resolved-text-default)]">
        Delete project
      </p>
    </template>

    This action cannot be undone. All data associated with this project
    will be permanently removed.

    <template #footer>
      <div class="flex justify-end gap-2">
        <SButton variant="ghost">
          Cancel
        </SButton>
        <SButton color="danger">
          Delete
        </SButton>
      </div>
    </template>
  </SCard>
</template>
```


```vue-html
<SCard>
  <template #header>
    <p class="font-semibold text-[var(--selaras-resolved-text-default)]">Delete project</p>
  </template>

  This action cannot be undone. All data associated with this project
  will be permanently removed.

  <template #footer>
    <div class="flex justify-end gap-2">
      <SButton variant="ghost">Cancel</SButton>
      <SButton color="danger">Delete</SButton>
    </div>
  </template>
</SCard>
```

### Variant


```vue
<script setup lang="ts">
const variants = ['outline', 'solid', 'soft', 'subtle'] as const
</script>

<template>
  <div class="grid grid-cols-1 gap-4 sm:grid-cols-4">
    <SCard v-for="variant in variants" :key="variant" :variant="variant">
      <p class="text-xs font-medium tracking-wide text-[var(--selaras-resolved-text-muted)] uppercase">
        {{ variant }}
      </p>
      <h4 class="font-semibold text-[var(--selaras-resolved-text-default)]">
        New feature shipped
      </h4>
      <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
        Read the release notes for this week's update.
      </p>
    </SCard>
  </div>
</template>
```


```vue-html
<SCard variant="outline">
  <!-- bordered, no shadow -->
</SCard>
<SCard variant="solid">
  <!-- elevated, no border -->
</SCard>
<SCard variant="soft">
  <!-- subtle tinted background -->
</SCard>
<SCard variant="subtle">
  <!-- tinted background, plus a border -->
</SCard>
```

### Blog post

A `header` badge and a `footer` byline, built entirely from other Selaras
components:


```vue
<template>
  <SCard class="w-80">
    <template #header>
      <SBadge label="Design" color="primary" variant="soft" />
    </template>

    <h3 class="font-semibold text-[var(--selaras-resolved-text-default)]">
      Building a scalable design token system
    </h3>
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      A look at how semantic tokens keep a component library themeable
      without ever touching a single component file.
    </p>

    <template #footer>
      <div class="flex items-center gap-2">
        <SAvatar text="JS" size="sm" />
        <div class="text-sm leading-tight">
          <p class="font-medium text-[var(--selaras-resolved-text-default)]">
            Jane Smith
          </p>
          <p class="text-[var(--selaras-resolved-text-muted)]">
            Mar 12, 2026
          </p>
        </div>
      </div>
    </template>
  </SCard>
</template>
```


```vue-html
<SCard class="w-80">
  <template #header>
    <SBadge label="Design" color="primary" variant="soft" />
  </template>

  <h3 class="font-semibold text-[var(--selaras-resolved-text-default)]">
    Building a scalable design token system
  </h3>
  <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
    A look at how semantic tokens keep a component library themeable
    without ever touching a single component file.
  </p>

  <template #footer>
    <div class="flex items-center gap-2">
      <SAvatar text="JS" size="sm" />
      <div class="text-sm leading-tight">
        <p class="font-medium text-[var(--selaras-resolved-text-default)]">Jane Smith</p>
        <p class="text-[var(--selaras-resolved-text-muted)]">Mar 12, 2026</p>
      </div>
    </div>
  </template>
</SCard>
```

### Product

Overriding `ui.body` to `p-0` lets a full-bleed image sit flush against the
card's edges, with your own padded wrapper underneath for the details:


```vue
<template>
  <SCard :ui="{ body: 'p-0' }" class="w-64">
    <img
      src="https://picsum.photos/seed/selaras-headphones/400/300"
      alt="Wireless headphones"
      class="aspect-[4/3] w-full object-cover"
    >
    <div class="flex flex-col gap-1 p-4">
      <p class="font-medium text-[var(--selaras-resolved-text-default)]">
        Wireless headphones
      </p>
      <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
        Noise-cancelling, 30-hour battery life
      </p>
      <div class="mt-2 flex items-center justify-between">
        <span class="font-semibold text-[var(--selaras-resolved-text-default)]">$129</span>
        <SButton size="sm">
          Add to cart
        </SButton>
      </div>
    </div>
  </SCard>
</template>
```


```vue-html
<SCard :ui="{ body: 'p-0' }" class="w-64">
  <img
    src="https://picsum.photos/seed/selaras-headphones/400/300"
    alt="Wireless headphones"
    class="aspect-[4/3] w-full object-cover"
  >
  <div class="flex flex-col gap-1 p-4">
    <p class="font-medium text-[var(--selaras-resolved-text-default)]">Wireless headphones</p>
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">Noise-cancelling, 30-hour battery life</p>
    <div class="mt-2 flex items-center justify-between">
      <span class="font-semibold text-[var(--selaras-resolved-text-default)]">$129</span>
      <SButton size="sm">Add to cart</SButton>
    </div>
  </div>
</SCard>
```

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-card{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally). Its `header`/`footer` named slots are each a
`#slot-name` line inside the block, `@nuxtjs/mdc`'s own convention:

```text
::s-card
#header
Design
#footer
Posted March 2026
::
```

A block mixing `header`/`footer` markers with unmarked body text for the
default slot doesn't reliably separate the two - confirmed empirically, not
just undocumented - so keep a markdown-authored card to its named slots only;
reach for `<SCard>` directly in a `.vue` file once the body needs its own
text.

## Custom `:ui`

Global and scoped recipe overrides use `ui.card`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Card`'s own theme file:

:theme-source{name="card"}

## Props

| Prop      | Type                                         | Default     |
| --------- | -------------------------------------------- | ----------- |
| `variant` | `'outline' | 'solid' | 'soft' | 'subtle'`    | `'outline'` |
| `ui`      | `Partial<Record<CardSlot, string | object>>` | -           |

## Slots

| Slot     | Description                                                                        |
| -------- | ---------------------------------------------------------------------------------- |
| `header` | Optional content above the body, separated by a border. Only rendered when passed. |
| default  | The card's body content.                                                           |
| `footer` | Optional content below the body, separated by a border. Only rendered when passed. |


# CardGroup

## Usage


```vue
<template>
  <SCardGroup class="w-full">
    <SCard>
      <template #header>
        <SBadge label="Design" color="primary" variant="soft" />
      </template>
      <h3 class="font-semibold text-[var(--selaras-resolved-text-default)]">
        Building a scalable design token system
      </h3>
      <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
        A look at how semantic tokens keep a component library themeable.
      </p>
    </SCard>
    <SCard>
      <template #header>
        <SBadge label="Engineering" color="secondary" variant="soft" />
      </template>
      <h3 class="font-semibold text-[var(--selaras-resolved-text-default)]">
        CSS-only animation, end to end
      </h3>
      <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
        Why every transition in this library skips JavaScript entirely.
      </p>
    </SCard>
  </SCardGroup>
</template>
```


```vue-html
<SCardGroup>
  <SCard>...</SCard>
  <SCard>...</SCard>
</SCardGroup>
```

Single column below the `sm` breakpoint, `cols` columns at `sm` and up -
`2` by default, matching the most common use ([Card](https://selarasui.my.id/components/layout/card)'s
own comparison/before-after cases). `SCardGroup` has no opinion on what's
inside it - any children work, not just [Card](https://selarasui.my.id/components/layout/card).

## Custom `:ui`

Global and scoped recipe overrides use `ui.cardGroup`.

To see exactly what you'd be overriding - the current default classes for
every slot - here's `CardGroup`'s own theme file:

:theme-source{name="card-group"}

## Props

| Prop   | Type                                              | Default |
| ------ | ------------------------------------------------- | ------- |
| `cols` | `2 | 3 | 4`                                       | `2`     |
| `ui`   | `Partial<Record<CardGroupSlot, string | object>>` | -       |


# ColorModeSwitch

## Usage


```vue
<template>
  <div class="flex flex-wrap items-center gap-6">
    <SColorModeSwitch />
    <SColorModeSwitch label="Dark mode" description="Change the appearance of this documentation." />
  </div>
</template>
```


```vue-html
<SColorModeSwitch />
<SColorModeSwitch label="Dark mode" description="Choose your preferred appearance." />
```

The switch is checked in dark mode and unchecked in light mode. It follows
the resolved appearance when the preference is `system`; changing it sets
an explicit `light` or `dark` preference through `useColorMode()`. Preferences
are persisted by the color-mode module that Selaras installs automatically.
The switch is disabled on pages with a forced color mode.

During server rendering and its first client render, the switch is unchecked
and disabled. After mounting, it reflects the saved or system appearance.
This keeps hydration consistent on synchronous and async pages without
requiring a `ClientOnly` wrapper.

It uses the same theme and `ui` slots as [Switch](https://selarasui.my.id/components/forms/switch),
with sun and moon icons in the thumb. Use [ColorModeToggle](https://selarasui.my.id/components/layout/color-mode-toggle)
for a button instead.

## Props

| Prop            | Type                  | Default                    |
| --------------- | --------------------- | -------------------------- |
| `id`            | `string`              | —                          |
| `label`         | `string`              | —                          |
| `description`   | `string`              | —                          |
| `size`          | `'sm' | 'md' | 'lg'`  | `'md'`                     |
| `color`         | `ColorRole`           | `'primary'`                |
| `disabled`      | `boolean`             | `false`                    |
| `checkedIcon`   | `string`              | Registered dark-mode icon  |
| `uncheckedIcon` | `string`              | Registered light-mode icon |
| `ui`            | Switch slot overrides | —                          |

Without a label, the switch has a localized accessible name. Set `aria-label`
to customize it. Set either icon prop to an empty string to hide that icon.

## Slots

| Slot          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `default`     | Replaces the label.                                      |
| `description` | Replaces the description when `description` is provided. |


# ColorModeToggle

## Usage


```vue
<template>
  <SColorModeToggle />
</template>
```


```vue-html
<SColorModeToggle />
```

Built on [`@nuxtjs/color-mode`](https://color-mode.nuxtjs.org/){rel="&#x22;nofollow&#x22;"} (a
`moduleDependencies` entry in selaras's own Nuxt module, so it's set up
automatically for any consumer) - toggling flips between `light` and `dark`,
applying a bare `dark`/`light` class on `<html>` that matches this library's
own Tailwind v4 dark variant (`theme.css`'s
`@custom-variant dark (&:where(.dark, .dark *))`) with no extra config.

For anything beyond a simple two-way toggle (e.g. a light/dark/system
picker), call `useColorMode()` yourself - it's the same composable this
component uses internally (`colorMode.preference` is writable, `colorMode.value`
is the resolved mode).

The button renders a disabled light-mode icon during server rendering and
its first client render. After mounting, it reflects the saved or system
appearance and becomes interactive. This also works on pages with async
data loading; no `ClientOnly` wrapper is needed. Pages with a forced color
mode keep the button disabled.

## Props

`SColorModeToggle` takes no props.


# Container

## Usage


```vue
<template>
  <SContainer size="sm" class="rounded-[var(--selaras-resolved-radius-md)] border border-dashed border-[var(--selaras-resolved-border-default)]">
    <p>This content is centered and constrained to a max width.</p>
  </SContainer>
</template>
```


```vue-html
<SContainer size="sm">
  <p>This content is centered and constrained to a max width.</p>
</SContainer>
```

## Custom `:ui`

Global and scoped recipe overrides use `ui.container`.

To see exactly what you'd be overriding - the current default classes for
every slot and size - here's `Container`'s own theme file:

:theme-source{name="container"}

## Props

| Prop   | Type                                              | Default |
| ------ | ------------------------------------------------- | ------- |
| `size` | `'sm' | 'md' | 'lg' | 'xl' | 'full'`              | `'lg'`  |
| `ui`   | `Partial<Record<ContainerSlot, string | object>>` | -       |


# Header

## Usage


```vue
<template>
  <SHeader class="static rounded-[var(--selaras-resolved-radius-md)] ring-1 ring-[var(--selaras-resolved-border-default)]">
    <span class="font-semibold">
      My App
    </span>
    <template #right>
      <SColorModeToggle />
    </template>
  </SHeader>
</template>
```


```vue-html
<SHeader>
  <span class="font-semibold">My App</span>
  <template #right>
    <SColorModeToggle />
  </template>
</SHeader>
```

`SHeader` is `sticky top-0` by default, meant to sit above everything else on
the page - this docs site's own top bar is exactly this component. If you
also use [PageAside](https://selarasui.my.id/composites/documentation/page-aside) below it (for nav or TOC), give
it a matching offset via its `ui` prop so it doesn't sit under the header:

```vue-html
<SPageAside :ui="{ root: 'top-16 h-[calc(100vh-4rem)]' }">
```

(`top-16`/`h-4rem` match `SHeader`'s default `h-16` - adjust both together if
you override the header's height.)

## Custom `:ui`

Global and scoped recipe overrides use `ui.header`.

To see exactly what you'd be overriding - the current default classes for
every slot - here's `Header`'s own theme file:

:theme-source{name="header"}

## Props

| Prop | Type                                           | Default |
| ---- | ---------------------------------------------- | ------- |
| `ui` | `Partial<Record<HeaderSlot, string | object>>` | -       |

## Slots

| Slot    | Description                          |
| ------- | ------------------------------------ |
| default | Left-aligned content (e.g. a logo)   |
| `right` | Right-aligned content (e.g. actions) |


# ScrollArea

## Usage


```vue
<template>
  <SScrollArea class="h-32 w-full rounded-[var(--selaras-resolved-radius-md)] ring-1 ring-[var(--selaras-resolved-border-default)]">
    <div class="flex flex-col gap-2 p-3">
      <p v-for="i in 15" :key="i" class="text-sm">
        Scrollable line {{ i }}
      </p>
    </div>
  </SScrollArea>
</template>
```


```vue-html
<SScrollArea class="h-32">
  <div class="flex flex-col gap-2 p-3">
    <p v-for="i in 15" :key="i">Line {{ i }}</p>
  </div>
</SScrollArea>
```

Give it a height via `class` (fallthrough) - `SScrollArea` fills whatever
box it's placed in. [PageAside](https://selarasui.my.id/composites/documentation/page-aside) uses this internally
for its scrollable body.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `ScrollArea`'s own theme file:

Global and scoped theme recipes use `ui.scrollArea`.

:theme-source{name="scroll-area"}

## Props

| Prop          | Type                                               | Default      |
| ------------- | -------------------------------------------------- | ------------ |
| `orientation` | `'vertical' | 'horizontal' | 'both'`               | `'vertical'` |
| `ui`          | `Partial<Record<ScrollAreaSlot, string | object>>` | -            |

## Slots

| Slot    | Description        |
| ------- | ------------------ |
| default | Scrollable content |


# Splitter

## Usage


```vue
<template>
  <SSplitter class="h-64 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SSplitterPanel :default-size="30" :min-size="20" class="bg-[var(--selaras-resolved-surface-elevated)] p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
      Panel one
    </SSplitterPanel>
    <!--
      The resize handle's own hit area is wider than its visible line
      (a comfortable grab target, invisible padding on either side) -
      harmless when both panels share one background, but Panel one here
      uses --selaras-resolved-surface-elevated while Panel two stays plain, so that
      "invisible" padding would otherwise show through as a mismatched
      sliver right at Panel one's edge (same fix DashboardResizeHandle
      applies for its own fixed two-role layout - see its theme file).
    -->
    <SSplitterResizeHandle direction="horizontal" :ui="{ root: 'bg-[linear-gradient(to_right,var(--selaras-resolved-surface-elevated)_50%,transparent_50%)]' }" />
    <SSplitterPanel :min-size="20" class="p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
      Panel two
    </SSplitterPanel>
  </SSplitter>
</template>
```


```vue-html
<SSplitter>
  <SSplitterPanel :default-size="30" :min-size="20">Panel one</SSplitterPanel>
  <SSplitterResizeHandle />
  <SSplitterPanel :min-size="20">Panel two</SSplitterPanel>
</SSplitter>
```

Three components used together - `SSplitter` (the group), one
`SSplitterPanel` per pane, and an `SSplitterResizeHandle` between each pair
of panels you want draggable. Sizes are percentages of the group's total by
default (`sizeUnit="%"` on `SSplitterPanel`); pass `sizeUnit="px"` for
pixel-based panels instead. A pixel `defaultSize` also applies in the
server-rendered layout, before the group measures its container.
[DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) uses this to
keep its default width at 260px while the main panel fills the remaining space.

`SSplitterPanel` has no visual styling of its own beyond clipping its own
overflow - what a panel looks like depends entirely on what it's used for,
left to the consumer.

### Collapsible panels

A panel with `collapsible` snaps fully closed once dragged past its own
`minSize`, down to `collapsedSize` (`0` by default - fully hidden). Call
`.collapse()`/`.expand()` on a template ref to do the same thing
programmatically - see [DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar)'s
own source for a real example, driven by a button elsewhere on the page
rather than a drag gesture.

`SSplitterPanel`'s own default slot is scoped with `{ isCollapsed, isExpanded, collapse, expand }` - the same `collapse()`/`expand()` functions as the
template-ref methods above, plus live `isCollapsed`/`isExpanded` booleans, so
content inside the panel can react to (or trigger) collapse state without
needing a ref at all:

```vue-html
<SSplitterPanel collapsible :collapsed-size="0">
  <template #default="{ isCollapsed, expand }">
    <button v-if="isCollapsed" @click="expand()">Expand</button>
    <p v-else>Panel content</p>
  </template>
</SSplitterPanel>
```

### Persistence

`autoSaveId` (on `SSplitter`) remembers every panel's size across reloads,
via `localStorage` by default - pass a custom `storage` object (anything
shaped `{ getItem, setItem }`) to persist somewhere else instead, the same
mechanism [DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) uses to
persist to a cookie. Whichever storage is used, the remembered layout only
applies once mounted, not during SSR - Reka's own layout-restore call runs
inside a `watch()` callback, which Vue's SSR render pass doesn't flush.

## Custom `:ui`

Each of the three components keeps its own theme file. To see exactly what
you'd be overriding - the current default classes for every slot - here they
are:

### Splitter

:theme-source{name="splitter"}

### SplitterPanel

`SplitterPanel` has no visual styling of its own beyond clipping overflow
(see [Usage](https://selarasui.my.id/#usage) above), but the slot is still there to override if you
need to add your own:

:theme-source{name="splitter-panel"}

### SplitterResizeHandle

:theme-source{name="splitter-resize-handle"}

## Props

### Splitter

| Prop               | Type                                       | Default                                      |
| ------------------ | ------------------------------------------ | -------------------------------------------- |
| `direction`        | `'horizontal' | 'vertical'`                | `'horizontal'`                               |
| `autoSaveId`       | `string`                                   | -                                            |
| `keyboardResizeBy` | `number`                                   | `10`                                         |
| `storage`          | `{ getItem, setItem }`                     | - (Reka's own `localStorage`-backed default) |
| `ui`               | `Partial<Record<'root', string | object>>` | -                                            |

### SplitterPanel

| Prop            | Type                                       | Default |
| --------------- | ------------------------------------------ | ------- |
| `defaultSize`   | `number`                                   | -       |
| `minSize`       | `number`                                   | -       |
| `maxSize`       | `number`                                   | -       |
| `collapsedSize` | `number`                                   | -       |
| `collapsible`   | `boolean`                                  | -       |
| `sizeUnit`      | `'px' | '%'`                               | `'%'`   |
| `order`         | `number`                                   | -       |
| `ui`            | `Partial<Record<'root', string | object>>` | -       |

### SplitterResizeHandle

| Prop        | Type                                                         | Default        |
| ----------- | ------------------------------------------------------------ | -------------- |
| `direction` | `'horizontal' | 'vertical'`                                  | `'horizontal'` |
| `disabled`  | `boolean`                                                    | -              |
| `ui`        | `Partial<Record<SplitterResizeHandleSlot, string | object>>` | -              |

## Emits

### Splitter

| Event    | Payload                                     |
| -------- | ------------------------------------------- |
| `layout` | `number[]` - every panel's own current size |

### SplitterPanel

| Event      | Payload  |
| ---------- | -------- |
| `collapse` | -        |
| `expand`   | -        |
| `resize`   | `number` |

## Slots

### SplitterPanel

| Slot      | Props                                           | Description                                                                                                                     |
| --------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `default` | `{ isCollapsed, isExpanded, collapse, expand }` | Panel content, scoped with live collapse state and the same `collapse()`/`expand()` functions as the template-ref methods below |

## Methods

### SplitterPanel

Access these via a template ref on `SSplitterPanel`.

| Method                 | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `collapse()`           | Snaps the panel closed to `collapsedSize`                        |
| `expand()`             | Restores the panel to its size before it was last collapsed      |
| `resize(size: number)` | Sets the panel's size directly, in whatever unit `sizeUnit` is   |
| `getSize()`            | Returns the panel's current size, in whatever unit `sizeUnit` is |
| `isCollapsed`          | Whether the panel is currently collapsed                         |
| `isExpanded`           | Whether the panel is currently expanded                          |


# Theme

## Usage

`STheme` applies `ui`/`defaults` overrides to descendant components.
It is headless by default. Set `as` to give runtime token overrides an
explicit DOM boundary.


```vue
<template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-3">
      <SButton>Default</SButton>
      <STheme :ui="{ button: { slots: { base: 'rounded-full' } } }">
        <SButton>Rounded, scoped</SButton>
      </STheme>
    </div>

    <STheme :defaults="{ button: { size: 'lg' } }">
      <div class="flex items-center gap-3">
        <SButton>No own size - defaults to lg</SButton>
        <SButton size="sm">
          Explicit size - still sm
        </SButton>
      </div>
    </STheme>

    <!-- Nesting: the inner Theme wins for what it sets (color), while
    still inheriting the outer one's unset setting (the rounded ui override). -->
    <STheme :ui="{ button: { slots: { base: 'rounded-full' } } }" :defaults="{ button: { color: 'neutral' } }">
      <STheme :defaults="{ button: { color: 'danger' } }">
        <SButton>Rounded (outer) + danger (inner)</SButton>
      </STheme>
    </STheme>
  </div>
</template>
```


```vue-html
<SButton>Default</SButton>
<STheme :ui="{ button: { base: 'rounded-full' } }">
  <SButton>Rounded, scoped</SButton>
</STheme>
```

This is the same override shape as [`app.config.selaras.ui`](https://selarasui.my.id/overview/theming/global-configuration)

- `{ <componentKey>: { slots: { <slotName>: '...' } } }`, merged onto the
  component's base theme the same way (`tv()`'s own `extend`) - just scoped
  to this subtree instead of the whole app. See
  [Theming](https://selarasui.my.id/overview/theming/overview) for the full precedence order and how
  `:ui`/`app.config.selaras.ui`/`STheme` all fit together.

### Prop defaults

`defaults` sets a default value for a prop on every matching descendant,
rather than a class override:

```vue-html
<STheme :defaults="{ button: { size: 'lg' } }">
  <SButton>No own size - renders lg</SButton>
  <SButton size="sm">Explicit size - still sm</SButton>
</STheme>
```

An explicit prop on the component itself always wins - `STheme` only
fills in when a prop is left unset. **Only `size`/`color` are wired up to
read this today**, and only on `Button`, `Badge`, `Avatar`, `Chip`, and
`Input` - not every prop on every component. Unwired components ignore
`defaults` entirely (their own `:ui`/`app.config.selaras.ui` overrides are
unaffected either way).

### Nesting

An inner `STheme` wins for the specific settings it sets, while still
inheriting whatever an outer one set and it didn't touch:

```vue-html
<STheme :ui="{ button: { base: 'rounded-full' } }" :defaults="{ button: { color: 'neutral' } }">
  <STheme :defaults="{ button: { color: 'danger' } }">
    <SButton>Rounded (from the outer Theme) + danger (from the inner one)</SButton>
  </STheme>
</STheme>
```

### Scoped tokens and portals

Use `as` to create a DOM boundary for semantic token overrides:

```vue-html
<STheme as="section" :tokens="{ light: { colors: { premium: { fill: '#5134a8' } } } }">
  <!-- nested token scopes inherit untouched modes, roles and leaves -->
</STheme>
```

This example assumes a registered `premium` role. Managed overrides are
carried into supported overlay portals. An inner scope
can override one leaf and retain its outer scope's other values, including
after reactive updates. A headless `STheme` passes the existing token scope
through; its own `tokens` require an explicit `as` root.

External CSS variables still follow DOM inheritance. If a token references
a variable declared on a local ancestor, use a portal target within that
ancestor; the theme marker does not copy arbitrary CSS variables.

## Props

| Prop       | Type                                               | Default |
| ---------- | -------------------------------------------------- | ------- |
| `ui`       | `Partial<Record<string, object>>`                  | -       |
| `defaults` | `Partial<Record<string, Record<string, unknown>>>` | -       |
| `tokens`   | `RuntimeTokenOverrides`                            | -       |
| `as`       | `string | Component`                               | -       |


# Accordion

## Usage


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <SAccordion :items="items">
    <template #a>
      A UI component library for Nuxt, themed with tv() and CSS variables.
    </template>
    <template #b>
      Yes, MIT licensed.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion :items="[{ value: 'a', label: 'Question one' }]">
  <template #a>
    Answer one.
  </template>
</SAccordion>
```

Each item's content comes from a named slot matching its `value`. `type`
defaults to `'multiple'` (independent items can each be open at once) -
[ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation) uses this internally for
its collapsible nav groups.

### Custom label content

The `label` slot replaces an item's plain-text label with anything -
scoped with `item`, so a single template can vary per item:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <SAccordion :items="items">
    <template #label="{ item }">
      <span class="flex items-center gap-2">
        {{ item.label }}
        <SBadge v-if="item.value === 'a'" label="New" color="primary" size="sm" />
      </span>
    </template>
    <template #a>
      A UI component library for Nuxt, themed with tv() and CSS variables.
    </template>
    <template #b>
      Yes, MIT licensed.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion :items="items">
  <template #label="{ item }">
    <span class="flex items-center gap-2">
      {{ item.label }}
      <SBadge v-if="item.value === 'a'" label="New" color="primary" size="sm" />
    </span>
  </template>
  ...
</SAccordion>
```

`chevron-icon` replaces the expand/collapse chevron the same way any other
icon-swap slot in this library does (default: `hugeicons:arrow-down-01`).

### Icon in the label

An icon next to the label is just more `label` slot content - it's
independent of the chevron on the other end of the trigger:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'Account settings', icon: 'hugeicons:settings-01' },
  { value: 'b', label: 'Security', icon: 'hugeicons:shield-01' },
]
</script>

<template>
  <SAccordion :items="items">
    <template #label="{ item }">
      <span class="flex items-center gap-2">
        <SIcon v-if="item.icon" :name="item.icon" class="size-4 text-[var(--selaras-resolved-text-muted)]" />
        {{ item.label }}
      </span>
    </template>
    <template #a>
      Update your name, email and profile photo.
    </template>
    <template #b>
      Manage two-factor authentication and active sessions.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion :items="items">
  <template #label="{ item }">
    <span class="flex items-center gap-2">
      <SIcon :name="item.icon" class="size-4 text-[var(--selaras-resolved-text-muted)]" />
      {{ item.label }}
    </span>
  </template>
  ...
</SAccordion>
```

### Custom chevron

`chevron-icon` isn't limited to a single swapped-in icon - here two icons
are cross-faded via `group-data-[state=open]:` instead of the default
icon's rotation, for a plus/minus toggle instead of an arrow:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <SAccordion :items="items">
    <template #chevron-icon>
      <span class="relative size-4 shrink-0 text-[var(--selaras-resolved-text-muted)]">
        <SIcon name="hugeicons:plus-sign" class="absolute inset-0 transition-opacity group-data-[state=open]:opacity-0" />
        <SIcon name="hugeicons:minus-sign" class="absolute inset-0 opacity-0 transition-opacity group-data-[state=open]:opacity-100" />
      </span>
    </template>
    <template #a>
      A UI component library for Nuxt, themed with tv() and CSS variables.
    </template>
    <template #b>
      Yes, MIT licensed.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion :items="items">
  <template #chevron-icon>
    <span class="relative size-4 shrink-0 text-[var(--selaras-resolved-text-muted)]">
      <SIcon name="hugeicons:plus-sign" class="absolute inset-0 transition-opacity group-data-[state=open]:opacity-0" />
      <SIcon name="hugeicons:minus-sign" class="absolute inset-0 opacity-0 transition-opacity group-data-[state=open]:opacity-100" />
    </span>
  </template>
  ...
</SAccordion>
```

### Single mode

`type="single"` allows only one item open at a time - opening one closes
whichever was open before it. `collapsible` (default `true`) additionally
lets clicking the open item's own trigger close it, rather than leaving at
least one item permanently forced open:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
  { value: 'c', label: 'Does it support dark mode?' },
]
</script>

<template>
  <SAccordion type="single" :items="items" default-value="a">
    <template #a>
      A UI component library for Nuxt, themed with tv() and CSS variables.
    </template>
    <template #b>
      Yes, MIT licensed.
    </template>
    <template #c>
      Yes, every color token has a light and dark value.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion type="single" :items="items" default-value="a">
  <template #a>...</template>
  <template #b>...</template>
</SAccordion>
```

### Sizes

`size` takes `sm` / `md` / `lg`, scaling the trigger's padding/text and
the content's text together:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <div class="flex w-full flex-col gap-6">
    <SAccordion size="sm" :items="items">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
    <SAccordion size="md" :items="items">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
    <SAccordion size="lg" :items="items">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
  </div>
</template>
```


```vue-html
<SAccordion size="sm" :items="items">...</SAccordion>
<SAccordion size="md" :items="items">...</SAccordion>
<SAccordion size="lg" :items="items">...</SAccordion>
```

### Variant

`list` (default) is a flat list with a shared divider between items.
`pill` gives each item its own bordered, rounded card instead, with a gap
between them - the same visual language as [Card](https://selarasui.my.id/components/layout/card)'s
own `outline` variant:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <div class="flex w-full flex-col gap-6">
    <SAccordion variant="list" :items="items">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
    <SAccordion variant="pill" :items="items">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
  </div>
</template>
```


```vue-html
<SAccordion variant="list" :items="items">...</SAccordion>
<SAccordion variant="pill" :items="items">...</SAccordion>
```

### Chevron position

`chevronPosition` moves the chevron to the start of the trigger instead of
the end - the label stays flush next to it rather than pushed to the
opposite side, since `justify-between` only applies in the (default) `end`
position:


```vue
<script setup lang="ts">
const items = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?' },
]
</script>

<template>
  <SAccordion chevron-position="start" :items="items">
    <template #a>
      A UI component library for Nuxt, themed with tv() and CSS variables.
    </template>
    <template #b>
      Yes, MIT licensed.
    </template>
  </SAccordion>
</template>
```


```vue-html
<SAccordion chevron-position="start" :items="items">...</SAccordion>
```

### Disabled

An item's own `disabled: true` blocks just that item; the accordion's own
`disabled` prop blocks every item at once:


```vue
<script setup lang="ts">
const itemsWithDisabledItem = [
  { value: 'a', label: 'What is Selaras?' },
  { value: 'b', label: 'Is it free?', disabled: true },
]
</script>

<template>
  <div class="flex w-full flex-col gap-6">
    <SAccordion :items="itemsWithDisabledItem">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
    <SAccordion disabled :items="itemsWithDisabledItem">
      <template #a>
        A UI component library for Nuxt, themed with tv() and CSS variables.
      </template>
      <template #b>
        Yes, MIT licensed.
      </template>
    </SAccordion>
  </div>
</template>
```


```vue-html
<SAccordion :items="[{ value: 'a', label: '...' }, { value: 'b', label: '...', disabled: true }]">
  ...
</SAccordion>
<SAccordion disabled :items="items">
  ...
</SAccordion>
```

### Accessibility

Accordion renders Reka UI's Accordion primitive, so the accessibility
semantics come from there rather than being reimplemented here: each
trigger is a real `<button>` (keyboard-activatable with
:kbd[Enter] / :kbd[Space] ), :kbd[↑] / :kbd[↓] move focus
between triggers, and each panel is exposed as `role="region"` with
`aria-labelledby` pointing back at its own trigger - a screen reader
always knows which question a given answer belongs to, even if the DOM
order changes.

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-accordion{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally). `items` is an array prop, not a string - bind
it with a leading `:` so `@nuxtjs/mdc` parses the attribute as an expression
instead of literal text. Each item's own content is a `#slot-name` line
matching that item's `value`:

```text
::s-accordion{:items='[{"label":"First","value":"a"},{"label":"Second","value":"b"}]'}
#a
Content for the first item.
#b
Content for the second item.
::
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.accordion`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Accordion`'s own theme file:

:theme-source{name="accordion"}

## Props

| Prop              | Type                                                                    | Default      |
| ----------------- | ----------------------------------------------------------------------- | ------------ |
| `items`           | `{ value: string, label: string, disabled?: boolean, icon?: string }[]` | -            |
| `type`            | `'single' | 'multiple'`                                                 | `'multiple'` |
| `defaultValue`    | `string | string[]`                                                     | -            |
| `modelValue`      | `string | string[]`                                                     | -            |
| `collapsible`     | `boolean`                                                               | `true`       |
| `disabled`        | `boolean`                                                               | `false`      |
| `size`            | `'sm' | 'md' | 'lg'`                                                    | `md`         |
| `variant`         | `'list' | 'pill'`                                                       | `list`       |
| `chevronPosition` | `'start' | 'end'`                                                       | `end`        |
| `ui`              | `Partial<Record<AccordionSlot, string | object>>`                       | -            |

## Events

| Event               | Payload             | Description                        |
| ------------------- | ------------------- | ---------------------------------- |
| `update:modelValue` | `string | string[]` | Fires when the open item(s) change |

## Slots

| Slot           | Props      | Description                                                               |
| -------------- | ---------- | ------------------------------------------------------------------------- |
| `[item.value]` | -          | Content for that item, one named slot per item                            |
| `label`        | `{ item }` | Replaces an item's label content                                          |
| `chevron-icon` | -          | Replaces the expand/collapse chevron (default: `hugeicons:arrow-down-01`) |


# Breadcrumb

## Usage

The last item always renders as the current page - a plain, non-
interactive label, never a link, regardless of whether it has its own
`to`:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Components', to: '/components' },
  { label: 'Breadcrumb' },
]
</script>

<template>
  <SBreadcrumb :items="items" />
</template>
```


```vue-html
<SBreadcrumb :items="[
  { label: 'Home', to: '/' },
  { label: 'Components', to: '/components' },
  { label: 'Breadcrumb' },
]" />
```

### With icons


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/', icon: 'hugeicons:home-01' },
  { label: 'Settings', to: '/settings', icon: 'hugeicons:settings-01' },
  { label: 'Profile', icon: 'hugeicons:user' },
]
</script>

<template>
  <SBreadcrumb :items="items" />
</template>
```


```vue-html
<SBreadcrumb :items="[
  { label: 'Home', to: '/', icon: 'hugeicons:home-01' },
  { label: 'Settings', to: '/settings', icon: 'hugeicons:settings-01' },
]" />
```

### Disabled item

An earlier item without a `to` (or with `disabled` set) renders inert -
same look as the trail, without being clickable:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Archived project', to: '/projects/archived', disabled: true },
  { label: 'Report' },
]
</script>

<template>
  <SBreadcrumb :items="items" />
</template>
```


```vue-html
<SBreadcrumb :items="[
  { label: 'Home', to: '/' },
  { label: 'Archived project', to: '/projects/archived', disabled: true },
  { label: 'Report' },
]" />
```

### Custom separator

`separator-icon` replaces the default chevron:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Components', to: '/components' },
  { label: 'Breadcrumb' },
]
</script>

<template>
  <SBreadcrumb :items="items" separator-icon="hugeicons:slash" />
</template>
```


```vue-html
<SBreadcrumb :items="items" separator-icon="hugeicons:slash" />
```

### Collapsing long trails

`max-items` collapses the middle of a long trail behind an ellipsis
button once there are more items than that - the first item and the
last `maxItems - 1` stay visible, everything else moves into an
overflow menu:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/', icon: 'hugeicons:home-01' },
  { label: 'Electronics', to: '/electronics' },
  { label: 'Computers', to: '/electronics/computers' },
  { label: 'Laptops', to: '/electronics/computers/laptops' },
  { label: 'Gaming laptops', to: '/electronics/computers/laptops/gaming' },
  { label: 'Product' },
]
</script>

<template>
  <SBreadcrumb :items="items" :max-items="4" />
</template>
```


```vue-html
<SBreadcrumb :items="items" :max-items="4" />
```

### Truncating long labels

`truncate` keeps a single long label - a dynamic product title, say -
from breaking the trail's layout. `true` caps it at `12rem`; pass a
CSS length string (`'20rem'`, `'300px'`) for a custom cap. The full
label is still available on hover via the native `title` attribute:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Products', to: '/products' },
  { label: 'The Ultimate Ergonomic Wireless Mechanical Keyboard, Limited Edition' },
]
</script>

<template>
  <div class="max-w-sm">
    <SBreadcrumb :items="items" truncate />
  </div>
</template>
```


```vue-html
<SBreadcrumb :items="items" truncate />
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.breadcrumb`. Its collapsed overflow
menu and icons remain ordinary nested `ui.dropdown` and `ui.icon` components.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Breadcrumb`'s own theme file:

:theme-source{name="breadcrumb"}

## Props

| Prop            | Type                                               | Default              |
| --------------- | -------------------------------------------------- | -------------------- |
| `items`         | `BreadcrumbItem[]`                                 | -                    |
| `maxItems`      | `number`                                           | -                    |
| `truncate`      | `boolean | string`                                 | `false`              |
| `separatorIcon` | `string`                                           | `icons.chevronRight` |
| `ui`            | `Partial<Record<BreadcrumbSlot, string | object>>` | -                    |

`BreadcrumbItem` is `{ label: string, icon?: string, to?: string, disabled?: boolean }`.

## Slots

| Slot        | Props                      | Description                          |
| ----------- | -------------------------- | ------------------------------------ |
| `item`      | `{ item, index, current }` | Replaces one item's content          |
| `separator` | -                          | Replaces the separator between items |


# Collapsible

## Usage

Closed by default - the `trigger` slot is the button's own content, the
default slot is the panel:


```vue
<template>
  <SCollapsible>
    <template #trigger>
      What's included in the free plan?
    </template>
    Everything you need to get started: unlimited projects, community
    support, and access to every core feature.
  </SCollapsible>
</template>
```


```vue-html
<SCollapsible>
  <template #trigger>
    What's included in the free plan?
  </template>
  Everything you need to get started: unlimited projects, community
  support, and access to every core feature.
</SCollapsible>
```

### Controlled

`v-model:open` controls it from the parent instead of managing its own
state:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <div class="flex flex-col gap-3">
    <SButton size="sm" @click="open = !open">
      {{ open ? 'Close from outside' : 'Open from outside' }}
    </SButton>
    <SCollapsible v-model:open="open">
      <template #trigger>
        Toggle me
      </template>
      Content controlled by the parent.
    </SCollapsible>
  </div>
</template>
```


```vue-html
<SCollapsible v-model:open="open">
  <template #trigger>
    Toggle me
  </template>
  Content controlled by the parent.
</SCollapsible>
```

### Disabled

`disabled` blocks the trigger from toggling at all:


```vue
<template>
  <SCollapsible disabled default-open>
    <template #trigger>
      This can't be collapsed
    </template>
    Locked open.
  </SCollapsible>
</template>
```


```vue-html
<SCollapsible disabled default-open>
  <template #trigger>
    This can't be collapsed
  </template>
  Locked open.
</SCollapsible>
```

### Direction

`direction="up"` reveals the content above the trigger instead of
below it - the chevron's rest/open rotation flips to match, still
pointing toward where the content will appear:


```vue
<template>
  <SCollapsible direction="up">
    <template #trigger>
      What's included in the free plan?
    </template>
    Everything you need to get started: unlimited projects, community
    support, and access to every core feature.
  </SCollapsible>
</template>
```


```vue-html
<SCollapsible direction="up">
  <template #trigger>
    What's included in the free plan?
  </template>
  Everything you need to get started: unlimited projects, community
  support, and access to every core feature.
</SCollapsible>
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.collapsible`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Collapsible`'s own theme file:

:theme-source{name="collapsible"}

## Props

| Prop          | Type                                                | Default  |
| ------------- | --------------------------------------------------- | -------- |
| `open`        | `boolean`                                           | -        |
| `defaultOpen` | `boolean`                                           | `false`  |
| `disabled`    | `boolean`                                           | -        |
| `size`        | `'sm' | 'md' | 'lg'`                                | `'md'`   |
| `direction`   | `'down' | 'up'`                                     | `'down'` |
| `ui`          | `Partial<Record<CollapsibleSlot, string | object>>` | -        |

## Emits

| Event         | Payload   |
| ------------- | --------- |
| `update:open` | `boolean` |

## Slots

| Slot           | Props      | Description                      |
| -------------- | ---------- | -------------------------------- |
| `trigger`      | `{ open }` | The trigger button's own content |
| `default`      | `{ open }` | The collapsible panel's content  |
| `chevron-icon` | `{ open }` | Replaces the default chevron     |


# NavigationMenu

## Usage

`items` is a flat array - `label` is required, everything else is optional:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Docs', to: '/docs' },
  { label: 'Pricing', to: '/pricing' },
  { label: 'About', to: '/about' },
]
</script>

<template>
  <SNavigationMenu :items="items" />
</template>
```


```vue-html
<SNavigationMenu :items="[
  { label: 'Home', to: '/' },
  { label: 'Docs', to: '/docs' },
  { label: 'Pricing', to: '/pricing' },
]" />
```

### Icons

Give an item an `icon` and it renders before its label:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', icon: 'hugeicons:home-01', to: '/' },
  { label: 'Docs', icon: 'hugeicons:book-02', to: '/docs' },
  { label: 'Settings', icon: 'hugeicons:settings-01', to: '/settings' },
]
</script>

<template>
  <SNavigationMenu :items="items" />
</template>
```


```vue-html
<SNavigationMenu :items="[{ label: 'Home', icon: 'hugeicons:home-01', to: '/' }]" />
```

### With children

An item with `children` renders as a trigger instead of a link - clicking
(or hovering) it opens a dropdown. Open dropdowns render in one shared
viewport within the NavigationMenu. By default, the panel is a compact,
single-column list beneath its active trigger. The viewport resizes as
you move between top-level items:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Products', children: [
    { label: 'Analytics', to: '/components/data/table' },
    { label: 'Automation', to: '/components/forms/validation' },
    { label: 'Integrations', to: '/components/overlays/dropdown' },
  ] },
  { label: 'Company', children: [
    { label: 'About', to: '/components/navigation/navigation-menu' },
    { label: 'Careers', to: '/components/layout/header' },
  ] },
]
</script>

<template>
  <SNavigationMenu :items="items" />
</template>
```


```vue-html
<SNavigationMenu :items="[
  { label: 'Products', children: [
    { label: 'Analytics', to: '/components/data/table' },
    { label: 'Automation', to: '/components/forms/validation' },
  ] },
]" />
```

This is a single level of children only - Reka's own shared-viewport
dropdown isn't built for deeper nesting. For an arbitrary-depth tree, use
[Vertical](https://selarasui.my.id/#vertical) instead.

For a wide, multi-column panel, set `contentOrientation="horizontal"`.
This example shows that layout with more items, children, and icons:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', icon: 'hugeicons:home-01', to: '/' },
  { label: 'Products', children: [
    { label: 'Analytics', icon: 'hugeicons:chart-line-data-01', to: '/products/analytics' },
    { label: 'Automation', icon: 'hugeicons:workflow-square-05', to: '/products/automation' },
    { label: 'Integrations', icon: 'hugeicons:plug-01', to: '/products/integrations' },
    { label: 'Security', icon: 'hugeicons:shield-01', to: '/products/security' },
    { label: 'Database', icon: 'hugeicons:database-01', to: '/products/database' },
    { label: 'Reporting', icon: 'hugeicons:file-01', to: '/products/reporting' },
  ] },
  { label: 'Solutions', children: [
    { label: 'For teams', icon: 'hugeicons:user-group', to: '/solutions/teams' },
    { label: 'For enterprise', icon: 'hugeicons:briefcase-01', to: '/solutions/enterprise' },
    { label: 'For developers', icon: 'hugeicons:code-square', to: '/solutions/developers' },
    { label: 'For marketing', icon: 'hugeicons:megaphone-01', to: '/solutions/marketing' },
  ] },
  { label: 'Resources', children: [
    { label: 'Docs', icon: 'hugeicons:book-02', to: '/resources/docs' },
    { label: 'Blog', icon: 'hugeicons:news', to: '/resources/blog' },
    { label: 'Help center', icon: 'hugeicons:help-circle', to: '/resources/help' },
  ] },
  { label: 'Pricing', to: '/pricing' },
]
</script>

<template>
  <SNavigationMenu :items="items" content-orientation="horizontal" />
</template>
```


```vue-html
<SNavigationMenu :items="items" content-orientation="horizontal" />
```

### Content orientation and alignment

For a horizontal navigation bar, `contentOrientation="vertical"` is the
default: a compact, single-column dropdown beneath its active trigger.
`contentOrientation="horizontal"` switches to a full-width, multi-column
dropdown. The navigation bar itself stays horizontal in both layouts.


```vue
<script setup lang="ts">
const align = ref<'start' | 'center' | 'end'>('start')
const items = [
  { label: 'Products', children: [
    { label: 'Analytics', icon: 'hugeicons:analytics-01', to: '/components/data/table' },
    { label: 'Automation', icon: 'hugeicons:workflow-square-01', to: '/components/forms/validation' },
    { label: 'Integrations', icon: 'hugeicons:link-01', to: '/components/overlays/dropdown' },
  ] },
  { label: 'Company', children: [
    { label: 'About', to: '/overview/getting-started/introduction' },
    { label: 'Contact', to: '/components/layout/header' },
  ] },
]
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <div class="flex items-center gap-3">
      <span class="text-sm text-[var(--selaras-resolved-text-muted)]">Dropdown alignment</span>
      <SSelect v-model="align" :items="['start', 'center', 'end']" aria-label="Dropdown alignment" class="w-32" />
    </div>
    <SNavigationMenu :items="items" :positioning="{ align }" />
  </div>
</template>
```


```vue-html
<SNavigationMenu
  :items="items"
  :positioning="{ align: 'start' }"
/>
```

`positioning.align` accepts `start`, `center` (the default), or `end`.
Start and end follow the reading direction, and the compact panel shifts
at screen edges to stay visible. Use `ui.content` to customize its width;
the viewport measures each open panel and resizes with it.

These settings apply only to horizontal navigation; alignment affects
only its compact dropdown. They do not change vertical accordions or
collapsed sidebar flyouts. Configure those flyouts through `popover`.
NavigationMenu's `positioning` currently supports only `align`, rather than
the full set of positioning options available on Popover and Dropdown.

### Active item

An item whose `to` matches the current route is highlighted
automatically, via Reka's own real `active` link state (`aria-current="page"`
included, not just a class). `active` on the item itself overrides the
auto-detected value in either direction - useful for a route that doesn't
map cleanly to one item's `to`, or for a non-navigating item that should
still show as current:


```vue
<script setup lang="ts">
const active = ref(false)

const items = computed(() => [
  { label: 'Home', to: '/' },
  { label: 'Docs', active: active.value },
  { label: 'Pricing', to: '/pricing' },
])
</script>

<template>
  <div class="flex flex-col items-start gap-3">
    <SNavigationMenu :items="items" />
    <SButton size="sm" variant="soft" @click="active = !active">
      Toggle "Docs" active
    </SButton>
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="[{ label: 'Docs', active: true }]" />
```

### Vertical

`orientation="vertical"` switches to a top-to-bottom layout. Unlike
horizontal's single-level dropdown, vertical supports arbitrary-depth
nesting - each level with children renders as its own collapsible
accordion group, closed by default:


```vue
<script setup lang="ts">
const items = [
  { label: 'Getting started', to: '/getting-started' },
  { label: 'Components', children: [
    { label: 'Forms', children: [
      { label: 'Input', to: '/components/forms/input' },
      { label: 'Select', to: '/components/forms/select' },
    ] },
    { label: 'Overlays', children: [
      { label: 'Modal', to: '/components/overlays/modal' },
      { label: 'Slideover', to: '/components/overlays/slideover' },
    ] },
  ] },
  { label: 'API Reference', to: '/api' },
]
</script>

<template>
  <div class="max-w-64">
    <SNavigationMenu :items="items" orientation="vertical" />
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="items" orientation="vertical" />
```

At a more realistic scale - a settings/docs-style sidebar, three levels
deep, icons throughout, mixing leaf links with nested groups, plus an
active and a disabled item:


```vue
<script setup lang="ts">
const items = [
  { label: 'Dashboard', icon: 'hugeicons:dashboard-square-01', to: '/dashboard', active: true },
  { label: 'Account', icon: 'hugeicons:user-account', children: [
    { label: 'Profile', to: '/account/profile' },
    { label: 'Security', children: [
      { label: 'Password', icon: 'hugeicons:square-lock-01', to: '/account/security/password' },
      { label: 'Two-factor auth', icon: 'hugeicons:notification-01', to: '/account/security/2fa' },
    ] },
    { label: 'Billing', icon: 'hugeicons:credit-card', to: '/account/billing' },
  ] },
  { label: 'Developers', icon: 'hugeicons:code', children: [
    { label: 'API keys', icon: 'hugeicons:api', to: '/developers/api-keys' },
    { label: 'Webhooks', icon: 'hugeicons:puzzle', to: '/developers/webhooks' },
    { label: 'Integrations', children: [
      { label: 'GitHub', icon: 'hugeicons:git-branch', to: '/developers/integrations/github' },
      { label: 'Cloud storage', icon: 'hugeicons:cloud', to: '/developers/integrations/cloud' },
    ] },
  ] },
  { label: 'Archived project', icon: 'hugeicons:folder-01', disabled: true },
]
</script>

<template>
  <div class="max-w-64">
    <SNavigationMenu :items="items" orientation="vertical" highlight />
  </div>
</template>
```


### Collapsed

`collapsed` (vertical only) shrinks every item down to just its own icon -
an icon rail, the shape a sidebar nav commonly takes once collapsed. Labels
stay in the DOM for assistive tech (`sr-only`, not removed), so this is
CSS-only and doesn't change what a screen reader announces. A parent with
children renders as a themed flyout trigger instead of an expandable
accordion row - there's no room for a nested list in an icon rail, so its
children surface in a small popover next to the icon instead, the same
pattern a collapsed sidebar commonly uses elsewhere:


```vue
<script setup lang="ts">
const collapsed = ref(true)

const items = [
  { label: 'Overview', icon: 'hugeicons:dashboard-square-01', to: '/overview' },
  { label: 'Analytics', icon: 'hugeicons:chart-line-data-01', children: [
    { label: 'Traffic', to: '/analytics/traffic' },
    { label: 'Conversion', to: '/analytics/conversion' },
  ] },
  { label: 'Settings', icon: 'hugeicons:settings-01', to: '/settings' },
]
</script>

<template>
  <div class="flex flex-col gap-3">
    <SButton size="sm" variant="outline" color="neutral" @click="collapsed = !collapsed">
      {{ collapsed ? 'Expand' : 'Collapse' }}
    </SButton>
    <div :class="collapsed ? 'w-16' : 'w-64'">
      <SNavigationMenu :items="items" orientation="vertical" :collapsed="collapsed" tooltip />
    </div>
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="items" orientation="vertical" collapsed tooltip />
```

### Collapsed labels and flyouts

Add `tooltip` to show a collapsed leaf's label on hover or keyboard focus.
Its text defaults to `ariaLabel`, then `label`. Disabled items, group labels,
and separators do not show tooltips. Expanded and horizontal menus are unaffected.
Wrap your application in `SApp` to provide the shared tooltip context.

```vue-html
<SNavigationMenu
  :items="items"
  orientation="vertical"
  collapsed
  :tooltip="{ delayDuration: 150, arrow: false }"
  :popover="{ side: 'right', positioning: { sideOffset: 10 } }"
/>
```

Use an item's `tooltip: false` to opt out, or an object such as
`tooltip: { text: 'Account settings', side: 'left' }` to override that item.
Global and item tooltip settings are merged, with item settings taking priority.
Tooltips default to an immediate opening on the right in LTR and left in RTL.
The link remains the trigger, preserving navigation, shortcuts, and custom item slots.

Items with children keep their child flyout rather than adding a competing tooltip.
`popover` configures its side, alignment, positioning, portal, arrow, and `ui`;
an item's `popover` overrides the menu settings. Flyouts remain enabled and retain
hover, click, and keyboard behavior. Their default side also follows text direction.

### Labels and separators

An item can be a real link (the default), or `type: 'label'`/`type: 'separator'`
instead - a non-interactive section heading and a thin divider line,
respectively. Both are just items in the same flat array, not a wrapping
structure - a "group" is nothing more than a `label` item followed by the
items it introduces:


```vue
<script setup lang="ts">
const collapsed = ref(false)
const items = [
  { label: 'Guide', type: 'label' as const },
  { label: 'Introduction', to: '/introduction' },
  { label: 'Installation', to: '/installation' },
  { label: 'sep-1', type: 'separator' as const },
  { label: 'Components', type: 'label' as const },
  { label: 'Button', to: '/components/button' },
  { label: 'Input', to: '/components/input' },
]
</script>

<template>
  <div class="flex flex-col items-start gap-3">
    <SButton size="sm" variant="outline" @click="collapsed = !collapsed">
      {{ collapsed ? 'Expand groups' : 'Collapse groups' }}
    </SButton>
    <div :class="collapsed ? 'w-16' : 'w-64'">
      <SNavigationMenu :items="items" orientation="vertical" :collapsed="collapsed" tooltip />
    </div>
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="[
  { label: 'Guide', type: 'label' },
  { label: 'Introduction', to: '/introduction' },
  { label: 'Installation', to: '/installation' },
  { label: 'sep-1', type: 'separator' },
  { label: 'Components', type: 'label' },
  { label: 'Button', to: '/components/button' },
]" orientation="vertical" />
```

In a collapsed vertical rail, headings stay in the DOM but are visually hidden.
By default, `collapsedGroups="separator"` adds a thin line between populated
sections. Use `"spacing"` for a gap or `"none"` for no automatic boundary.
The same `items` array works when expanding and collapsing. Explicit separator
items still draw lines in all three modes; collapsed rails remove leading,
trailing, and repeated separators. Empty sections do not add visible boundaries.
Horizontal menus are unchanged.

```vue-html
<SNavigationMenu :items="items" orientation="vertical" collapsed collapsed-groups="spacing" tooltip />
```

Use `ui.separator`, `ui.groupSpacer`, and `ui.collapsedGroupLabel` to customize
the line, gap, and visually hidden heading respectively. None become focusable
menu actions; link labels and tooltips retain their existing behavior.

A `separator` item still needs a unique `label` even though it's never
displayed - every item's `label` doubles as its list key. Top-level only:
a `children` array doesn't check `type`, so a nested tree can't group its
own children under a sub-heading.

### Variant

`variant="pill"` (default) gives the active item a filled background;
`variant="link"` only changes its text color, no background:


```vue
<script setup lang="ts">
const variants = ['pill', 'link'] as const
const variant = ref<typeof variants[number]>('pill')

const items = [
  { label: 'Home', to: '/', active: true },
  { label: 'Docs', to: '/docs' },
  { label: 'Pricing', to: '/pricing' },
]
</script>

<template>
  <div class="flex flex-col items-start gap-3">
    <SButtonGroup>
      <SButton
        v-for="v in variants"
        :key="v"
        variant="soft"
        :color="variant === v ? 'primary' : 'neutral'"
        @click="variant = v"
      >
        {{ v }}
      </SButton>
    </SButtonGroup>
    <SNavigationMenu :items="items" :variant="variant" />
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="items" variant="link" />
```

### Highlight

`highlight` draws a small bar next to the active item, in addition to its
own color styling - a line under it in horizontal, or beside it in
vertical:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Docs', to: '/docs', active: true },
  { label: 'Pricing', to: '/pricing' },
]
</script>

<template>
  <SNavigationMenu :items="items" highlight />
</template>
```


```vue-html
<SNavigationMenu :items="items" highlight />
```

### Disabled item

`disabled` on an item keeps it visible but non-interactive - no
navigation, no `onSelect`, marked `aria-disabled`:


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Docs', to: '/docs' },
  { label: 'Coming soon', disabled: true },
]
</script>

<template>
  <SNavigationMenu :items="items" />
</template>
```


```vue-html
<SNavigationMenu :items="[{ label: 'Coming soon', disabled: true }]" />
```

### Shortcuts

`shortcut` displays a Kbd hint next to a leaf item. Set `hotkey: true` to
bind it, so the key activates that item from anywhere on the page. It stays
inactive while someone is typing in a field. `mod` maps to ⌘ on macOS and Ctrl
on other platforms. A leaf can navigate with `to` or run `onSelect` like a
button.


```vue
<script setup lang="ts">
const lastAction = ref('')

const items = [
  { label: 'Overview', icon: 'hugeicons:home-01', shortcut: 'mod+1', hotkey: true, onSelect: () => lastAction.value = 'Overview selected' },
  { label: 'Settings', icon: 'hugeicons:settings-01', shortcut: 'mod+2', hotkey: true, onSelect: () => lastAction.value = 'Settings selected' },
  { label: 'Help', icon: 'hugeicons:help-circle', shortcut: 'mod+/', onSelect: () => lastAction.value = 'Help selected' },
]
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SNavigationMenu :items="items" />
    <p v-if="lastAction" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ lastAction }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const lastAction = ref('')
const items = [
  { label: 'Overview', shortcut: 'mod+1', hotkey: true, onSelect: () => lastAction.value = 'Overview selected' },
  { label: 'Settings', shortcut: 'mod+2', hotkey: true, onSelect: () => lastAction.value = 'Settings selected' },
  { label: 'Help', shortcut: 'mod+/', onSelect: () => lastAction.value = 'Help selected' },
]
</script>

<template>
  <SNavigationMenu :items="items" />
</template>
```

Press ⌘1 or ⌘2 (Ctrl on other platforms) to select an item. `Help` shows a
hint but does not bind the key because it omits `hotkey: true`.

### Color

`color` follows the same palette as every other component here
(`primary`, `neutral`, `secondary`, `success`, `danger`, `info`,
`warning`) and only affects the active item:


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const

const items = [
  { label: 'Home', to: '/' },
  { label: 'Docs', to: '/docs', active: true },
  { label: 'Pricing', to: '/pricing' },
]
</script>

<template>
  <div class="flex flex-col gap-4">
    <SNavigationMenu v-for="color in colors" :key="color" :items="items" :color="color" />
  </div>
</template>
```


```vue-html
<SNavigationMenu :items="items" color="secondary" />
```

### Customizing content

Every rendering spot has a matching slot, scoped with the item's own
data - `item-leading`/`item-label`/`item-trailing` replace one piece at a
time, `item` replaces a whole item's content, and `item-content` replaces
an entire dropdown's body, letting you build a genuine multi-column mega
menu instead of the default single-column list:

Open **Products** to see the generic `item-content` layout, or **Help** to
see the per-item `help-content` override.


```vue
<script setup lang="ts">
const items = [
  { label: 'Home', to: '/' },
  { label: 'Products', children: [
    { label: 'Analytics', to: '/components/data/table', icon: 'hugeicons:chart-line-data-01', description: 'Track usage across your app.' },
    { label: 'Automation', to: '/components/forms/validation', icon: 'hugeicons:workflow-square-05', description: 'Trigger workflows on events.' },
    { label: 'Integrations', to: '/components/overlays/dropdown', icon: 'hugeicons:plug-01', description: 'Connect your existing tools.' },
    { label: 'Reporting', to: '/components/typography/code-group', icon: 'hugeicons:file-01', description: 'Export data on a schedule.' },
  ] },
  // `slot: 'help'` targets #help-content specifically, ahead of the
  // generic #item-content every other item with children falls back to.
  { label: 'Help', slot: 'help', children: [
    { label: 'Docs', to: '/components/overlays/command-palette' },
  ] },
]
</script>

<template>
  <SNavigationMenu :items="items" content-orientation="horizontal">
    <template #item-content="{ item }">
      <ul class="grid w-full grid-cols-[repeat(auto-fit,minmax(14rem,1fr))] gap-2 p-2">
        <li v-for="child in item.children" :key="child.label">
          <NuxtLink :to="child.to" class="flex flex-col gap-1 rounded-[var(--selaras-resolved-radius-md)] p-3 hover:bg-[var(--selaras-resolved-surface-elevated)]">
            <span class="flex items-center gap-2 text-sm font-medium text-[var(--selaras-resolved-text-default)]">
              <SIcon v-if="child.icon" :name="child.icon" class="size-4" />
              {{ child.label }}
            </span>
            <span class="text-xs text-[var(--selaras-resolved-text-muted)]">{{ child.description }}</span>
          </NuxtLink>
        </li>
      </ul>
    </template>

    <template #help-content="{ item }">
      <div class="w-56 p-3 text-sm">
        <p class="mb-2 text-[var(--selaras-resolved-text-muted)]">
          Need a hand?
        </p>
        <NuxtLink v-for="child in item.children" :key="child.label" :to="child.to" class="block py-1 text-[var(--selaras-resolved-color-primary-text)]">
          {{ child.label }} →
        </NuxtLink>
      </div>
    </template>
  </SNavigationMenu>
</template>
```


```vue-html
<SNavigationMenu :items="items" content-orientation="horizontal">
  <template #item-content="{ item }">
    <ul class="grid w-96 grid-cols-2 gap-2 p-2">
      <li v-for="child in item.children" :key="child.label">
        <NuxtLink :to="child.to">{{ child.label }}</NuxtLink>
      </li>
    </ul>
  </template>
</SNavigationMenu>
```

Every one of these slots also has a **per-item** form: set `slot` on one
item and it targets `#{slot}-content` (or `-leading`/`-label`/`-trailing`)
ahead of the generic slot above - useful when only one or two items need
bespoke content and the rest are happy with the default:

```vue-html
<SNavigationMenu :items="[{ label: 'Help', slot: 'help', children: [...] }]">
  <template #help-content="{ item }">
    <!-- only this item's dropdown uses this -->
  </template>
</SNavigationMenu>
```

`list-leading`/`list-trailing` sit outside the item list entirely -
useful for a logo or a call-to-action button alongside the menu:

```vue-html
<SNavigationMenu :items="items">
  <template #list-leading>
    <img src="/logo.svg" class="h-6">
  </template>
  <template #list-trailing>
    <SButton size="sm">Sign up</SButton>
  </template>
</SNavigationMenu>
```

These same slots work identically in vertical mode.

### Custom `:ui`

Global and scoped recipe overrides use `ui.navigationMenu`. The recursive
accordion and collapsed flyout renderers intentionally consume that same key;
they are implementation details rather than separate theme surfaces.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `NavigationMenu`'s own theme file:

:theme-source{name="navigation-menu"}

## Props

| Prop                 | Type                                                                              | Default               |
| -------------------- | --------------------------------------------------------------------------------- | --------------------- |
| `items`              | `NavigationMenuItem[]`                                                            | - (required)          |
| `orientation`        | `'horizontal' | 'vertical'`                                                       | `'horizontal'`        |
| `contentOrientation` | `'horizontal' | 'vertical'`                                                       | `'vertical'`          |
| `positioning`        | `NavigationMenuPositioning` (`{ align?: 'start' | 'center' | 'end' }`)            | `{ align: 'center' }` |
| `color`              | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'primary'`           |
| `variant`            | `'pill' | 'link'`                                                                 | `'pill'`              |
| `highlight`          | `boolean`                                                                         | `false`               |
| `collapsed`          | `boolean`                                                                         | `false`               |
| `collapsedGroups`    | `'separator' | 'spacing' | 'none'`                                                | `'separator'`         |
| `tooltip`            | `boolean | TooltipProps`                                                          | `false`               |
| `popover`            | `NavigationMenuPopover`                                                           | -                     |
| `ui`                 | `Partial<Record<NavigationMenuSlot, string | object>>`                            | -                     |

`NavigationMenuItem`:

| Field         | Type                             | Description                                                                                                                                                                                                                                                                                                                          |
| ------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`       | `string`                         | Required.                                                                                                                                                                                                                                                                                                                            |
| `icon`        | `string`                         | Rendered before the label.                                                                                                                                                                                                                                                                                                           |
| `to`          | `string`                         | Route path for a leaf item.                                                                                                                                                                                                                                                                                                          |
| `disabled`    | `boolean`                        | Visible but non-interactive.                                                                                                                                                                                                                                                                                                         |
| `active`      | `boolean`                        | Overrides the auto-detected route match.                                                                                                                                                                                                                                                                                             |
| `children`    | `NavigationMenuItem[]`           | One level for horizontal; arbitrary depth for vertical.                                                                                                                                                                                                                                                                              |
| `description` | `string`                         | Not read by NavigationMenu's own default rendering - carried purely so a custom `#item-content`/`#{slot}-content` slot override can display one (a "mega menu" style description under each link, say) - see [Customizing content](https://selarasui.my.id/#customizing-content), whose own live example already renders this field. |
| `onSelect`    | `(event: Event) => void`         | Fired when a leaf item is activated.                                                                                                                                                                                                                                                                                                 |
| `shortcut`    | `string`                         | Displays a Kbd hint beside the item.                                                                                                                                                                                                                                                                                                 |
| `hotkey`      | `boolean`                        | Binds `shortcut` page-wide, except while typing in a field.                                                                                                                                                                                                                                                                          |
| `slot`        | `string`                         | Targets this item's own named slots ahead of the generic ones - see [Customizing content](https://selarasui.my.id/#customizing-content).                                                                                                                                                                                             |
| `type`        | `'link' | 'label' | 'separator'` | `'link'` unless set - see [Labels and separators](https://selarasui.my.id/#labels-and-separators).                                                                                                                                                                                                                                   |

## Slots

| Slot            | Scope              | Description                                                                         |
| --------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `item`          | `{ item, active }` | Replaces an item's entire content (icon+label, or icon+label+chevron for a trigger) |
| `item-leading`  | `{ item, active }` | Replaces the leading icon                                                           |
| `item-label`    | `{ item, active }` | Replaces the label text - also the only slot a `type: 'label'` item uses            |
| `item-trailing` | `{ item, active }` | Replaces the trailing content (the chevron, for a trigger)                          |
| `item-content`  | `{ item }`         | Replaces an entire dropdown/accordion body                                          |
| `list-leading`  | -                  | Rendered before the item list                                                       |
| `list-trailing` | -                  | Rendered after the item list                                                        |

Every slot above also has a per-item form via `item.slot` - see
[Customizing content](https://selarasui.my.id/#customizing-content).


# Pagination

## Usage


```vue
<script setup lang="ts">
const page = ref(1)
</script>

<template>
  <SPagination v-model:page="page" :total="120" :items-per-page="10" />
</template>
```


```vue
<script setup lang="ts">
const page = ref(1)
</script>

<template>
  <SPagination v-model:page="page" :total="120" :items-per-page="10" />
</template>
```

### Sizes

`size` takes `sm` / `md` / `lg`, scaling every button (and the ellipsis, to
stay aligned with them) together:


```vue
<script setup lang="ts">
const sm = ref(2)
const md = ref(2)
const lg = ref(2)
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SPagination v-model:page="sm" size="sm" :total="50" :items-per-page="10" />
    <SPagination v-model:page="md" size="md" :total="50" :items-per-page="10" />
    <SPagination v-model:page="lg" size="lg" :total="50" :items-per-page="10" />
  </div>
</template>
```


```vue-html
<SPagination v-model:page="page" size="sm" :total="50" :items-per-page="10" />
<SPagination v-model:page="page" size="md" :total="50" :items-per-page="10" />
<SPagination v-model:page="page" size="lg" :total="50" :items-per-page="10" />
```

### Sibling count & edges

`sibling-count` controls how many page numbers show on either side of the
current page before collapsing into an ellipsis; `show-edges` (on by
default) keeps page 1 and the last page visible for quick jumping even when
they'd otherwise fall inside a collapsed range:


```vue
<script setup lang="ts">
const tight = ref(10)
const wide = ref(10)
const noEdges = ref(10)
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <SPagination v-model:page="tight" :total="200" :items-per-page="10" :sibling-count="1" />
    <SPagination v-model:page="wide" :total="200" :items-per-page="10" :sibling-count="3" />
    <SPagination v-model:page="noEdges" :total="200" :items-per-page="10" :sibling-count="1" :show-edges="false" />
  </div>
</template>
```


```vue-html
<SPagination v-model:page="page" :total="200" :items-per-page="10" :sibling-count="1" />
<SPagination v-model:page="page" :total="200" :items-per-page="10" :sibling-count="3" />
<SPagination v-model:page="page" :total="200" :items-per-page="10" :sibling-count="1" :show-edges="false" />
```

### Links

`to` maps a page number to a route/href, rendering every control as a real
`<a>` instead of a plain button - useful for crawlable, SEO-friendly
pagination on a content site. Clicking still drives the page change through
the same handling as a plain button (no full navigation) - `to` only
changes what markup renders, not the behavior:


```vue
<script setup lang="ts">
const page = ref(1)
</script>

<template>
  <SPagination
    v-model:page="page"
    :total="120"
    :items-per-page="10"
    :to="(p) => `#page-${p}`"
  />
</template>
```


```vue-html
<SPagination v-model:page="page" :total="120" :items-per-page="10" :to="(p) => `/posts?page=${p}`" />
```

### Hiding controls

`show-controls` (on by default) toggles Previous/Next - set it `false` for
a bare page-number-only strip:


```vue
<script setup lang="ts">
const page = ref(1)
</script>

<template>
  <SPagination v-model:page="page" :total="50" :items-per-page="10" :show-controls="false" />
</template>
```


```vue-html
<SPagination v-model:page="page" :total="50" :items-per-page="10" :show-controls="false" />
```

### Color & variant

`color`/`variant` style every inactive control (First/Prev/Next/Last and
non-current page numbers); `active-color`/`active-variant` style the
current page's own button separately:


```vue
<script setup lang="ts">
const page = ref(1)
</script>

<template>
  <SPagination v-model:page="page" :total="50" :items-per-page="10" color="primary" variant="outline" active-color="danger" active-variant="solid" />
</template>
```


```vue-html
<SPagination
  v-model:page="page"
  :total="50"
  :items-per-page="10"
  color="primary"
  variant="outline"
  active-color="danger"
  active-variant="solid"
/>
```

### First/Last buttons

`show-first-last` adds jump-to-first/jump-to-last buttons on either end,
alongside the Previous/Next buttons that are always shown:


```vue
<script setup lang="ts">
const page = ref(10)
</script>

<template>
  <SPagination v-model:page="page" :total="200" :items-per-page="10" show-first-last />
</template>
```


```vue-html
<SPagination v-model:page="page" :total="200" :items-per-page="10" show-first-last />
```

### Disabled

`disabled` disables every button at once, regardless of which page is
current:


```vue
<script setup lang="ts">
const page = ref(3)
</script>

<template>
  <SPagination v-model:page="page" :total="120" :items-per-page="10" disabled />
</template>
```


```vue-html
<SPagination v-model:page="page" :total="120" :items-per-page="10" disabled />
```

### Accessibility

Pagination renders Reka UI's Pagination primitive, so most of the
accessibility semantics come from there: the root is a `<nav>` landmark
(labeled "Pagination" by default, translatable via the message registry),
each page-number button gets its own `aria-label="Page N"` plus
`aria-current="page"` on whichever one is current, and Previous/Next/First/
Last are icon-only buttons labeled via the message registry (`Previous`,
`Next`, `First`, `Last`) rather than left unlabeled. Previous/Next/First/Last
disable themselves automatically at the relevant boundary (Previous/First on
page 1, Next/Last on the last page) - that boundary logic comes from the
underlying primitive, not something this component reimplements.

### Custom `:ui`

Global and scoped `ui.pagination` overrides cover the root, page list, and
ellipsis. Page controls are Button instances: use Pagination's color/variant
props for their presentation and `ui.button` for shared Button recipe changes.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Pagination`'s own theme file:

:theme-source{name="pagination"}

## Props

| Prop            | Type                                                                              | Default     |
| --------------- | --------------------------------------------------------------------------------- | ----------- |
| `total`         | `number`                                                                          | `0`         |
| `itemsPerPage`  | `number`                                                                          | `10`        |
| `page`          | `number`                                                                          | -           |
| `defaultPage`   | `number`                                                                          | `1`         |
| `siblingCount`  | `number`                                                                          | `1`         |
| `showEdges`     | `boolean`                                                                         | `true`      |
| `showFirstLast` | `boolean`                                                                         | `false`     |
| `showControls`  | `boolean`                                                                         | `true`      |
| `to`            | `(page: number) => string`                                                        | -           |
| `disabled`      | `boolean`                                                                         | `false`     |
| `size`          | `'sm' | 'md' | 'lg'`                                                              | `md`        |
| `color`         | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `'neutral'` |
| `variant`       | `'solid' | 'soft' | 'outline' | 'ghost' | 'text'`                                 | `'ghost'`   |
| `activeColor`   | same as `color`                                                                   | `'primary'` |
| `activeVariant` | same as `variant`                                                                 | `'solid'`   |
| `ui`            | `Partial<Record<'root' | 'list' | 'ellipsis', string | object>>`                  | -           |

## Emits

| Emit          | Payload  | Description                                                                                              |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `update:page` | `number` | Fires whenever the current page changes, whether from a page-number button, Previous/Next, or First/Last |


# Stepper

## Usage

`Stepper` only tracks and displays *which* step is current - `v-model`
is a plain 1-indexed `number`, and pairing it with your own step content
and Back/Next buttons is up to you, the same way `v-model` composes with
anything else:


```vue
<script setup lang="ts">
const items = [
  { title: 'Cart' },
  { title: 'Shipping' },
  { title: 'Payment' },
]
const step = ref(1)
</script>

<template>
  <div class="flex w-full flex-col gap-4">
    <SStepper v-model="step" :items="items" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Step {{ step }}: {{ items[step - 1]?.title }}
    </p>
    <div class="flex gap-2">
      <SButton
        variant="outline"
        color="neutral"
        :disabled="step === 1"
        @click="step--"
      >
        Back
      </SButton>
      <SButton :disabled="step === items.length" @click="step++">
        Next
      </SButton>
    </div>
  </div>
</template>
```


```vue
<script setup lang="ts">
const items = [{ title: 'Cart' }, { title: 'Shipping' }, { title: 'Payment' }]
const step = ref(1)
</script>

<template>
  <SStepper v-model="step" :items="items" />
  <SButton :disabled="step === 1" @click="step--">
    Back
  </SButton>
  <SButton :disabled="step === items.length" @click="step++">
    Next
  </SButton>
</template>
```

By default, clicking a step only ever advances at most one step ahead of
the current one - going back to any earlier (completed) step is always
allowed. Pass `linear="false"` to allow jumping to any step directly:


```vue
<script setup lang="ts">
const items = [
  { title: 'One' },
  { title: 'Two' },
  { title: 'Three' },
  { title: 'Four' },
]
</script>

<template>
  <SStepper :items="items" :linear="false" />
</template>
```


```vue-html
<SStepper :items="items" :linear="false" />
```

### Descriptions

Each item can carry a `description` alongside its `title`:


```vue
<script setup lang="ts">
const items = [
  { title: 'Address', description: 'Where to ship' },
  { title: 'Delivery', description: 'Pick a speed' },
  { title: 'Review', description: 'Confirm order' },
]
</script>

<template>
  <SStepper :items="items" :default-value="2" />
</template>
```


```vue-html
<SStepper :items="[{ title: 'Address', description: 'Where to ship' }, ...]" />
```

### Icons

Each item can carry an `icon`, shown once its step is active or upcoming

- a completed step always shows a checkmark instead, regardless of `icon`:


```vue
<script setup lang="ts">
const items = [
  { title: 'Account', icon: 'hugeicons:user' },
  { title: 'Preferences', icon: 'hugeicons:settings-01' },
  { title: 'Billing', icon: 'hugeicons:credit-card' },
]
</script>

<template>
  <SStepper :items="items" :default-value="2" />
</template>
```


```vue-html
<SStepper :items="[{ title: 'Account', icon: 'hugeicons:user' }, ...]" />
```

### Custom slots

`#indicator`, `#title`, and `#description` each replace that part
entirely, scoped with the item, its index, and its `state` - useful for
always showing an item's own icon (instead of falling back to a
checkmark once completed) or annotating the active step:


```vue
<script setup lang="ts">
const items = [
  { title: 'Draft', icon: 'hugeicons:pencil' },
  { title: 'Review', icon: 'hugeicons:search-01' },
  { title: 'Published', icon: 'hugeicons:checkmark-circle-01' },
]
</script>

<template>
  <SStepper :items="items" :default-value="2">
    <template #indicator="{ item }">
      <SIcon v-if="item.icon" :name="item.icon" class="size-4" />
    </template>
    <template #title="{ item, state }">
      {{ item.title }}
      <span v-if="state === 'active'" class="text-[var(--selaras-resolved-color-primary-text)]">· current</span>
    </template>
  </SStepper>
</template>
```


```vue-html
<SStepper :items="items">
  <template #indicator="{ item }">
    <SIcon :name="item.icon" class="size-4" />
  </template>
  <template #title="{ item, state }">
    {{ item.title }}
    <span v-if="state === 'active'">· current</span>
  </template>
</SStepper>
```

### Vertical


```vue
<script setup lang="ts">
const items = [
  { title: 'Account', description: 'Create your login' },
  { title: 'Profile', description: 'Tell us about yourself' },
  { title: 'Confirm', description: 'Review and finish' },
]
</script>

<template>
  <SStepper :items="items" orientation="vertical" :default-value="2" class="max-w-64" />
</template>
```


```vue-html
<SStepper :items="items" orientation="vertical" />
```

### Color


```vue
<script setup lang="ts">
const colors = ['primary', 'neutral', 'secondary', 'success', 'danger', 'info', 'warning'] as const
const items = [{ title: 'One' }, { title: 'Two' }, { title: 'Three' }]
</script>

<template>
  <div class="flex w-full flex-col gap-6">
    <SStepper v-for="color in colors" :key="color" :items="items" :color="color" :default-value="2" />
  </div>
</template>
```


```vue-html
<SStepper :items="items" color="success" />
```

## Progress announcements

Stepper has one visually hidden, polite live region announcing the current step.
Its English default is `Step 1 of 2`. Translate it globally through the
[message registry](https://selarasui.my.id/overview/getting-started/messages):

```ts
export default defineAppConfig({
  selaras: {
    messages: {
      stepper: 'Progres',
      stepperProgress: (step, total) => `Langkah ${step} dari ${total}`,
    },
  },
})
```

`stepper` names the root group; an explicit `aria-label` on the component takes
priority. `stepperProgress(step, total)` formats the live-region message.
Changing `selaras.locale` formats locale-aware values but does not translate UI
messages automatically. Update the message registry when switching languages;
announcements react to those changes and to step or item-count changes.

For one instance, the `progress` slot replaces only the announcement text.
Keep it concise; the component supplies the live-region semantics and hiding.
An empty item list has no default announcement.


```vue
<script setup lang="ts">
const step = ref(1)
const items = [{ title: 'Atur kunci' }, { title: 'Simpan kunci' }]
</script>

<template>
  <SStepper v-model="step" :items="items" aria-label="Progres pembuatan kunci">
    <template #progress="{ step: currentStep, total }">
      Langkah {{ currentStep }} dari {{ total }}
    </template>
  </SStepper>
</template>
```


```vue-html
<SStepper v-model="step" :items="items" aria-label="Progres pembuatan kunci">
  <template #progress="{ step: currentStep, total }">
    Langkah {{ currentStep }} dari {{ total }}
  </template>
</SStepper>
```

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-stepper{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally). `items` is an array prop, not a string - bind
it with a leading `:` so `@nuxtjs/mdc` parses the attribute as an expression
instead of literal text. Unlike [Tabs](https://selarasui.my.id/components/navigation/tabs) or
[Accordion](https://selarasui.my.id/components/navigation/accordion), each step's own text comes
from its `title`/`description` fields directly, not a per-item slot - the
block needs no body at all:

```md
::s-stepper{:items='[{"title":"Cart"},{"title":"Shipping"},{"title":"Payment"}]'}
::
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.stepper`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Stepper`'s own theme file:

:theme-source{name="stepper"}

## Props

| Prop           | Type                                                                              | Default      |
| -------------- | --------------------------------------------------------------------------------- | ------------ |
| `items`        | `Step[]`                                                                          | -            |
| `modelValue`   | `number`                                                                          | -            |
| `defaultValue` | `number`                                                                          | -            |
| `linear`       | `boolean`                                                                         | `true`       |
| `orientation`  | `'horizontal' | 'vertical'`                                                       | `horizontal` |
| `size`         | `'sm' | 'md' | 'lg'`                                                              | `md`         |
| `color`        | `'primary' | 'neutral' | 'secondary' | 'success' | 'danger' | 'info' | 'warning'` | `primary`    |
| `ui`           | `Partial<Record<StepperSlot, string | object>>`                                   | -            |

`Step` is `{ title?: string, description?: string, icon?: string, disabled?: boolean }`.

## Events

| Event               | Payload  | Description                            |
| ------------------- | -------- | -------------------------------------- |
| `update:modelValue` | `number` | Fires when a step's trigger is clicked |

## Slots

| Slot          | Props                    | Description                                                                                                          |
| ------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `progress`    | `{ step, total }`        | Replaces the screen-reader progress text; `step` may be undefined when no step is active                             |
| `indicator`   | `{ item, index, state }` | Replaces the indicator's content (default: a checkmark once completed, else the item's `icon`, else the step number) |
| `title`       | `{ item, index, state }` | Replaces the title text                                                                                              |
| `description` | `{ item, index, state }` | Replaces the description text                                                                                        |

`state` is `'inactive' \| 'active' \| 'completed'`.


# Tabs

## Usage


```vue
<script setup lang="ts">
const active = ref('one')
</script>

<template>
  <STabs v-model="active" :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]">
    <template #one>
      Tab one content
    </template>
    <template #two>
      Tab two content
    </template>
  </STabs>
</template>
```


```vue
<script setup lang="ts">
const active = ref('one')
</script>

<template>
  <STabs v-model="active" :items="[{ label: 'One', value: 'one' }, { label: 'Two', value: 'two' }]">
    <template #one>
      Tab one content
    </template>
    <template #two>
      Tab two content
    </template>
  </STabs>
</template>
```

Switching tabs slides a shared indicator between them rather than each tab
carrying its own static active state - the indicator measures the active
trigger itself, so it stays correct even if a tab's own width changes.

### Custom label content

The `label` slot replaces a tab's plain-text label with anything - scoped
with `item` and `index`, so a single template can vary per tab:


```vue
<script setup lang="ts">
const active = ref('inbox')
const items = [
  { label: 'Inbox', value: 'inbox' },
  { label: 'Archive', value: 'archive' },
]
</script>

<template>
  <STabs v-model="active" :items="items">
    <template #label="{ item }">
      <span class="flex items-center gap-2">
        {{ item.label }}
        <SBadge v-if="item.value === 'inbox'" label="3" color="primary" size="sm" />
      </span>
    </template>
    <template #inbox>
      3 unread messages.
    </template>
    <template #archive>
      Nothing archived yet.
    </template>
  </STabs>
</template>
```


```vue-html
<STabs v-model="active" :items="items">
  <template #label="{ item }">
    <span class="flex items-center gap-2">
      {{ item.label }}
      <SBadge v-if="item.value === 'inbox'" label="3" color="primary" size="sm" />
    </span>
  </template>
  ...
</STabs>
```

### Icons

Give an item an `icon` and it renders before the label automatically - no
`label` slot needed for the common case:


```vue
<script setup lang="ts">
const active = ref('profile')
const items = [
  { label: 'Profile', value: 'profile', icon: 'hugeicons:user' },
  { label: 'Settings', value: 'settings', icon: 'hugeicons:settings-01' },
]
</script>

<template>
  <STabs v-model="active" :items="items">
    <template #profile>
      Profile details.
    </template>
    <template #settings>
      Account settings.
    </template>
  </STabs>
</template>
```


```vue-html
<STabs
  v-model="active"
  :items="[
    { label: 'Profile', value: 'profile', icon: 'hugeicons:user' },
    { label: 'Settings', value: 'settings', icon: 'hugeicons:settings-01' },
  ]"
/>
```

### Variants

`variant` takes `underline` (default) or `pill`, a segmented-control look
with the sliding indicator as a raised background instead of a bottom bar:


```vue
<script setup lang="ts">
const active = ref('day')
const items = [
  { label: 'Day', value: 'day' },
  { label: 'Week', value: 'week' },
  { label: 'Month', value: 'month' },
]
</script>

<template>
  <STabs v-model="active" :items="items" variant="pill">
    <template #day>
      Showing today.
    </template>
    <template #week>
      Showing this week.
    </template>
    <template #month>
      Showing this month.
    </template>
  </STabs>
</template>
```


```vue-html
<STabs v-model="active" :items="items" variant="pill" />
```

### Scrollable

Set `scrollable` when a tab list may outgrow its container. Previous and next
chevrons appear only while the labels overflow. The list also supports touch,
trackpad, and keyboard navigation, and brings the selected tab into view:


```vue
<script setup lang="ts">
const active = ref('tab-1')
const items = Array.from({ length: 12 }, (_, index) => ({
  label: `Tab ${index + 1}`,
  value: `tab-${index + 1}`,
}))
</script>

<template>
  <STabs v-model="active" :items="items" scrollable class="w-full max-w-xl">
    <template v-for="item in items" :key="item.value" #[item.value]>
      Showing {{ item.label }}.
    </template>
  </STabs>
</template>
```


```vue-html
<STabs v-model="active" :items="items" scrollable />
```

The controls use neutral ghost `SButton`s by default. Use `ui.scrollButton`
and `ui.scrollIcon` for styling, or the `scroll-left-icon` and
`scroll-right-icon` slots to replace only the chevrons. For a different control,
replace `scroll-left` or `scroll-right` and bind the supplied `buttonProps` so
the button keeps its click handler, disabled state, type, and accessible label:

```vue-html
<STabs :items="items" scrollable>
  <template #scroll-right="{ buttonProps }">
    <MyIconButton v-bind="buttonProps" />
  </template>
</STabs>
```

The full button slots also expose `scroll`, `disabled`, and `ariaLabel` for
custom controls that cannot use `v-bind="buttonProps"`.

### Orientation

Set `orientation="vertical"` to place the tab list beside its content. Both
`underline` and `pill` variants work vertically, and Reka changes arrow-key
navigation to Up/Down. `scrollable` applies only to horizontal tabs.


```vue
<script setup lang="ts">
const active = ref('account')
const items = [
  { label: 'Account', value: 'account' },
  { label: 'Security', value: 'security' },
  { label: 'Notifications', value: 'notifications' },
]
</script>

<template>
  <STabs v-model="active" :items="items" orientation="vertical" variant="pill" class="max-w-xl">
    <template #account>
      Manage your account details.
    </template>
    <template #security>
      Review your security settings.
    </template>
    <template #notifications>
      Choose which notifications you receive.
    </template>
  </STabs>
</template>
```


```vue-html
<STabs v-model="active" :items="items" orientation="vertical" variant="pill" />
```

### Keep inactive panels mounted

Inactive panel content is unmounted by default. Set `unmount-on-hide` to
`false` to keep its local state, such as an unfinished form, while the panel
is hidden:

```vue-html
<STabs :items="items" :unmount-on-hide="false">
  <!-- panel slots -->
</STabs>
```

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name - a bare `::s-tabs{...}` block works with no extra wiring (see
[Callout](https://selarasui.my.id/components/typography/callout)'s own "In markdown" section for how
the pattern works generally). `items` is an array prop, not a string - bind
it with a leading `:` so `@nuxtjs/mdc` parses the attribute as an expression
instead of literal text. Each tab's own content is a `#slot-name` line
matching that item's `value`:

```text
::s-tabs{:items='[{"label":"One","value":"one"},{"label":"Two","value":"two"}]'}
#one
Content for the first tab.
#two
Content for the second tab.
::
```

### Custom `:ui`

Global and scoped recipe overrides use `ui.tabs`.

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Tabs`'s own theme file:

:theme-source{name="tabs"}

## Props

| Prop            | Type                                                                                                                                                                 | Default        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `items`         | `{ label: string; value?: string; disabled?: boolean; icon?: string }[]`                                                                                             | -              |
| `variant`       | `'underline' | 'pill'`                                                                                                                                               | `'underline'`  |
| `orientation`   | `'horizontal' | 'vertical'`                                                                                                                                          | `'horizontal'` |
| `scrollable`    | `boolean`                                                                                                                                                            | `false`        |
| `unmountOnHide` | `boolean`                                                                                                                                                            | `true`         |
| `modelValue`    | `string`                                                                                                                                                             | -              |
| `ui`            | `Partial<Record<'root' | 'scrollRoot' | 'scrollViewport' | 'scrollButton' | 'scrollIcon' | 'list' | 'trigger' | 'icon' | 'indicator' | 'content', string | object>>` | -              |

## Events

| Event               | Payload  | Description                       |
| ------------------- | -------- | --------------------------------- |
| `update:modelValue` | `string` | Fires when the active tab changes |

## Slots

| Slot                                    | Props                                          | Description                                   |
| --------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| `[item.value]`                          | -                                              | Content for that tab, one named slot per item |
| `label`                                 | `{ item, index }`                              | Replaces a tab's label content                |
| `scroll-left-icon`, `scroll-right-icon` | `{ class }`                                    | Replaces a default control's chevron          |
| `scroll-left`, `scroll-right`           | `{ buttonProps, scroll, disabled, ariaLabel }` | Replaces an entire overflow control           |


# Tree

## Usage

`items` is a nested array - a node with `children` renders as an
expandable row, one without renders as a leaf. Click a row to expand it
(and select it, if it's a leaf):


```vue
<script setup lang="ts">
const items = [
  {
    label: 'Documents',
    value: 'documents',
    children: [
      { label: 'Resume.pdf', value: 'resume' },
      { label: 'Cover Letter.docx', value: 'cover-letter' },
    ],
  },
  {
    label: 'Photos',
    value: 'photos',
    children: [
      { label: 'Vacation', value: 'vacation', children: [
        { label: 'Beach.jpg', value: 'beach' },
        { label: 'Sunset.jpg', value: 'sunset' },
      ] },
      { label: 'Family.jpg', value: 'family' },
    ],
  },
  { label: 'Notes.txt', value: 'notes' },
]
</script>

<template>
  <STree :items="items" class="w-full max-w-xs" />
</template>
```


```vue
<script setup lang="ts">
const items = [
  {
    label: 'Documents',
    value: 'documents',
    children: [
      { label: 'Resume.pdf', value: 'resume' },
      { label: 'Cover Letter.docx', value: 'cover-letter' },
    ],
  },
  { label: 'Notes.txt', value: 'notes' },
]
</script>

<template>
  <STree :items="items" />
</template>
```

### Multiple selection

`multiple` makes `v-model` an array instead of a single node.
`default-expanded` (an array of keys) opens branches immediately, no
click needed:


```vue
<script setup lang="ts">
const selected = ref()

const items = [
  {
    label: 'Frontend',
    value: 'frontend',
    children: [
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  },
  {
    label: 'Backend',
    value: 'backend',
    children: [
      { label: 'Node', value: 'node' },
      { label: 'Go', value: 'go' },
    ],
  },
]
</script>

<template>
  <div class="flex w-full max-w-xs flex-col gap-2">
    <STree v-model="selected" :items="items" multiple :default-expanded="['frontend', 'backend']" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ selected?.length ?? 0 }} selected
    </p>
  </div>
</template>
```


```vue-html
<STree v-model="selected" :items="items" multiple :default-expanded="['frontend', 'backend']" />
```

### Checkbox mode

`checkbox` shows a tri-state checkbox per row (reusing `SCheckbox`'s own
checked/unchecked/indeterminate model) and turns on `multiple` together
with parent↔child propagation: selecting a parent checks every one of
its descendants, and checking all of a node's children checks the
parent too (partially checking them marks it indeterminate instead):


```vue
<script setup lang="ts">
const selected = ref()

const items = [
  {
    label: 'Permissions',
    value: 'permissions',
    children: [
      { label: 'Read', value: 'read' },
      { label: 'Write', value: 'write' },
      { label: 'Admin', value: 'admin' },
    ],
  },
]
</script>

<template>
  <STree v-model="selected" :items="items" checkbox :default-expanded="['permissions']" class="w-full max-w-xs" />
</template>
```


```vue-html
<STree v-model="selected" :items="items" checkbox :default-expanded="['permissions']" />
```

### Custom item content

The `item` slot replaces a row's default icon+label content, scoped
with the node itself plus its live `expanded`/`selected`/`indeterminate`
state:


```vue
<script setup lang="ts">
const items = [
  {
    label: 'Reports',
    value: 'reports',
    children: [
      { label: 'Daily', value: 'daily', badge: '3' },
      { label: 'Weekly', value: 'weekly', badge: '12' },
    ],
  },
]
</script>

<template>
  <STree :items="items" :default-expanded="['reports']" class="w-full max-w-xs">
    <template #item="{ item }">
      <span class="flex flex-1 items-center justify-between">
        <span>{{ item.label }}</span>
        <SBadge v-if="item.badge" :label="item.badge as string" size="sm" variant="soft" />
      </span>
    </template>
  </STree>
</template>
```


```vue-html
<STree :items="items">
  <template #item="{ item }">
    <span class="flex flex-1 items-center justify-between">
      <span>{{ item.label }}</span>
      <SBadge v-if="item.badge" :label="item.badge" size="sm" variant="soft" />
    </span>
  </template>
</STree>
```

### Disabled items

A node's own `disabled: true` blocks just that row - siblings stay
interactive:


```vue
<script setup lang="ts">
const items = [
  {
    label: 'Team',
    value: 'team',
    children: [
      { label: 'Members', value: 'members' },
      { label: 'Billing', value: 'billing', disabled: true },
      { label: 'Danger zone', value: 'danger', disabled: true },
    ],
  },
]
</script>

<template>
  <STree :items="items" :default-expanded="['team']" class="w-full max-w-xs" />
</template>
```


```vue-html
<STree :items="items" />
```

```ts
const items = [
  { label: 'Members', value: 'members' },
  { label: 'Billing', value: 'billing', disabled: true },
]
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Tree`'s own theme file:

:theme-source{name="tree"}

## Props

| Prop              | Type                                                 | Default                            |
| ----------------- | ---------------------------------------------------- | ---------------------------------- |
| `items`           | `TreeItemType[]`                                     | - (required)                       |
| `modelValue`      | `TreeItemType | TreeItemType[]`                      | -                                  |
| `defaultValue`    | `TreeItemType | TreeItemType[]`                      | -                                  |
| `expanded`        | `string[]`                                           | -                                  |
| `defaultExpanded` | `string[]`                                           | -                                  |
| `multiple`        | `boolean`                                            | `false`                            |
| `checkbox`        | `boolean`                                            | `false`                            |
| `propagateSelect` | `boolean`                                            | `false`                            |
| `bubbleSelect`    | `boolean`                                            | `false`                            |
| `disabled`        | `boolean`                                            | `false`                            |
| `getKey`          | `(item: TreeItemType) => string`                     | `item => item.value ?? item.label` |
| `getChildren`     | `(item: TreeItemType) => TreeItemType[] | undefined` | `item => item.children`            |
| `size`            | `'sm' | 'md' | 'lg'`                                 | `md`                               |
| `ui`              | `Partial<Record<TreeSlot, string | object>>`         | -                                  |

## Events

| Event               | Payload                         | Description                               |
| ------------------- | ------------------------------- | ----------------------------------------- |
| `update:modelValue` | `TreeItemType | TreeItemType[]` | Fires on selection                        |
| `update:expanded`   | `string[]`                      | Fires when a row is expanded or collapsed |

## Slots

| Slot   | Props                                                | Description                                 |
| ------ | ---------------------------------------------------- | ------------------------------------------- |
| `item` | `{ item, level, expanded, selected, indeterminate }` | Replaces a row's default icon+label content |


# AlertDialog

## Usage

AlertDialog is Modal's stricter sibling for a "are you sure?" confirmation -
an outside click never closes it (Reka blocks that unconditionally), and it
already ships default Cancel/Continue buttons, so the common case needs no
`footer` slot at all:


```vue
<script setup lang="ts">
const open = ref(false)
const { add } = useToast()

function onConfirm() {
  add({ title: 'Account deleted', color: 'success' })
}
</script>

<template>
  <SButton color="danger" variant="soft" @click="open = true">
    Delete account
  </SButton>

  <SAlertDialog
    v-model:open="open"
    title="Delete account"
    description="This will permanently delete your account. This action cannot be undone."
    action-color="danger"
    action-label="Delete account"
    @confirm="onConfirm"
  />
</template>
```


```vue
<script setup lang="ts">
const open = ref(false)
const { add } = useToast()

function onConfirm() {
  add({ title: 'Account deleted', color: 'success' })
}
</script>

<template>
  <SButton color="danger" variant="soft" @click="open = true">
    Delete account
  </SButton>

  <SAlertDialog
    v-model:open="open"
    title="Delete account"
    description="This will permanently delete your account. This action cannot be undone."
    action-color="danger"
    action-label="Delete account"
    @confirm="onConfirm"
  />
</template>
```

Always pass `title` (or a `header` slot containing a heading) - without
one, the dialog has no accessible name for screen readers, and dev mode
warns about it.

The action button already closes the dialog on click (same as Cancel) -
`confirm`/`cancel` fire alongside that, not instead of it, so `@confirm`
only needs to run the actual side effect.

### Custom footer

A `footer` slot replaces the default Cancel/Continue pair entirely -
useful for more than two choices:


```vue
<script setup lang="ts">
const open = ref(false)
const { add } = useToast()

function discard() {
  open.value = false
  add({ title: 'Changes discarded', color: 'warning' })
}

function save() {
  open.value = false
  add({ title: 'Changes saved', color: 'success' })
}
</script>

<template>
  <SButton variant="soft" @click="open = true">
    Leave page
  </SButton>

  <SAlertDialog v-model:open="open" title="Unsaved changes" description="You have unsaved changes. What would you like to do?">
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton color="danger" variant="soft" @click="discard">
        Discard
      </SButton>
      <SButton color="primary" @click="save">
        Save changes
      </SButton>
    </template>
  </SAlertDialog>
</template>
```


```vue-html
<SAlertDialog v-model:open="open" title="Unsaved changes" description="You have unsaved changes. What would you like to do?">
  <template #footer>
    <SButton variant="ghost" @click="open = false">Cancel</SButton>
    <SButton color="danger" variant="soft" @click="discard">Discard</SButton>
    <SButton color="primary" @click="save">Save changes</SButton>
  </template>
</SAlertDialog>
```

A custom footer owns its own buttons and click handlers entirely - it
doesn't emit `confirm`/`cancel` (those are specific to the default footer),
and nothing auto-closes the dialog for you, same as Modal's own `footer`
slot.

### Why not just Modal?

`SModal` already supports `dismissible="false"` for a dialog that can't be
dismissed by Escape or an outside click - but that's opt-in per instance,
and still lets a consumer plug it back in wrong. `SAlertDialog` bakes the
outside-click block into Reka's own primitive instead, so it's not a
setting to get right or forget - the two components exist for genuinely
different intents:

```vue-html
<!-- Escape and outside click both work by default -->
<SModal v-model:open="open" title="Edit profile" />

<!-- Outside click can never close it - Escape still can (dismissible="false" blocks that too) -->
<SAlertDialog v-model:open="open" title="Delete account" description="..." />
```

Escape still closes an `SAlertDialog` by default, the same as `SModal` -
`dismissible="false"` blocks that too, for a dialog that must be answered
via one of the footer buttons:

```vue-html
<SAlertDialog v-model:open="open" :dismissible="false" title="Confirm your plan" description="..." />
```

The `escapeKeyDown`/`pointerDownOutside` events still fire either way -
useful for something like a shake animation to signal the dialog won't
close that way.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the dialog's own theme file:

:theme-source{name="alert-dialog"}

## Props

| Prop          | Type                                                                                                               | Default      |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ |
| `open`        | `boolean`                                                                                                          | -            |
| `defaultOpen` | `boolean`                                                                                                          | `false`      |
| `title`       | `string`                                                                                                           | -            |
| `description` | `string`                                                                                                           | -            |
| `icon`        | `string`                                                                                                           | -            |
| `cancelLabel` | `string`                                                                                                           | `'Cancel'`   |
| `actionLabel` | `string`                                                                                                           | `'Continue'` |
| `actionColor` | `'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'neutral'`                                  | -            |
| `dismissible` | `boolean`                                                                                                          | `true`       |
| `overlay`     | `boolean`                                                                                                          | `true`       |
| `transition`  | `boolean`                                                                                                          | `true`       |
| `ui`          | `Partial<Record<'overlay' | 'content' | 'header' | 'title' | 'description' | 'body' | 'footer', string | object>>` | -            |

A `class` passed to `<SAlertDialog>` is merged into the alert dialog panel. Use `ui.content` for the same panel, or put a class directly on the default-slot trigger to style that trigger.

## Events

| Event                | Payload         | Description                                                                                                       |
| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `update:open`        | `boolean`       | Open state changed                                                                                                |
| `cancel`             | -               | The default Cancel button was clicked                                                                             |
| `confirm`            | -               | The default action button was clicked                                                                             |
| `escapeKeyDown`      | `KeyboardEvent` | Escape was pressed - `preventDefault()` to stop it from closing                                                   |
| `pointerDownOutside` | `Event`         | A pointer went down outside the dialog - can never actually close it, but still useful for e.g. a shake animation |
| `afterLeave`         | -               | The close transition has finished (or fires immediately if `transition` is `false`)                               |

## Slots

| Slot     | Description                                          |
| -------- | ---------------------------------------------------- |
| default  | The trigger element                                  |
| `header` | Overrides the default title/description block        |
| `body`   | Optional extra content between the header and footer |
| `footer` | Overrides the default Cancel/Continue buttons        |


# Command Palette

## Usage

Place `SCommandPalette` once (your root layout is a good spot) and
control it from anywhere with `useCommandPalette()` - the same
composable-driven pattern as `useModal()`/`useSlideover()`. Press
:kbd[⌘]:kbd[K] (or :kbd[Ctrl]:kbd[K] ) to open it too -
that shortcut is bound automatically, nothing to wire up yourself:


```vue
<script setup lang="ts">
const open = ref(false)
const result = ref<string>()

const groups = [
  {
    label: 'Actions',
    items: [
      { label: 'New file', icon: 'hugeicons:file-add', shortcut: 'mod+n', hotkey: true, onSelect: () => result.value = 'New file' },
      { label: 'New folder', icon: 'hugeicons:folder-add', onSelect: () => result.value = 'New folder' },
    ],
  },
  {
    label: 'Navigation',
    items: [
      { label: 'Go to settings', icon: 'hugeicons:settings-01', shortcut: 'mod+,', hotkey: true, onSelect: () => result.value = 'Go to settings' },
      { label: 'Go to profile', icon: 'hugeicons:user', onSelect: () => result.value = 'Go to profile' },
    ],
  },
]
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SButton variant="outline" @click="open = true">
      Open command palette
    </SButton>
    <p v-if="result" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Ran: {{ result }}
    </p>
  </div>

  <!--
    This docs page already has the site's own real command palette mounted
    globally (its Cmd/Ctrl+K), so this self-contained demo runs as its own
    locally-controlled instance instead of the shared useCommandPalette()
    singleton - shortcut disabled to avoid a second dialog stacking on top
    of the real one when the same key is pressed.
  -->
  <SCommandPalette v-model:open="open" :groups="groups" :shortcut="false" />
</template>
```


```vue
<script setup lang="ts">
const palette = useCommandPalette()

const groups = [
  {
    label: 'Actions',
    items: [
      { label: 'New file', icon: 'hugeicons:file-add', shortcut: 'mod+n', hotkey: true, onSelect: () => {} },
      { label: 'New folder', icon: 'hugeicons:folder-add', onSelect: () => {} },
    ],
  },
  {
    label: 'Navigation',
    items: [
      { label: 'Go to settings', icon: 'hugeicons:settings-01', shortcut: 'mod+,', hotkey: true, onSelect: () => {} },
      { label: 'Go to profile', icon: 'hugeicons:user', onSelect: () => {} },
    ],
  },
]
</script>

<template>
  <SButton @click="palette.open()">
    Open command palette
  </SButton>
  <SCommandPalette :groups="groups" />
</template>
```

`items` are an array of groups, same shape as
[Dropdown](https://selarasui.my.id/components/overlays/dropdown)/[ContextMenu](https://selarasui.my.id/components/overlays/context-menu) -
a separator (here, a small group label) between each group. Typing
filters every item with a lightweight fuzzy match (not a plain
substring check) - "nf" matches "New File" - and results re-rank live
as the query changes; an empty search keeps each group's own
authoring order rather than reshuffling the default view.

### Item shortcuts

An item's own `shortcut` renders via [Kbd](https://selarasui.my.id/components/elements/kbd) as a
display hint. Add `hotkey: true` to bind it while the palette is open; the
item's normal selection behavior runs and the palette closes. Use `mod` to
show ⌘ on macOS and Ctrl on other platforms. The live example above includes
enabled shortcuts for creating a file and opening settings, plus items that
show no hint and therefore have no item-specific shortcut:

```vue-html
{ label: 'New file', shortcut: 'mod+n', hotkey: true, onSelect: () => {} }
```

### Disabling the built-in shortcut

Set `:shortcut="false"` if you'd rather wire your own trigger (a menu
item, a different key combo) instead of the automatic
:kbd[⌘]:kbd[K] / :kbd[Ctrl]:kbd[K] binding -
`useCommandPalette().open()` still works from anywhere either way.

```vue-html
<SCommandPalette :groups="groups" :shortcut="false" />
```

### Keyboard interaction

:kbd[↑]/ :kbd[↓] move the highlighted result (wrapping past
either end, skipping disabled items), :kbd[Enter] runs the
highlighted item's `onSelect` and closes the palette, :kbd[Esc]
or an outside click closes it without running anything.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the palette's own theme file:

:theme-source{name="command-palette"}

## Props

| Prop       | Type                                                                                                                                              | Default |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `groups`   | `{ label?: string; items: { label: string; icon?: string; shortcut?: string; hotkey?: boolean; disabled?: boolean; onSelect?: () => void }[] }[]` | -       |
| `open`     | `boolean`                                                                                                                                         | -       |
| `shortcut` | `boolean`                                                                                                                                         | `true`  |
| `ui`       | `Partial<Record<CommandPaletteSlot, string | object>>`                                                                                            | -       |

### Multiple instances

Pass `v-model:open` if you need a second, independently-controlled palette
(a different `groups` list, scoped to some part of the app) instead of the
one shared instance:

```vue-html
<SCommandPalette v-model:open="open" :groups="scopedGroups" />
```

This instance stops reacting to `useCommandPalette()` entirely - its own
`open`/`close`/Cmd-K state is fully local. The default (no `open` prop)
stays wired to the shared singleton described above, which is what you
want for the single app-wide palette.

## `useCommandPalette()`

| Member   | Type           | Description           |
| -------- | -------------- | --------------------- |
| `isOpen` | `Ref<boolean>` | The shared open state |
| `open`   | `() => void`   | Opens it              |
| `close`  | `() => void`   | Closes it             |
| `toggle` | `() => void`   | Flips it              |


# Context Menu

## Usage

Right-click the target area - anywhere inside the default slot opens
the menu at the cursor position, instead of at a fixed trigger element
the way `Dropdown` does:


```vue
<template>
  <SContextMenu
    :items="[
      [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
      [{ label: 'Delete', icon: 'hugeicons:delete-02' }],
    ]"
  >
    <div class="flex h-32 w-64 select-none items-center justify-center rounded-[var(--selaras-resolved-radius-md)] border border-dashed border-[var(--selaras-resolved-border-default)] text-sm text-[var(--selaras-resolved-text-muted)]">
      Right-click here
    </div>
  </SContextMenu>
</template>
```


```vue
<template>
  <SContextMenu
    :items="[
      [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
      [{ label: 'Delete', icon: 'hugeicons:delete-02' }],
    ]"
  >
    <div>Right-click here</div>
  </SContextMenu>
</template>
```

Items are an array of groups — a separator is rendered between each group,
same shape as [Dropdown](https://selarasui.my.id/components/overlays/dropdown).
`shortcut` renders a Kbd hint; set `hotkey: true` to activate it while the
context menu is open.

### Shortcuts

`shortcut` is a display hint by itself. Add `hotkey: true` to run the item's
normal `onSelect` action while the context menu is open. Use `mod` for ⌘ on
macOS or Ctrl on other platforms. Right-click the example area first, then
try the enabled shortcut; the item with only `shortcut` does not bind a key.


```vue
<script setup lang="ts">
const lastAction = ref('')

const items = [
  [
    { label: 'Rename', icon: 'hugeicons:pencil', shortcut: 'mod+e', hotkey: true, onSelect: () => lastAction.value = 'Rename selected' },
    { label: 'Share', icon: 'hugeicons:share-08', shortcut: 'mod+shift+s', onSelect: () => lastAction.value = 'Share selected' },
  ],
]
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SContextMenu :items="items">
      <div class="flex h-32 w-72 select-none items-center justify-center rounded-[var(--selaras-resolved-radius-md)] border border-dashed border-[var(--selaras-resolved-border-default)] text-sm text-[var(--selaras-resolved-text-muted)]">
        Right-click here, then press ⌘/Ctrl+E
      </div>
    </SContextMenu>
    <p v-if="lastAction" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ lastAction }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const lastAction = ref('')
const items = [[
  { label: 'Rename', shortcut: 'mod+e', hotkey: true, onSelect: () => lastAction.value = 'Rename selected' },
  { label: 'Share', shortcut: 'mod+shift+s', onSelect: () => lastAction.value = 'Share selected' },
]]
</script>

<template>
  <SContextMenu :items="items">
    <div>Right-click here</div>
  </SContextMenu>
</template>
```

### Custom item content

The `item` slot replaces an item's plain-text label with anything,
scoped with `item`, so a single template can vary per item. The component
continues to render `shortcut` after the slot content automatically:


```vue
<script setup lang="ts">
const items = [
  [
    { label: 'Edit', icon: 'hugeicons:pencil', shortcut: 'mod+e', hotkey: true },
    { label: 'Duplicate', icon: 'hugeicons:copy', shortcut: 'mod+d', hotkey: true },
  ],
]
</script>

<template>
  <SContextMenu :items="items">
    <template #item="{ item }">
      <span class="flex-1">{{ item.label }}</span>
    </template>
    <div class="flex h-32 w-64 select-none items-center justify-center rounded-[var(--selaras-resolved-radius-md)] border border-dashed border-[var(--selaras-resolved-border-default)] text-sm text-[var(--selaras-resolved-text-muted)]">
      Right-click here
    </div>
  </SContextMenu>
</template>
```


```vue-html
<SContextMenu :items="items">
  <template #item="{ item }">
    <span class="flex-1">{{ item.label }}</span>
  </template>
  ...
</SContextMenu>
```

### Destructive items

`destructive: true` styles an item for a delete/remove-style action,
the same single flag `Dropdown`'s own items use:


```vue
<script setup lang="ts">
const items = [
  [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
  [{ label: 'Delete', icon: 'hugeicons:delete-02', destructive: true }],
]
</script>

<template>
  <SContextMenu :items="items">
    <div class="flex h-32 w-64 select-none items-center justify-center rounded-[var(--selaras-resolved-radius-md)] border border-dashed border-[var(--selaras-resolved-border-default)] text-sm text-[var(--selaras-resolved-text-muted)]">
      Right-click here
    </div>
  </SContextMenu>
</template>
```


```vue-html
<SContextMenu
  :items="[
    [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
    [{ label: 'Delete', icon: 'hugeicons:delete-02', destructive: true }],
  ]"
>
  ...
</SContextMenu>
```

### Accessibility

Same underlying menu machinery as [Dropdown](https://selarasui.my.id/components/overlays/dropdown#accessibility):
the menu itself is `role="menu"` with each item as `role="menuitem"`,
:kbd[↑] / :kbd[↓] move between items (wrapping past either
end), typing a letter jumps to the next matching item, and
:kbd[Enter] / :kbd[Space] selects the highlighted one -
:kbd[Escape] or an outside click closes the menu. A touch/pen
long-press opens it too, not just a mouse right-click.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `ContextMenu`'s own theme file:

:theme-source{name="context-menu"}

### Positioning and portal

ContextMenu anchors to the right-click point, so it does not accept `side` or
`align`. Its `positioning` prop controls supported offsets and collision
behavior. `portal` defaults to the document body; set it to `false` to render
inline or pass a CSS selector or `HTMLElement` as the teleport target.

```vue-html
<SContextMenu :items="items" :positioning="{ collisionPadding: 12 }" portal="#overlay-root">...</SContextMenu>
```

## Props

Set `hotkey: true` alongside `shortcut` to register the displayed key while
the context menu is open. Otherwise the shortcut is a visual hint only.

| Prop          | Type                                                                                                                                          | Default                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `items`       | `{ label: string; icon?: string; disabled?: boolean; destructive?: boolean; onSelect?: () => void; shortcut?: string; hotkey?: boolean }[][]` | -                         |
| `positioning` | `ContextMenuPositioning`                                                                                                                      | pointer-anchored defaults |
| `portal`      | `boolean | string | HTMLElement`                                                                                                              | `true` (document body)    |
| `ui`          | `Partial<Record<'content' | 'item' | 'icon' | 'separator', string | object>>`                                                                 | -                         |

A `class` passed to `<SContextMenu>` is merged into its default-slot context target. Use `ui.content` to style the floating menu.

## Slots

| Slot      | Props      | Description                      |
| --------- | ---------- | -------------------------------- |
| `default` | -          | The right-click target area      |
| `item`    | `{ item }` | Replaces an item's label content |


# Drawer

## Usage

Drawer visibility is controlled with `v-model:open`, so it needs a ref
from the page it's used on. Unlike [Slideover](https://selarasui.my.id/components/overlays/slideover),
which is built on Reka's Dialog primitive, Drawer is built on Reka's own
Drawer primitive - real drag-to-dismiss and (below) resting snap points,
not just a slide animation:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open drawer
  </SButton>

  <SDrawer v-model:open="open" title="Edit profile" description="Update your personal details.">
    <template #body>
      Drawer content goes here.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton @click="open = false">
        Save
      </SButton>
    </template>
  </SDrawer>
</template>
```


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open drawer
  </SButton>

  <SDrawer v-model:open="open" title="Edit profile" description="Update your personal details.">
    <template #body>
      Drawer content goes here.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton @click="open = false">
        Save
      </SButton>
    </template>
  </SDrawer>
</template>
```

Always pass `title` (or a `header`/`content` slot containing a heading) -
without one, the panel has no accessible name for screen readers, and dev
mode warns about it.

### Side

`side` picks which edge the panel slides in from (and the direction it's
swiped toward to dismiss it) - `top`, `right`, `bottom` (default), or
`left`. Unlike Slideover's `'right'` default, a drawer defaults to `bottom`

- the classic mobile bottom sheet:


```vue
<script setup lang="ts">
const sides = ['top', 'right', 'bottom', 'left'] as const
const side = ref<typeof sides[number]>('bottom')
const open = ref(false)

function openWith(value: typeof sides[number]) {
  side.value = value
  open.value = true
}
</script>

<template>
  <SButtonGroup>
    <SButton v-for="s in sides" :key="s" variant="soft" @click="openWith(s)">
      {{ s }}
    </SButton>
  </SButtonGroup>

  <SDrawer v-model:open="open" :side="side" title="Filters">
    <template #body>
      Slides in from the {{ side }} edge.
    </template>
  </SDrawer>
</template>
```


```vue-html
<SDrawer v-model:open="open" side="left" title="Filters" />
```

### Snap points

`snapPoints` gives the panel resting heights (or widths, for a `left`/
`right` drawer) to drag between before it's fully open - fractions
(`0`-`1`), pixels (`> 1`), or CSS length strings (`'30rem'`). Pair with
`v-model:snap-point` to read or control which one is currently active.
`snapToSequentialPoints` (default `false`) restricts dragging to one step
at a time instead of jumping to whichever point is nearest:


```vue
<script setup lang="ts">
const open = ref(false)
const snapPoint = ref<number | string | null>(0.3)
</script>

<template>
  <SButton @click="open = true">
    Open drawer
  </SButton>

  <SDrawer
    v-model:open="open"
    v-model:snap-point="snapPoint"
    :snap-points="[0.3, 0.6, 1]"
    title="Drag me"
    description="Rests at 30%, 60%, or fully open - drag the handle to snap between them."
  >
    <template #body>
      <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
        Current snap point: {{ snapPoint }}
      </p>
    </template>
  </SDrawer>
</template>
```


```vue-html
<SDrawer
  v-model:open="open"
  v-model:snap-point="snapPoint"
  :snap-points="[0.3, 0.6, 1]"
  title="Drag me"
/>
```

### Handle

A small grip bar shows at the top of the panel by default, signaling it's
draggable - set `handle="false"` to remove it:

```vue-html
<SDrawer v-model:open="open" :handle="false" title="No handle" />
```

### Custom content

`content` replaces the header/title/description/body/footer structure
entirely - useful when the panel doesn't fit the header-plus-body shape at
all. `close`/`handle` are ignored once `content` is provided, since the
slot owns the whole visible panel - but `title`/`description`, if still
set, stay registered with Reka as the panel's accessible name/description,
just visually hidden instead of rendered as a header. Pass them if your
own custom content doesn't already include a heading Reka can associate
with the panel:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open custom drawer
  </SButton>

  <SDrawer v-model:open="open">
    <template #content>
      <div class="flex flex-col items-center gap-4 p-8 text-center">
        <div class="flex size-12 items-center justify-center rounded-full bg-[var(--selaras-resolved-color-success-subtle)] text-[var(--selaras-resolved-color-success-text)]">
          <SIcon name="hugeicons:checkmark-circle-01" class="size-6" />
        </div>
        <h2 class="text-base font-semibold text-[var(--selaras-resolved-text-default)]">
          Order placed
        </h2>
        <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
          We'll email you once it ships.
        </p>
        <SButton class="mt-2" block @click="open = false">
          Done
        </SButton>
      </div>
    </template>
  </SDrawer>
</template>
```


```vue-html
<SDrawer v-model:open="open">
  <template #content>
    <div class="flex flex-col items-center gap-4 p-8 text-center">
      ...
    </div>
  </template>
</SDrawer>
```

### Non-modal

`modal="false"` stops the panel from blocking interaction with the rest of
the page - no focus trap, outside elements stay reachable and aren't hidden
from assistive tech. `overlay` is independent of this - a non-modal panel
can still show (or hide) its own backdrop:

```vue-html
<SDrawer v-model:open="open" :modal="false" title="Non-modal" />
```

### Intercepting dismissal

`SDrawer` doesn't override Reka UI's own defaults (Escape, an outside
click, and a drag-to-dismiss swipe all dismiss it), but exposes the
underlying events so you can `preventDefault()` on them - e.g. to confirm
before closing a panel with unsaved changes. A swipe has no separate event
of its own to intercept ahead of time (Reka only reports it after the
fact), so it can only be blocked wholesale via `dismissible`, not
conditionally per attempt like Escape/outside-click:

```vue-html
<SDrawer
  v-model:open="open"
  title="Edit profile"
  @escape-key-down="(e) => hasChanges && e.preventDefault()"
  @pointer-down-outside="(e) => hasChanges && e.preventDefault()"
/>
```

For the simpler, all-or-nothing case - a panel that must not be dismissed
by anything but an explicit choice - `dismissible="false"` disables
Escape, outside-click, and swipe-to-dismiss all at once, and
`close="false"` removes the close button too:

```vue-html
<SDrawer v-model:open="open" :dismissible="false" :close="false" title="Confirm your plan" />
```

## Programmatic usage

`useDrawer()` opens a panel from anywhere - a click handler, an async
callback - without a `v-model` of your own to manage. It works
automatically once `<SApp>` wraps your app, exactly like `useModal()`/
`useSlideover()`; there's nothing extra to place.

The given component owns the panel's entire content, the same as the
`content` slot. `open()` returns a promise that resolves with whatever
value the component's own `close` event carries, so an explicit action can
resolve with real data while dismissing via Escape, an outside click, or a
swipe resolves with `undefined`:


```vue
<script setup lang="ts">
import DrawerCartPanel from './DrawerCartPanel.vue'

const drawer = useDrawer()
const result = ref<string>()

async function openCart() {
  const checkedOut = await drawer.open(DrawerCartPanel)
  result.value = checkedOut === undefined ? 'Dismissed' : checkedOut ? 'Checked out' : 'Cancelled'
}
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SButton @click="openCart">
      Open cart
    </SButton>
    <p v-if="result" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Result: {{ result }}
    </p>
  </div>
</template>
```


```ts
import DrawerCartPanel from './DrawerCartPanel.vue'

const drawer = useDrawer()
const checkedOut = await drawer.open(DrawerCartPanel)
// true, false, or undefined if dismissed without an explicit choice
```

`open()` also takes the same `title`/`description`/`side`/`handle`/
`snapPoints`/`snapPoint`/`snapToSequentialPoints`/`dismissible`/`modal`/
`overlay`/`transition` options as the declarative props.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the panel's own theme file:

:theme-source{name="drawer"}

## Props

| Prop                     | Type                                           | Default    |
| ------------------------ | ---------------------------------------------- | ---------- |
| `open`                   | `boolean`                                      | `false`    |
| `title`                  | `string`                                       | -          |
| `description`            | `string`                                       | -          |
| `side`                   | `'top' | 'right' | 'bottom' | 'left'`          | `'bottom'` |
| `handle`                 | `boolean`                                      | `true`     |
| `snapPoints`             | `(number | string)[]`                          | -          |
| `snapPoint`              | `number | string | null`                       | -          |
| `snapToSequentialPoints` | `boolean`                                      | `false`    |
| `dismissible`            | `boolean`                                      | `true`     |
| `close`                  | `boolean`                                      | `true`     |
| `modal`                  | `boolean | 'trap-focus'`                       | `true`     |
| `overlay`                | `boolean`                                      | `true`     |
| `transition`             | `boolean`                                      | `true`     |
| `ui`                     | `Partial<Record<DrawerSlot, string | object>>` | -          |

A `class` passed to `<SDrawer>` is merged into the drawer panel. Use `ui.content` for the same panel, or put a class directly on the default-slot trigger to style that trigger.

## Events

| Event                | Payload                  | Description                                                                                     |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `update:open`        | `boolean`                | Open state changed                                                                              |
| `update:snapPoint`   | `number | string | null` | Active snap point changed                                                                       |
| `escapeKeyDown`      | `KeyboardEvent`          | Escape was pressed - `preventDefault()` to stop it from closing                                 |
| `pointerDownOutside` | `Event`                  | A pointer went down outside the panel - `preventDefault()` to stop it from closing              |
| `focusOutside`       | `Event`                  | A non-modal panel's outside element received focus - `preventDefault()` to stop it from closing |
| `afterLeave`         | -                        | The close transition has finished (or fires immediately if `transition` is `false`)             |

## Slots

| Slot         | Description                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| default      | The trigger element                                                                                   |
| `content`    | Replaces the visible header/body/footer entirely (title/description, if set, still register for a11y) |
| `header`     | Overrides the default title/description block                                                         |
| `body`       | Main content                                                                                          |
| `footer`     | Usually action buttons                                                                                |
| `close-icon` | Replaces the close button's icon (default: `hugeicons:cancel-01`)                                     |


# Dropdown

## Usage


```vue
<template>
  <SDropdown
    :items="[
      [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
      [{ label: 'Delete', icon: 'hugeicons:delete-02' }],
    ]"
  >
    <SButton variant="outline">
      Open dropdown
    </SButton>
  </SDropdown>
</template>
```


```vue
<template>
  <SDropdown
    :items="[
      [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
      [{ label: 'Delete', icon: 'hugeicons:delete-02' }],
    ]"
  >
    <SButton variant="outline">
      Open dropdown
    </SButton>
  </SDropdown>
</template>
```

Items are an array of groups — a separator is rendered between each group.
Items can run `onSelect` actions or navigate through `to` (including
external URLs, with `target`/`rel` when needed). `shortcut` renders a Kbd
hint; set `hotkey: true` to bind it while the dropdown is open.

### Groups and separators

`items` is a `DropdownItem[][]`: each inner array is one group. Selaras adds a
separator between groups; items in the same group have no separator between them.
There is no separate `type: 'separator'` item in this API. Split the items into
another inner array wherever a boundary belongs.


```vue
<script setup lang="ts">
const lastAction = ref('No action selected')
const profile = { label: 'Profile', onSelect: () => lastAction.value = 'Profile selected' }
const signOut = { label: 'Sign out', onSelect: () => lastAction.value = 'Sign out selected' }
</script>

<template>
  <div class="flex flex-col gap-3">
    <div class="flex flex-wrap gap-4">
      <SDropdown :items="[[profile], [signOut]]">
        <SButton variant="outline">
          Two groups
        </SButton>
      </SDropdown>
      <SDropdown :items="[[profile, signOut]]">
        <SButton variant="outline">
          One group
        </SButton>
      </SDropdown>
    </div>
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]" aria-live="polite">
      {{ lastAction }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const lastAction = ref('')
const profile = { label: 'Profile', onSelect: () => lastAction.value = 'Profile selected' }
const signOut = { label: 'Sign out', onSelect: () => lastAction.value = 'Sign out selected' }
</script>

<template>
  <!-- Two groups: a separator appears between Profile and Sign out. -->
  <SDropdown :items="[[profile], [signOut]]">
    <SButton variant="outline">
      Two groups
    </SButton>
  </SDropdown>

  <!-- One group: no separator appears between the two items. -->
  <SDropdown :items="[[profile, signOut]]">
    <SButton variant="outline">
      One group
    </SButton>
  </SDropdown>
</template>
```

Use `ui.separator` to change the separator's styling. This applies to the
anchored menu and the adaptive mobile modal:

```vue-html
<SDropdown :items="[[profile], [signOut]]" :ui="{ separator: 'my-2' }">
  <SButton>Account</SButton>
</SDropdown>
```

### Shortcuts and links

`shortcut` only displays the hint. Add `hotkey: true` to activate the item
with that key while this dropdown is open. Use `mod` for the platform's
primary modifier (⌘ on macOS, Ctrl elsewhere). Items with `to` navigate as
links by mouse, keyboard selection, or shortcut; action items call
`onSelect` through the same selection path.


```vue
<script setup lang="ts">
const lastAction = ref('')

const items = [
  [
    { label: 'Save draft', icon: 'hugeicons:floppy-disk', shortcut: 'mod+s', hotkey: true, onSelect: () => lastAction.value = 'Saved draft' },
    { label: 'Preview', icon: 'hugeicons:view', shortcut: 'mod+p', onSelect: () => lastAction.value = 'Preview opened' },
  ],
  [
    { label: 'Context menu docs', icon: 'hugeicons:book-open-01', to: '/components/overlays/context-menu', shortcut: 'mod+shift+d', hotkey: true },
  ],
]
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SDropdown :items="items">
      <SButton variant="outline">
        Open actions
      </SButton>
    </SDropdown>
    <p v-if="lastAction" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      {{ lastAction }}
    </p>
  </div>
</template>
```


```vue
<script setup lang="ts">
const lastAction = ref('')
const items = [[
  { label: 'Save draft', icon: 'hugeicons:floppy-disk', shortcut: 'mod+s', hotkey: true, onSelect: () => lastAction.value = 'Saved draft' },
  { label: 'Preview', shortcut: 'mod+p', onSelect: () => lastAction.value = 'Preview opened' },
  { label: 'Documentation', to: '/components/overlays/context-menu', shortcut: 'mod+shift+d', hotkey: true },
]]
</script>

<template>
  <SDropdown :items="items">
    <SButton variant="outline">
      Open actions
    </SButton>
  </SDropdown>
</template>
```

In this example, `Save draft` and `Documentation` respond to their shortcuts;
`Preview` shows a hint only. Open the dropdown before pressing a menu shortcut.

### Custom item content

The `item` slot replaces an item's plain-text label with anything,
scoped with `item`, so a single template can vary per item. The component
continues to render `shortcut` after the slot content automatically:


```vue
<script setup lang="ts">
const items = [
  [
    { label: 'Edit', icon: 'hugeicons:pencil', shortcut: 'mod+e', hotkey: true },
    { label: 'Duplicate', icon: 'hugeicons:copy', shortcut: 'mod+d', hotkey: true },
  ],
]
</script>

<template>
  <SDropdown :items="items">
    <template #item="{ item }">
      <span class="flex-1">{{ item.label }}</span>
    </template>
    <SButton variant="outline">
      Open dropdown
    </SButton>
  </SDropdown>
</template>
```


```vue-html
<SDropdown :items="items">
  <template #item="{ item }">
    <span class="flex-1">{{ item.label }}</span>
  </template>
  ...
</SDropdown>
```

### Destructive items

`destructive: true` styles an item for a delete/remove-style action
(danger text, danger-tinted hover) - just this one flag rather than a
full color choice, since a menu item realistically only ever needs this
one special case:


```vue
<script setup lang="ts">
const items = [
  [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
  [{ label: 'Delete', icon: 'hugeicons:delete-02', destructive: true }],
]
</script>

<template>
  <SDropdown :items="items">
    <SButton variant="outline">
      Open dropdown
    </SButton>
  </SDropdown>
</template>
```


```vue-html
<SDropdown
  :items="[
    [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
    [{ label: 'Delete', icon: 'hugeicons:delete-02', destructive: true }],
  ]"
>
  ...
</SDropdown>
```

### Arrow

`arrow` shows a small pointer triangle connecting the menu to its trigger.
Pass an object to configure its width, height, rounded tip, or corner
clearance (`padding`):


```vue
<script setup lang="ts">
const items = [
  [{ label: 'Edit', icon: 'hugeicons:pencil' }, { label: 'Duplicate', icon: 'hugeicons:copy' }],
  [{ label: 'Delete', icon: 'hugeicons:delete-02' }],
]
</script>

<template>
  <SDropdown :items="items" arrow>
    <SButton variant="outline">
      Open dropdown
    </SButton>
  </SDropdown>
</template>
```


```vue-html
<SDropdown :items="items" arrow>...</SDropdown>
<SDropdown :items="items" :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }">...</SDropdown>
```

### Adaptive mobile presentation

Set `adaptive` to show the action list in a modal on small screens while
keeping the anchored menu on larger screens. This is opt-in; links, action
handlers, groups, item slots, and shortcut hints work in either presentation.
The modal uses normal buttons and links, so touch users get larger targets and
keyboard users can move through actions with Tab. Escape and the backdrop close
it and return focus to the trigger.


```vue
<template>
  <SDropdown
    adaptive
    :items="[
      [{ label: 'Edit profile', icon: 'hugeicons:pencil' }, { label: 'Copy profile link', icon: 'hugeicons:copy' }],
      [{ label: 'Sign out', icon: 'hugeicons:logout-03', destructive: true }],
    ]"
  >
    <SButton variant="outline">
      More actions
    </SButton>
  </SDropdown>
</template>
```


### Accessibility

Dropdown renders Reka UI's DropdownMenu primitive, so the accessibility
semantics come from there rather than being reimplemented here: the
trigger exposes `aria-haspopup`/`aria-expanded`, the menu itself is
`role="menu"` with each item as `role="menuitem"`,
:kbd[↑] / :kbd[↓] move between items (wrapping past either end),
typing a letter jumps to the next matching item, and
:kbd[Enter] / :kbd[Space] selects the highlighted one -
:kbd[Escape] or an outside click closes the menu and returns focus
to the trigger. With `adaptive` on a small screen, the action list becomes a
dialog containing native links and buttons; focus follows the dialog's normal
Tab order instead of menu arrow-key navigation.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the menu's own theme file:

:theme-source{name="dropdown"}

### Positioning and portal

Use `positioning` for the menu's side, alignment, offsets, and collision
behavior. `portal` defaults to the document body; set it to `false` to render
inline or pass a CSS selector or `HTMLElement` as the teleport target.
`ui.content` remains the styling override.

```vue-html
<SDropdown :items="items" :positioning="{ side: 'top', align: 'end' }" portal="#overlay-root">...</SDropdown>
```

## Props

For the `items` array shape, see [Groups and separators](https://selarasui.my.id/#groups-and-separators).
For link items, use `to` with optional `target` and `rel`. Shortcut hints
are display-only unless `hotkey: true` is set.

| Prop                                                      | Type                                                                                                                                                                                      | Default                |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| [`items`](https://selarasui.my.id/#groups-and-separators) | `{ label: string; icon?: string; disabled?: boolean; destructive?: boolean; onSelect?: () => void; to?: string; target?: string; rel?: string; shortcut?: string; hotkey?: boolean }[][]` | -                      |
| `arrow`                                                   | `boolean | RoundedArrowConfig`                                                                                                                                                            | `false`                |
| `positioning`                                             | `OverlayPositioning`                                                                                                                                                                      | menu defaults          |
| `portal`                                                  | `boolean | string | HTMLElement`                                                                                                                                                          | `true` (document body) |
| `adaptive`                                                | `boolean`                                                                                                                                                                                 | `false`                |
| `ui`                                                      | `Partial<Record<'content' | 'item' | 'icon' | 'separator' | 'arrow' | 'mobileList' | 'mobileGroup', string | object>>`                                                                    | -                      |

A `class` passed to `<SDropdown>` is merged into its default-slot trigger element. Use `ui.content` to style the floating menu.

## Slots

| Slot      | Props      | Description                      |
| --------- | ---------- | -------------------------------- |
| `default` | -          | The trigger element              |
| `item`    | `{ item }` | Replaces an item's label content |


# Modal

## Usage

Modal visibility is controlled with `v-model:open`, so it needs a ref from
the page it's used on.


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open modal
  </SButton>

  <SModal v-model:open="open" title="Delete item" description="This action cannot be undone.">
    <template #body>
      Are you sure you want to delete this item?
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton color="danger" @click="open = false">
        Delete
      </SButton>
    </template>
  </SModal>
</template>
```


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open modal
  </SButton>

  <SModal v-model:open="open" title="Delete item" description="This action cannot be undone.">
    <template #body>
      Are you sure you want to delete this item?
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton color="danger" @click="open = false">
        Delete
      </SButton>
    </template>
  </SModal>
</template>
```

Always pass `title` (or a `header`/`content` slot containing a heading) -
without one, the dialog has no accessible name for screen readers, and dev
mode warns about it.

### Controlling it programmatically

`open` is a real controlled value, not tied to a click - setting it
from anywhere (a timeout, an async callback, a route watcher, another
component) opens the dialog identically. No trigger element, or even a
default slot, is required:


```vue
<script setup lang="ts">
const open = ref(false)
const counting = ref(false)

// Not tied to a click that opens it directly - a "Simulate" button just
// starts a timeout, the same shape a real async callback/route watcher
// would have. Deliberately not auto-run on mount: a modal is `modal` by
// default, meaning it blocks the rest of the page (including every other
// live example below it) - auto-popping one open the moment a docs reader
// scrolls near this section would be genuinely disruptive, not just a
// neat demo.
function simulate() {
  counting.value = true
  setTimeout(() => {
    counting.value = false
    open.value = true
  }, 1000)
}
</script>

<template>
  <SButton :disabled="counting" @click="simulate">
    {{ counting ? 'Waiting a second...' : 'Simulate an async event' }}
  </SButton>

  <SModal v-model:open="open" title="Opened by the timeout" description="Nothing was clicked to show this - the button above only started a timer.">
    <template #body>
      <code class="font-mono text-xs">v-model</code> is a real controlled
      value - setting it from anywhere (a timeout, an async callback, a
      route watcher, another component) opens the dialog identically to a
      click. No trigger element, or even a <code class="font-mono text-xs">default</code>
      slot, is required.
    </template>
    <template #footer>
      <SButton @click="open = false">
        Got it
      </SButton>
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open" title="Opened by the timeout" />
```

```ts
function simulate() {
  setTimeout(() => {
    open.value = true
  }, 1000)
}
```

### Custom content

`content` replaces the header/title/description/body/footer structure
entirely - useful when the dialog doesn't fit the header-plus-body shape at
all (a success screen, a fully custom form layout). `close`/`maximizable`
are ignored once `content` is provided, since the slot owns the whole
visible dialog - but `title`/`description`, if still set, stay registered
with Reka as the dialog's accessible name/description, just visually
hidden instead of rendered as a header. Pass them if your own custom
content doesn't already include a heading Reka can associate with the
dialog:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open custom modal
  </SButton>

  <SModal v-model:open="open">
    <template #content>
      <div class="flex flex-col items-center gap-4 p-8 text-center">
        <div class="flex size-12 items-center justify-center rounded-full bg-[var(--selaras-resolved-color-success-subtle)] text-[var(--selaras-resolved-color-success-text)]">
          <SIcon name="hugeicons:checkmark-circle-01" class="size-6" />
        </div>
        <h2 class="text-base font-semibold text-[var(--selaras-resolved-text-default)]">
          Payment successful
        </h2>
        <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
          A receipt has been sent to your email.
        </p>
        <SButton class="mt-2" block @click="open = false">
          Done
        </SButton>
      </div>
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open">
  <template #content>
    <div class="flex flex-col items-center gap-4 p-8 text-center">
      ...
    </div>
  </template>
</SModal>
```

### Fullscreen

`fullscreen` takes the dialog full-viewport instead of the default centered
card - useful for image viewers, complex forms, or anything that benefits
from the extra room.


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open fullscreen modal
  </SButton>

  <SModal v-model:open="open" fullscreen title="Fullscreen" description="Takes up the entire viewport.">
    <template #body>
      Useful for image viewers, complex forms, or anything that benefits from
      the extra room a centered card can't give it.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Close
      </SButton>
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open" fullscreen title="Fullscreen" />
```

### Maximizable

`fullscreen` alone only sets a fixed initial layout - `maximizable` adds a
header button next to close that lets the user toggle between the default
and full-viewport layout at runtime, matching a comparable reference's
own dialog maximize toggle. `fullscreen` still sets which one it starts
in; pair with `v-model:fullscreen` if you need to read or control the
current state yourself:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open maximizable modal
  </SButton>

  <SModal v-model:open="open" maximizable title="Report" description="Toggle the button beside close to expand it.">
    <template #body>
      Click the maximize button to expand this to full-viewport, and again to
      restore it - the icon swaps to match the current state.
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open" maximizable title="Report" />
```

### Non-modal

`modal="false"` stops the dialog from blocking interaction with the rest of
the page - no focus trap, outside elements stay reachable and aren't hidden
from assistive tech. `overlay` is independent of this - a non-modal dialog
can still show (or hide) its own backdrop:


```vue
<script setup lang="ts">
const open = ref(false)
const clicks = ref(0)
</script>

<template>
  <div class="flex flex-wrap items-center gap-3">
    <SButton @click="open = true">
      Open non-modal
    </SButton>
    <SButton variant="soft" @click="clicks++">
      Page button (clicked {{ clicks }})
    </SButton>
  </div>

  <SModal v-model:open="open" :modal="false" :dismissible="false" title="Non-modal" description="The rest of the page stays interactive.">
    <template #body>
      Try clicking the "Page button" above without closing this dialog first -
      it still works, since <code class="font-mono">modal="false"</code>
      doesn't block outside interaction.
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open" :modal="false" title="Non-modal" />
```

### Scrollable content

The dialog is capped to the viewport height - a body taller than that
scrolls internally on its own, while the header and footer stay pinned in
place.


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open modal with long content
  </SButton>

  <SModal v-model:open="open" title="Terms of service" description="Please read the whole thing.">
    <template #body>
      <p v-for="i in 20" :key="i" class="mb-3 last:mb-0">
        Paragraph {{ i }} - the body scrolls internally once its content
        outgrows the viewport, while the header and footer stay pinned in
        place.
      </p>
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Decline
      </SButton>
      <SButton color="primary" @click="open = false">
        Accept
      </SButton>
    </template>
  </SModal>
</template>
```


### Intercepting dismissal

`SModal` doesn't override Reka UI's own defaults (Escape and an outside
click both dismiss it), but exposes the underlying events so you can
`preventDefault()` on them - e.g. to confirm before closing a dialog with
unsaved changes:

```vue-html
<SModal
  v-model:open="open"
  title="Edit profile"
  @escape-key-down="(e) => hasChanges && e.preventDefault()"
  @pointer-down-outside="(e) => hasChanges && e.preventDefault()"
/>
```

For the simpler, all-or-nothing case - a dialog that must not be dismissed
by anything but an explicit choice - `dismissible="false"` disables both
Escape and outside-click at once, and `close="false"` removes the close
button too:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open blocking modal
  </SButton>

  <SModal
    v-model:open="open"
    :dismissible="false"
    :close="false"
    title="Confirm your plan"
    description="You must pick an option below to continue."
  >
    <template #body>
      Escape and clicking outside are both disabled, and there's no close
      button - the footer actions are the only way out.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Keep free plan
      </SButton>
      <SButton color="primary" @click="open = false">
        Upgrade
      </SButton>
    </template>
  </SModal>
</template>
```


```vue-html
<SModal v-model:open="open" :dismissible="false" :close="false" title="Confirm your plan" />
```

The two raw events still fire even with `dismissible="false"` - useful for
something like a shake animation to signal the dialog won't close that way.

### Customizing the close/maximize buttons

Both header buttons render as real `<SButton>`s, so `:ui.close`/`:ui.maximize`
already reach them fully - not just classes. An object `:ui` value's
non-`class` keys apply as raw attrs/props, so `:ui="{ close: { color: 'danger' } }"`
works today without a dedicated prop for it:

```vue-html
<SModal v-model:open="open" title="Delete item" :ui="{ close: { color: 'danger' } }" />
```

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the dialog's own theme file:

:theme-source{name="modal"}

## Programmatic usage

`useModal()` opens a dialog from anywhere - a click handler, an async
callback - without a `v-model` of your own to manage. It works
automatically once `<SApp>` wraps your app, exactly like every other
component here; there's nothing extra to place, unlike `<SToast />`.

The given component owns the dialog's entire content, the same as the
`content` slot above - its own heading, its own buttons. `open()` returns
a promise that resolves with whatever value the component's own `close`
event carries, so an explicit action can resolve with real data while
dismissing via Escape or an outside click resolves with `undefined`:


```vue
<script setup lang="ts">
import ModalConfirmDialog from './ModalConfirmDialog.vue'

const modal = useModal()
const result = ref<string>()

async function confirm() {
  const confirmed = await modal.open(ModalConfirmDialog)
  result.value = confirmed === undefined ? 'Dismissed' : confirmed ? 'Deleted' : 'Cancelled'
}
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SButton color="danger" @click="confirm">
      Delete item
    </SButton>
    <p v-if="result" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Result: {{ result }}
    </p>
  </div>
</template>
```


```vue-html
<!-- ModalConfirmDialog.vue - a self-contained dialog -->
<template>
  <div class="p-8 text-center">
    <h2>Delete this item?</h2>
    <SButton variant="ghost" @click="$emit('close', false)">Cancel</SButton>
    <SButton color="danger" @click="$emit('close', true)">Delete</SButton>
  </div>
</template>
```

```ts
import ModalConfirmDialog from './ModalConfirmDialog.vue'

const modal = useModal()
const confirmed = await modal.open(ModalConfirmDialog)
// true, false, or undefined if dismissed without an explicit choice
```

`open()` also takes the same `title`/`description`/`dismissible`/`modal`/
`overlay`/`transition` options as the declarative props - `title`/
`description` are the only way to give a programmatically-opened dialog a
real accessible name/description, since the opened component always
renders through the `content` slot:

```ts
await modal.open(ModalConfirmDialog, { dismissible: false })
```

## Props

| Prop          | Type                                                                                                                                                        | Default |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `open`        | `boolean`                                                                                                                                                   | `false` |
| `title`       | `string`                                                                                                                                                    | -       |
| `description` | `string`                                                                                                                                                    | -       |
| `fullscreen`  | `boolean`                                                                                                                                                   | `false` |
| `maximizable` | `boolean`                                                                                                                                                   | `false` |
| `dismissible` | `boolean`                                                                                                                                                   | `true`  |
| `close`       | `boolean`                                                                                                                                                   | `true`  |
| `modal`       | `boolean`                                                                                                                                                   | `true`  |
| `overlay`     | `boolean`                                                                                                                                                   | `true`  |
| `transition`  | `boolean`                                                                                                                                                   | `true`  |
| `ui`          | `Partial<Record<'overlay' | 'content' | 'header' | 'headerActions' | 'title' | 'description' | 'close' | 'maximize' | 'body' | 'footer', string | object>>` | -       |

A `class` passed to `<SModal>` is merged into the dialog panel. Use `ui.content` for the same panel, or put a class directly on the default-slot trigger to style that trigger.

## Events

| Event                | Payload         | Description                                                                                      |
| -------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `update:open`        | `boolean`       | Open state changed                                                                               |
| `update:fullscreen`  | `boolean`       | Fired when `maximizable`'s toggle button changes the layout                                      |
| `escapeKeyDown`      | `KeyboardEvent` | Escape was pressed - `preventDefault()` to stop it from closing                                  |
| `pointerDownOutside` | `Event`         | A pointer went down outside the dialog - `preventDefault()` to stop it from closing              |
| `focusOutside`       | `Event`         | A non-modal dialog's outside element received focus - `preventDefault()` to stop it from closing |
| `afterLeave`         | -               | The close transition has finished (or fires immediately if `transition` is `false`)              |

## Slots

| Slot            | Description                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| default         | The trigger element                                                                                   |
| `content`       | Replaces the visible header/body/footer entirely (title/description, if set, still register for a11y) |
| `header`        | Overrides the default title/description block                                                         |
| `body`          | Main content                                                                                          |
| `footer`        | Usually action buttons                                                                                |
| `close-icon`    | Replaces the close button's icon (default: `hugeicons:cancel-01`)                                     |
| `maximize-icon` | Replaces the maximize button's icon while not fullscreen                                              |
| `minimize-icon` | Replaces the maximize button's icon while fullscreen                                                  |


# Popover

## Usage

Popover's `content` slot can hold anything - unlike
[Dropdown](https://selarasui.my.id/components/overlays/dropdown) (menu items) or
[Tooltip](https://selarasui.my.id/components/overlays/tooltip) (hover-only text), it's a blank,
interactive panel for things like a quick-edit form or a filter list:


```vue
<script setup lang="ts">
const open = ref(false)
const name = ref('')
</script>

<template>
  <SPopover v-model:open="open">
    <SButton variant="outline">
      Edit name
    </SButton>
    <template #content>
      <div class="flex w-64 flex-col gap-3">
        <p class="text-sm font-medium text-[var(--selaras-resolved-text-default)]">
          Display name
        </p>
        <SInput v-model="name" placeholder="Jane Doe" />
        <SButton size="sm" @click="open = false">
          Save
        </SButton>
      </div>
    </template>
  </SPopover>
</template>
```


```vue
<script setup lang="ts">
const open = ref(false)
const name = ref('')
</script>

<template>
  <SPopover v-model:open="open">
    <SButton variant="outline">
      Edit name
    </SButton>
    <template #content>
      <div class="flex w-64 flex-col gap-3">
        <p class="text-sm font-medium text-[var(--selaras-resolved-text-default)]">
          Display name
        </p>
        <SInput v-model="name" placeholder="Jane Doe" />
        <SButton size="sm" @click="open = false">
          Save
        </SButton>
      </div>
    </template>
  </SPopover>
</template>
```

`v-model:open` is optional - omit it and the popover manages its own open
state internally, toggled by clicking the trigger.

### Side and align

`side` picks which edge of the trigger the panel opens from (`top`,
`right`, `left`, default `bottom`); `align` controls how it lines up
along that edge (`start`, `center` default, `end`):


```vue
<script setup lang="ts">
const sides = ['top', 'right', 'bottom', 'left'] as const
const side = ref<typeof sides[number]>('bottom')
</script>

<template>
  <SButtonGroup>
    <SButton v-for="s in sides" :key="s" variant="soft" @click="side = s">
      {{ s }}
    </SButton>
  </SButtonGroup>

  <div class="mt-4">
    <SPopover :side="side">
      <SButton variant="outline">
        Open popover
      </SButton>
      <template #content>
        Positioned on the {{ side }}.
      </template>
    </SPopover>
  </div>
</template>
```


```vue-html
<SPopover side="right" align="start">...</SPopover>
```

### Arrow

`arrow` shows a small pointer triangle connecting the panel to its trigger.
Pass an object to set its width, height, rounded tip, or minimum clearance
from the panel corners (`padding`):


```vue
<template>
  <SPopover :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }">
    <SButton variant="outline">
      Custom arrow
    </SButton>
    <template #content>
      Points back at its trigger.
    </template>
  </SPopover>
</template>
```


```vue-html
<SPopover arrow>...</SPopover>
<SPopover :arrow="{ width: 16, height: 8, rounded: true, padding: 12 }">...</SPopover>
```

### Modal

Popover is non-modal by default - the rest of the page stays reachable,
and it isn't hidden from assistive tech. `modal="true"` traps focus and
blocks outside interaction instead, closer to how Modal/Slideover behave:

```vue-html
<SPopover modal>...</SPopover>
```

### Intercepting dismissal

Popover doesn't override Reka UI's own defaults (Escape and an outside
click both dismiss it), but exposes the underlying events so you can
`preventDefault()` on them:

```vue-html
<SPopover
  @escape-key-down="(e) => hasChanges && e.preventDefault()"
  @pointer-down-outside="(e) => hasChanges && e.preventDefault()"
>
  ...
</SPopover>
```

For the simpler, all-or-nothing case, `dismissible="false"` disables
Escape and outside-click (and, for a non-modal popover, an outside
element merely receiving focus) all at once - the raw events still fire,
so a consumer can still react, but none of them close it on their own:

```vue-html
<SPopover :dismissible="false">...</SPopover>
```

### Return focus on close

Reka returns keyboard focus to the trigger whenever the popover closes,
regardless of *why* it closed - including a purely programmatic `open`
change. That matters for a popover that can open on hover rather than a
deliberate click/keypress: focus landing back on a trigger nobody meant
to focus can itself count as focus moving "outside" whatever *other*
popover the pointer has since moved on to, closing that one too.
`returnFocusOnClose="false"` disables the behavior for cases like that:

```vue-html
<SPopover :return-focus-on-close="false">...</SPopover>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the popover's own theme file:

:theme-source{name="popover"}

### Positioning and portal

`positioning` configures the panel's side, alignment, offsets, and collision
behavior. It overrides the older top-level `side` and `align` props when both
are supplied. `portal` defaults to the document body; set it to `false` to
render inline, or pass a CSS selector or `HTMLElement` as the teleport target.
Use `ui.content` for panel styling and `#content` for its contents.

```vue-html
<SPopover :positioning="{ side: 'top', align: 'end', sideOffset: 8 }" portal="#overlay-root">...</SPopover>
```

## Props

| Prop                 | Type                                                    | Default                |
| -------------------- | ------------------------------------------------------- | ---------------------- |
| `open`               | `boolean`                                               | -                      |
| `side`               | `'top' | 'right' | 'bottom' | 'left'`                   | `'bottom'`             |
| `align`              | `'start' | 'center' | 'end'`                            | `'center'`             |
| `positioning`        | `OverlayPositioning`                                    | panel defaults         |
| `portal`             | `boolean | string | HTMLElement`                        | `true` (document body) |
| `modal`              | `boolean`                                               | `false`                |
| `dismissible`        | `boolean`                                               | `true`                 |
| `returnFocusOnClose` | `boolean`                                               | `true`                 |
| `arrow`              | `boolean | RoundedArrowConfig`                          | `false`                |
| `ui`                 | `Partial<Record<'content' | 'arrow', string | object>>` | -                      |

A `class` passed to `<SPopover>` is merged into its default-slot trigger element. Use `ui.content` to style the floating panel.

## Events

| Event                | Payload         | Description                                                                                                                                                                                                       |
| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update:open`        | `boolean`       | Open state changed                                                                                                                                                                                                |
| `escapeKeyDown`      | `KeyboardEvent` | Escape was pressed - `preventDefault()` to stop it from closing                                                                                                                                                   |
| `pointerDownOutside` | `Event`         | A pointer went down outside the popover - `preventDefault()` to stop it from closing                                                                                                                              |
| `focusOutside`       | `Event`         | A non-modal popover's outside element received focus - `preventDefault()` to stop it from closing                                                                                                                 |
| `openAutoFocus`      | `Event`         | Fires right before focus moves into the popover on open - `preventDefault()` to skip autofocus for that open (e.g. a hover-triggered open that shouldn't yank focus, while a keyboard-triggered one still should) |

## Slots

| Slot      | Description               |
| --------- | ------------------------- |
| default   | The trigger element       |
| `content` | The popover's own content |


# Slideover

## Usage

Slideover visibility is controlled with `v-model:open`, so it needs a ref
from the page it's used on.


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open slideover
  </SButton>

  <SSlideover v-model:open="open" title="Edit profile" description="Update your personal details.">
    <template #body>
      Slideover content goes here.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton @click="open = false">
        Save
      </SButton>
    </template>
  </SSlideover>
</template>
```


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open slideover
  </SButton>

  <SSlideover v-model:open="open" title="Edit profile" description="Update your personal details.">
    <template #body>
      Slideover content goes here.
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Cancel
      </SButton>
      <SButton @click="open = false">
        Save
      </SButton>
    </template>
  </SSlideover>
</template>
```

Always pass `title` (or a `header`/`content` slot containing a heading) -
without one, the panel has no accessible name for screen readers, and dev
mode warns about it.

### Side

`side` picks which edge the panel slides in from - `top`, `right`
(default), `bottom`, or `left`:


```vue
<script setup lang="ts">
const sides = ['top', 'right', 'bottom', 'left'] as const
const side = ref<typeof sides[number]>('right')
const open = ref(false)

function openWith(value: typeof sides[number]) {
  side.value = value
  open.value = true
}
</script>

<template>
  <SButtonGroup>
    <SButton v-for="s in sides" :key="s" variant="soft" @click="openWith(s)">
      {{ s }}
    </SButton>
  </SButtonGroup>

  <SSlideover v-model:open="open" :side="side" title="Filters">
    <template #body>
      Slides in from the {{ side }} edge.
    </template>
  </SSlideover>
</template>
```


```vue-html
<SSlideover v-model:open="open" side="left" title="Filters" />
```

### Inset

`inset` floats the panel with a margin and rounded corners instead of
sitting flush against the edge:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open inset slideover
  </SButton>

  <SSlideover v-model:open="open" inset title="Notifications">
    <template #body>
      Floats with a margin and rounded corners instead of sitting flush
      against the edge.
    </template>
  </SSlideover>
</template>
```


```vue-html
<SSlideover v-model:open="open" inset title="Notifications" />
```

### Custom content

`content` replaces the header/title/description/body/footer structure
entirely - useful when the panel doesn't fit the header-plus-body shape at
all. `close` is ignored once `content` is provided, since the slot owns
the whole visible panel - but `title`/`description`, if still set, stay
registered with Reka as the panel's accessible name/description, just
visually hidden instead of rendered as a header. Pass them if your own
custom content doesn't already include a heading Reka can associate with
the panel:


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open custom slideover
  </SButton>

  <SSlideover v-model:open="open">
    <template #content>
      <div class="flex flex-col items-center gap-4 p-8 text-center">
        <div class="flex size-12 items-center justify-center rounded-full bg-[var(--selaras-resolved-color-success-subtle)] text-[var(--selaras-resolved-color-success-text)]">
          <SIcon name="hugeicons:checkmark-circle-01" class="size-6" />
        </div>
        <h2 class="text-base font-semibold text-[var(--selaras-resolved-text-default)]">
          All caught up
        </h2>
        <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
          You have no new notifications.
        </p>
        <SButton class="mt-2" block @click="open = false">
          Close
        </SButton>
      </div>
    </template>
  </SSlideover>
</template>
```


```vue-html
<SSlideover v-model:open="open">
  <template #content>
    <div class="flex flex-col items-center gap-4 p-8 text-center">
      ...
    </div>
  </template>
</SSlideover>
```

### Non-modal

`modal="false"` stops the panel from blocking interaction with the rest of
the page - no focus trap, outside elements stay reachable and aren't hidden
from assistive tech. `overlay` is independent of this - a non-modal panel
can still show (or hide) its own backdrop:


```vue
<script setup lang="ts">
const open = ref(false)
const clicks = ref(0)
</script>

<template>
  <div class="flex flex-wrap items-center gap-3">
    <SButton @click="open = true">
      Open non-modal
    </SButton>
    <SButton variant="soft" @click="clicks++">
      Page button (clicked {{ clicks }})
    </SButton>
  </div>

  <SSlideover v-model:open="open" :modal="false" :dismissible="false" title="Non-modal" description="The rest of the page stays interactive.">
    <template #body>
      Try clicking the "Page button" above without closing this slideover
      first - it still works, since <code class="font-mono">modal="false"</code>
      doesn't block outside interaction.
    </template>
  </SSlideover>
</template>
```


```vue-html
<SSlideover v-model:open="open" :modal="false" title="Non-modal" />
```

### Scrollable content

The panel is capped to the viewport - a body taller than that scrolls
internally on its own, while the header and footer stay pinned in place.


```vue
<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <SButton @click="open = true">
    Open slideover with long content
  </SButton>

  <SSlideover v-model:open="open" title="Terms of service" description="Please read the whole thing.">
    <template #body>
      <p v-for="i in 20" :key="i" class="mb-3 last:mb-0">
        Paragraph {{ i }} - the body scrolls internally once its content
        outgrows the viewport, while the header and footer stay pinned in
        place.
      </p>
    </template>
    <template #footer>
      <SButton variant="ghost" @click="open = false">
        Decline
      </SButton>
      <SButton color="primary" @click="open = false">
        Accept
      </SButton>
    </template>
  </SSlideover>
</template>
```


### Intercepting dismissal

`SSlideover` doesn't override Reka UI's own defaults (Escape and an
outside click both dismiss it), but exposes the underlying events so you
can `preventDefault()` on them - e.g. to confirm before closing a panel
with unsaved changes:

```vue-html
<SSlideover
  v-model:open="open"
  title="Edit profile"
  @escape-key-down="(e) => hasChanges && e.preventDefault()"
  @pointer-down-outside="(e) => hasChanges && e.preventDefault()"
/>
```

For the simpler, all-or-nothing case - a panel that must not be dismissed
by anything but an explicit choice - `dismissible="false"` disables both
Escape and outside-click at once, and `close="false"` removes the close
button too:

```vue-html
<SSlideover v-model:open="open" :dismissible="false" :close="false" title="Confirm your plan" />
```

The two raw events still fire even with `dismissible="false"` - useful for
something like a shake animation to signal the panel won't close that way.

### Customizing the close button

The close button renders as a real `<SButton>`, so `:ui.close` already
reaches it fully - not just classes. An object `:ui` value's non-`class`
keys apply as raw attrs/props, so `:ui="{ close: { color: 'danger' } }"`
works today without a dedicated prop for it:

```vue-html
<SSlideover v-model:open="open" title="Delete item" :ui="{ close: { color: 'danger' } }" />
```

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the panel's own theme file:

:theme-source{name="slideover"}

## Programmatic usage

`useSlideover()` opens a panel from anywhere - a click handler, an async
callback - without a `v-model` of your own to manage. It works
automatically once `<SApp>` wraps your app, exactly like `useModal()`;
there's nothing extra to place.

The given component owns the panel's entire content, the same as the
`content` slot above - its own heading, its own buttons. `open()` returns
a promise that resolves with whatever value the component's own `close`
event carries, so an explicit action can resolve with real data while
dismissing via Escape or an outside click resolves with `undefined`:


```vue
<script setup lang="ts">
import SlideoverFilterPanel from './SlideoverFilterPanel.vue'

const slideover = useSlideover()
const result = ref<string>()

async function openFilters() {
  const applied = await slideover.open(SlideoverFilterPanel)
  result.value = applied === undefined ? 'Dismissed' : applied ? 'Applied' : 'Cancelled'
}
</script>

<template>
  <div class="flex flex-col items-start gap-2">
    <SButton @click="openFilters">
      Open filters
    </SButton>
    <p v-if="result" class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Result: {{ result }}
    </p>
  </div>
</template>
```


```vue-html
<!-- SlideoverFilterPanel.vue - a self-contained panel -->
<template>
  <div class="flex h-full flex-col">
    <h2>Filters</h2>
    <SCheckbox label="In stock only" />
    <SButton variant="ghost" @click="$emit('close', false)">Cancel</SButton>
    <SButton @click="$emit('close', true)">Apply</SButton>
  </div>
</template>
```

```ts
import SlideoverFilterPanel from './SlideoverFilterPanel.vue'

const slideover = useSlideover()
const applied = await slideover.open(SlideoverFilterPanel)
// true, false, or undefined if dismissed without an explicit choice
```

`open()` also takes the same `title`/`description`/`side`/`inset`/
`dismissible`/`modal`/`overlay`/`transition` options as the declarative
props:

```ts
await slideover.open(SlideoverFilterPanel, { side: 'left' })
```

## Props

| Prop          | Type                                                                                                                         | Default   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------- |
| `open`        | `boolean`                                                                                                                    | `false`   |
| `title`       | `string`                                                                                                                     | -         |
| `description` | `string`                                                                                                                     | -         |
| `side`        | `'top' | 'right' | 'bottom' | 'left'`                                                                                        | `'right'` |
| `inset`       | `boolean`                                                                                                                    | `false`   |
| `dismissible` | `boolean`                                                                                                                    | `true`    |
| `close`       | `boolean`                                                                                                                    | `true`    |
| `modal`       | `boolean`                                                                                                                    | `true`    |
| `overlay`     | `boolean`                                                                                                                    | `true`    |
| `transition`  | `boolean`                                                                                                                    | `true`    |
| `ui`          | `Partial<Record<'overlay' | 'content' | 'header' | 'title' | 'description' | 'close' | 'body' | 'footer', string | object>>` | -         |

A `class` passed to `<SSlideover>` is merged into the slideover panel. Use `ui.content` for the same panel, or put a class directly on the default-slot trigger to style that trigger.

## Events

| Event                | Payload         | Description                                                                                     |
| -------------------- | --------------- | ----------------------------------------------------------------------------------------------- |
| `update:open`        | `boolean`       | Open state changed                                                                              |
| `escapeKeyDown`      | `KeyboardEvent` | Escape was pressed - `preventDefault()` to stop it from closing                                 |
| `pointerDownOutside` | `Event`         | A pointer went down outside the panel - `preventDefault()` to stop it from closing              |
| `focusOutside`       | `Event`         | A non-modal panel's outside element received focus - `preventDefault()` to stop it from closing |
| `afterLeave`         | -               | The close transition has finished (or fires immediately if `transition` is `false`)             |

## Slots

| Slot         | Description                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| default      | The trigger element                                                                                   |
| `content`    | Replaces the visible header/body/footer entirely (title/description, if set, still register for a11y) |
| `header`     | Overrides the default title/description block                                                         |
| `body`       | Main content                                                                                          |
| `footer`     | Usually action buttons                                                                                |
| `close-icon` | Replaces the close button's icon (default: `hugeicons:cancel-01`)                                     |


# Toast

## Usage

Wrap your root `app.vue` in `<SApp>` once (already done by this docs site's
shell),
and place `<SToast />` inside it, wrapped in `<ClientOnly>`. Then push toasts
from anywhere with `useToast()`:

```vue-html
<!-- app.vue -->
<SApp>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
  <ClientOnly>
    <SToast />
  </ClientOnly>
</SApp>
```

`SApp` establishes Reka UI's `ToastProvider` around your whole app - it must
be mounted exactly once, at the true app root, not per-layout or per-page.
Mounting it more than once would register multiple providers for the same
toast state, causing every toast to render once per instance.

`SToast` is the part that actually renders toasts - it does real DOM
measurement and CSS-driven animation, so it needs `<ClientOnly>` around it.
`SApp` itself doesn't: it only establishes context, so it renders on the
server like any other component.


```vue
<script setup lang="ts">
const { add } = useToast()

function save() {
  add({ title: 'Saved', description: 'Your changes have been saved.' })
}
</script>

<template>
  <SButton @click="save">
    Show toast
  </SButton>
</template>
```


```vue
<script setup lang="ts">
const { add } = useToast()

function save() {
  add({ title: 'Saved', description: 'Your changes have been saved.' })
}
</script>

<template>
  <SButton @click="save">
    Show toast
  </SButton>
</template>
```

### Colors

`color` accepts any registered semantic role and applies its soft background,
matching the color treatment used by `SAlert`. The built-in `success`, `danger`,
`warning`, and `info` intents select matching default icons. Other roles do not
guess an icon; set `icon` explicitly when needed. With no color, the toast keeps
a neutral surface and an explicit icon uses a neutral color:


```vue
<script setup lang="ts">
const { add } = useToast()

function show(color: 'success' | 'danger' | 'warning' | 'info') {
  add({
    color,
    title: color === 'success' ? 'Saved' : color === 'danger' ? 'Failed to save' : color === 'warning' ? 'Unsaved changes' : 'Heads up',
    description: color === 'success' ? 'Your changes have been saved.' : color === 'danger' ? 'Something went wrong - try again.' : color === 'warning' ? 'You have changes that haven\'t been saved yet.' : 'This action can\'t be undone.',
  })
}
</script>

<template>
  <div class="flex flex-wrap gap-2">
    <SButton color="success" variant="soft" @click="show('success')">
      Success
    </SButton>
    <SButton color="danger" variant="soft" @click="show('danger')">
      Danger
    </SButton>
    <SButton color="warning" variant="soft" @click="show('warning')">
      Warning
    </SButton>
    <SButton color="info" variant="soft" @click="show('info')">
      Info
    </SButton>
  </div>
</template>
```


```vue-html
<SButton @click="add({ color: 'success', title: 'Saved' })">
  Show success toast
</SButton>
```

### Position and stacking

Set `position` on the single `<SToast />` renderer to choose any screen corner
or center edge. The default is `bottom-right`. Multiple toasts layer into a
compact stack: each new toast slides in at the front and pushes the older
ones back, with up to three cards visible. The stack fans open while the
pointer or keyboard focus is inside it; set `expand` to show every toast
separately instead. Click a position a few times to see the stack build up,
then hover it:


```vue
<script setup lang="ts">
import type { ToastPosition } from '@sewadah/selaras/types'

const { add } = useToast()
const position = useDocsToastPosition()

const positions: ToastPosition[] = ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right']

function show(next: ToastPosition) {
  position.value = next
  add({ title: 'Saved', description: `Shown at ${next}.` })
}

// Put the shared renderer back where every other example expects it.
onBeforeUnmount(() => {
  position.value = 'bottom-right'
})
</script>

<template>
  <div class="flex flex-wrap gap-2">
    <SButton v-for="item in positions" :key="item" variant="outline" color="neutral" @click="show(item)">
      {{ item }}
    </SButton>
  </div>
</template>
```


```vue-html
<ClientOnly>
  <SToast position="top-center" expand />
</ClientOnly>
```

### Timing and count

`duration` sets the default time in milliseconds that each toast stays visible;
the `duration` passed to `add()` overrides it for that toast. `max` limits how
many are visible at once. When the limit is reached, the oldest toast is
removed so newer notifications can appear without building a hidden backlog.

```vue-html
<ClientOnly>
  <SToast :duration="8000" :max="3" />
</ClientOnly>
```

### Accessibility

Toast renders Reka UI's Toast primitive, so the accessibility semantics
come from there rather than being reimplemented here: each toast announces
itself via `aria-live` without stealing focus from whatever the user was
doing, a hover or focus inside it pauses its own dismiss timer (resuming
once it's left), and on touch devices it can be swiped away.

## `useToast()`

| Method       | Description                                                                           |
| ------------ | ------------------------------------------------------------------------------------- |
| `add(toast)` | Pushes a toast (`{ title?, description?, duration?, color?, icon? }`), returns its id |
| `remove(id)` | Dismisses a toast by id                                                               |

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's the toast's own theme file:

:theme-source{name="toast"}

## Props (`SToast`)

| Prop       | Type                                                                                                 | Default          |
| ---------- | ---------------------------------------------------------------------------------------------------- | ---------------- |
| `ui`       | `Partial<Record<'viewport' | 'root' | 'title' | 'description' | 'icon' | 'close', string | object>>` | -                |
| `position` | `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'`         | `'bottom-right'` |
| `expand`   | `boolean`                                                                                            | `false`          |
| `duration` | `number`                                                                                             | `5000`           |
| `max`      | `number`                                                                                             | `5`              |


# Tooltip

## Usage


```vue
<template>
  <STooltip text="I'm a tooltip">
    <SButton variant="outline">
      Hover me
    </SButton>
  </STooltip>
</template>
```


```vue
<template>
  <STooltip text="I'm a tooltip">
    <SButton variant="outline">
      Hover me
    </SButton>
  </STooltip>
</template>
```

Requires `<SApp>` around your root `app.vue` (already done by this docs site's
shell) - it establishes Reka UI's shared `TooltipProvider`, so quickly
moving between adjacent tooltips skips the full delay the second time,
instead of every tooltip waiting out `delayDuration` independently.

### Keyboard shortcut

`kbds` renders a row of small key badges alongside the text - useful for
surfacing a shortcut on the action a button already performs. It takes the
literal symbols to display, not semantic key names - there's no
platform-specific mapping (e.g. `'meta'` to `⌘`) built in, so pass whatever
you want shown (`['⌘', 'S']`, `['Ctrl', 'S']`, ...).


```vue
<template>
  <STooltip text="Save" :kbds="['⌘', 'S']">
    <SButton variant="outline">
      Save
    </SButton>
  </STooltip>
</template>
```


```vue-html
<STooltip text="Save" :kbds="['⌘', 'S']">
  <SButton variant="outline">Save</SButton>
</STooltip>
```

### Disabling and the arrow

`disabled` suppresses the tooltip entirely (it never opens); `arrow="false"`
hides the little pointer triangle for a plain floating tooltip. An object can
set the arrow's width, height, and corner clearance (`padding`):

```vue-html
<STooltip text="Won't show" disabled>...</STooltip>
<STooltip text="No arrow" :arrow="false">...</STooltip>
<STooltip text="Wide arrow" :arrow="{ width: 16, height: 8, padding: 12 }">...</STooltip>
```

### Custom content

The `content` slot replaces the plain-text `text` prop with anything -
useful for a richer hint than a single line of text can give:

```vue-html
<STooltip>
  <SButton variant="outline">
    Hover me
  </SButton>
  <template #content>
    <span class="flex items-center gap-1">
      <SIcon name="hugeicons:information-circle" />
      Custom content
    </span>
  </template>
</STooltip>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `Tooltip`'s own theme file:

:theme-source{name="tooltip"}

### Positioning and portal

Use `positioning` for the tooltip's side, alignment, offsets, and collision
behavior. It overrides the older top-level `side` prop when both are supplied.
`portal` defaults to the document body; set it to `false` to render inline or
pass a CSS selector or `HTMLElement` as the teleport target. `ui.content`
controls styling, while `#content` supplies custom content.

```vue-html
<STooltip text="Help" :positioning="{ side: 'bottom', align: 'end' }" portal="#overlay-root">...</STooltip>
```

## Props

| Prop            | Type                                                                     | Default                |
| --------------- | ------------------------------------------------------------------------ | ---------------------- |
| `text`          | `string`                                                                 | -                      |
| `side`          | `'top' | 'right' | 'bottom' | 'left'`                                    | `top`                  |
| `positioning`   | `OverlayPositioning`                                                     | tooltip defaults       |
| `portal`        | `boolean | string | HTMLElement`                                         | `true` (document body) |
| `delayDuration` | `number`                                                                 | `200`                  |
| `kbds`          | `string[]`                                                               | -                      |
| `arrow`         | `boolean | ArrowConfig`                                                  | `true`                 |
| `disabled`      | `boolean`                                                                | `false`                |
| `ui`            | `Partial<Record<'content' | 'arrow' | 'kbds' | 'kbd', string | object>>` | -                      |

A `class` passed to `<STooltip>` is merged into its default-slot trigger element. Use `ui.content` to style the floating tooltip.

## Slots

| Slot      | Description                                        |
| --------- | -------------------------------------------------- |
| default   | The trigger element                                |
| `content` | Replaces the plain-text `text` with custom content |


# Callout

## Usage


```vue
<template>
  <div class="flex w-full flex-col gap-3">
    <SCallout type="note" title="Note">
      This applies to every recent version - no upgrade needed.
    </SCallout>
    <SCallout type="tip" title="Tip">
      Pass <code>icon="false"</code> to drop the leading icon entirely.
    </SCallout>
    <SCallout type="warning" title="Warning">
      This changes how the export command behaves - check the migration notes first.
    </SCallout>
    <SCallout type="danger" title="Danger">
      Running this in production deletes the entire dataset.
    </SCallout>
  </div>
</template>
```


```vue-html
<SCallout type="tip" title="Tip">
  Pass <code>icon="false"</code> to drop the leading icon entirely.
</SCallout>
```

`type` picks both the accent color and the default icon - `note` (the
default), `tip`, `warning`, and `danger`, matching the four admonition
levels most docs sites converge on. It shares Alert's soft surface and
semantic color treatment. Hovering it, or focusing content inside it, reveals
a 2px striped border in that color. Unlike [Alert](https://selarasui.my.id/components/elements/alert),
a callout has no `variant`/`closable` - it is meant to sit inline in prose and
has no dismiss behavior.

## In markdown

Every Selaras component is already globally registered under its `S`-prefixed
name (this module's own `addComponentsDir` call, `src/module.ts`) - unlike
[Prose](https://selarasui.my.id/components/typography/prose)'s two enhanced components, nothing else needs
wiring for `@nuxt/content` to resolve a plain `::s-component-name{...}` block
directly to it. A prop goes in the block's own `{...}` attrs; a named slot
(`title` here) is a `#slot-name` line inside the block, `@nuxtjs/mdc`'s own
convention (`MDCSlot`) - and the block's own body becomes the default slot:

```text
::s-callout{type="warning"}
#title
Heads up
This changes how the export command behaves - check the migration notes first.
::
```

::s-callout
---
type: warning
---
#title
Heads up

This changes how the export command behaves - check the migration notes first.
::

The same pattern works for any already-shipped component, props and named
slots included - not just the two proven here. [Alert](https://selarasui.my.id/components/elements/alert),
for one, works identically:

```text
::s-alert{color="info"}
#title
Heads up
#description
This changes how the export command behaves - check the migration notes first.
::
```

::s-alert
---
color: info
---
#title
Heads up

#description
This changes how the export command behaves - check the migration notes first.
::

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `Callout`'s own theme file:

:theme-source{name="callout"}

Global and scoped theme recipes use `ui.callout`.

## Props

| Prop    | Type                                            | Default  |
| ------- | ----------------------------------------------- | -------- |
| `type`  | `'note' | 'tip' | 'warning' | 'danger'`         | `'note'` |
| `title` | `string`                                        | -        |
| `icon`  | `string | false`                                | -        |
| `ui`    | `Partial<Record<CalloutSlot, string | object>>` | -        |

## Slots

| Slot    | Description                                  |
| ------- | -------------------------------------------- |
| `title` | Custom title content, overrides `title` prop |
| default | The callout's body                           |


# CodeButton

## Usage


```vue
<template>
  <SCodeButton code="npm install @sewadah/selaras" />
</template>
```


```vue-html
<SCodeButton code="npm install @sewadah/selaras" />
```

Unlike [ProsePre](https://selarasui.my.id/components/typography/prose) (a full code block) or
[CodeGroup](https://selarasui.my.id/components/typography/code-group) (several of those, tabbed),
`SCodeButton` is meant to sit inline in a sentence - referencing a single
command without breaking the reading flow into a block. `code` is both what's
displayed and what actually gets copied; override just the displayed text
with the default slot when they should differ:

```vue-html
<SCodeButton code="npm install @sewadah/selaras">
  Copy install command
</SCodeButton>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `CodeButton`'s own theme file:

:theme-source{name="code-button"}

## Props

| Prop   | Type                                               | Default      |
| ------ | -------------------------------------------------- | ------------ |
| `code` | `string`                                           | - (required) |
| `ui`   | `Partial<Record<CodeButtonSlot, string | object>>` | -            |

## Slots

| Slot    | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| default | Overrides the displayed text - `code` still governs what's copied |


# CodeGroup

## Usage


```vue
<template>
  <SCodeGroup>
    <SProsePre filename="npm" language="bash" code="npm install @sewadah/selaras">
      npm install @sewadah/selaras
    </SProsePre>
    <SProsePre filename="pnpm" language="bash" code="pnpm add @sewadah/selaras">
      pnpm add @sewadah/selaras
    </SProsePre>
    <SProsePre filename="yarn" language="bash" code="yarn add @sewadah/selaras">
      yarn add @sewadah/selaras
    </SProsePre>
  </SCodeGroup>
</template>
```


```vue-html
<SCodeGroup>
  <SProsePre filename="npm" language="bash" code="npm install @sewadah/selaras">
npm install @sewadah/selaras
  </SProsePre>
  <SProsePre filename="pnpm" language="bash" code="pnpm add @sewadah/selaras">
pnpm add @sewadah/selaras
  </SProsePre>
</SCodeGroup>
```

`SCodeGroup` reads its own default slot's children directly (works with any
children, not just [Prose](https://selarasui.my.id/components/typography/prose) ones) and renders each as a tab
via [Tabs](https://selarasui.my.id/components/navigation/tabs) - the label comes from each child's `filename`
prop, falling back to `language`, falling back to `Tab 1`/`Tab 2`/... (by
position) for a child with neither. Known filename/language icons appear in
the tab as well. When a child is `SProsePre`, its header row is hidden so the
label isn't repeated above the panel; this also hides that row's copy button.
Other child content is rendered as provided.

### In markdown

Once wired into `@nuxt/content` via a `CodeGroup.vue` adapter (same recipe as
[Prose](https://selarasui.my.id/components/typography/prose)), plain adjacent fenced code blocks under
`::code-group` become tabs automatically - the `[label]` after the language
becomes each tab's title:

````md
::code-group

```bash [npm]
npm install @sewadah/selaras
```

```bash [pnpm]
pnpm add @sewadah/selaras
```

::
````

## Props

`SCodeGroup` takes no props - it derives everything from its children.


# CodeTree

## Usage


```vue
<script setup lang="ts">
const items = [
  {
    name: 'src',
    children: [
      { name: 'index.ts', code: 'export { useCommandPalette } from \'./composables/use-command-palette\'\n' },
      { name: 'App.vue', code: '<template>\n  <SApp>\n    <NuxtPage />\n  </SApp>\n</template>\n' },
    ],
  },
  { name: 'package.json', code: '{\n  "name": "my-app",\n  "dependencies": {\n    "selaras": "^1.0.0"\n  }\n}\n' },
]
</script>

<template>
  <SCodeTree :items="items" class="h-64 w-full" />
</template>
```


```vue-html
<SCodeTree :items="[
  { name: 'src', children: [{ name: 'index.ts', code: 'export default 1' }] },
  { name: 'package.json', code: '{}' },
]" />
```

Built on [FileTree](https://selarasui.my.id/components/typography/file-tree) for the left panel - a
node's `code` is syntax-highlighted for its filename once selected. Set
`language` on a file to override the language inferred from its extension.
The first file found (depth-first) is selected by default, so the panel is
never empty on load. Replacing `items` with a new array selects a new default;
mutating the existing array leaves the current selection alone.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `CodeTree`'s own theme file:

:theme-source{name="code-tree"}

## Props

| Prop              | Type                                             | Default      |
| ----------------- | ------------------------------------------------ | ------------ |
| `items`           | `CodeTreeFile[]`                                 | - (required) |
| `defaultExpanded` | `boolean`                                        | `true`       |
| `ui`              | `Partial<Record<CodeTreeSlot, string | object>>` | -            |

### `CodeTreeFile`

Extends [`FileTreeNode`](https://selarasui.my.id/components/typography/file-tree) with one added field:

| Field      | Type             | Description                                                                               |
| ---------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `name`     | `string`         | The file/directory's displayed label                                                      |
| `children` | `CodeTreeFile[]` | Present on a directory node, absent on a file                                             |
| `icon`     | `string`         | Overrides the default file/folder icon                                                    |
| `code`     | `string`         | The file's content, shown with syntax highlighting once selected - ignored on a directory |
| `language` | `string`         | Syntax language override; otherwise inferred from the filename                            |


# FileTree

## Usage


```vue
<script setup lang="ts">
const items = [
  {
    name: 'src',
    children: [
      { name: 'index.ts' },
      { name: 'components', children: [{ name: 'Button.vue' }, { name: 'Input.vue' }] },
    ],
  },
  { name: 'package.json' },
  { name: 'README.md' },
]
</script>

<template>
  <SFileTree :items="items" class="w-64" />
</template>
```


```vue-html
<SFileTree :items="[
  { name: 'src', children: [{ name: 'index.ts' }] },
  { name: 'package.json' },
]" />
```

A node with `children` renders as a directory (click to expand/collapse), one
without renders as a file (click to select it, emitting `update:selected`
with that node). Pass `selected` back in to highlight the active row - a
controlled pattern, the same shape [CodeTree](https://selarasui.my.id/components/typography/code-tree)
builds on for its own file-to-content pairing. File rows use the matching VS
Code icon when the filename is recognized; `icon` always overrides it.

### Controlled selection

`selected`/`update:selected` follow Vue's `v-model:selected` shorthand -
clicking a file emits the node back out, and passing it back in as
`selected` highlights that row:


```vue
<script setup lang="ts">
const items = [
  {
    name: 'src',
    children: [
      { name: 'index.ts' },
      { name: 'components', children: [{ name: 'Button.vue' }, { name: 'Input.vue' }] },
    ],
  },
  { name: 'package.json' },
  { name: 'README.md' },
]

const selected = ref()
</script>

<template>
  <div class="flex w-64 flex-col gap-2">
    <SFileTree v-model:selected="selected" :items="items" />
    <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
      Selected: {{ selected?.name ?? 'none' }}
    </p>
  </div>
</template>
```


```vue-html
<SFileTree v-model:selected="selected" :items="items" />
<p>Selected: {{ selected?.name ?? 'none' }}</p>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `FileTree`'s own theme file:

:theme-source{name="file-tree"}

## Props

| Prop              | Type                                             | Default      |
| ----------------- | ------------------------------------------------ | ------------ |
| `items`           | `FileTreeNode[]`                                 | - (required) |
| `selected`        | `FileTreeNode`                                   | -            |
| `defaultExpanded` | `boolean`                                        | `true`       |
| `ui`              | `Partial<Record<FileTreeSlot, string | object>>` | -            |

Each node accepts `name`, optional `children`, optional `icon`, and optional
`language`. `language` is used as a fallback hint when the filename does not
identify a VS Code file icon.

## Emits

| Event             | Payload        |
| ----------------- | -------------- |
| `update:selected` | `FileTreeNode` |


# Prose

## Usage

Wrap any rendered HTML - markdown output, a CMS's rich-text body,
hand-written content, whatever produced it - in the `selaras-prose`
class for consistent long-form typography, no components or
`@nuxt/content` required:


```vue
<template>
  <div class="selaras-prose">
    <SProseH3 id="standalone-heading">
      A heading
    </SProseH3>
    <p>
      Any plain HTML picks up consistent typography from the
      <code>.selaras-prose</code> class alone - <strong>bold</strong>,
      <em>italic</em>, and <code>inline code</code> all work with no
      components involved.
    </p>
  </div>
</template>
```


```vue-html
<div class="selaras-prose">
  <h3>A heading</h3>
  <p>Some <strong>bold</strong> text.</p>
</div>
```

It's a separate, opt-in stylesheet - not bundled into `theme.css` (which
you already import yourself, see [Installation](https://selarasui.my.id/overview/getting-started/installation))

- so a project with no long-form content never pays for it:

```css
@import "tailwindcss";
@import "@sewadah/selaras/prose.css";
```

Every element selector inside it is wrapped in `:where(...)`, which
carries zero specificity - your own classes, or even another plain
element selector combined with one more thing, always win. No
`!important`, and nothing to override one rule at a time on a page
where the defaults don't fit.

Tables fill the content width by default. When columns need more space,
the table scrolls horizontally without widening the page. Headers and
body cells keep their columns aligned.

### Fonts

`selaras-prose` doesn't hardcode a font stack - it follows whatever
your project already uses, through three CSS variables you can
override independently of your site-wide fonts if prose specifically
should look different:

```css
:root {
  --selaras-prose-font-body: inherit;
  --selaras-prose-font-heading: inherit;
  --selaras-prose-font-mono: var(--font-mono, ui-monospace, monospace);
}
```

## The two enhanced components

Two elements have real interactive behavior a CSS class can't
replicate, so they're still real components: `SProsePre` (a
copy-to-clipboard button, via [Button](https://selarasui.my.id/components/elements/button),
plus a plain filename/language header with a file-type
[Icon](https://selarasui.my.id/components/elements/icon)) and `SProseH1`-`SProseH6` (wraps
heading content in a self-anchor `<a href="#id">` when given an `id` -
this page's own headings work exactly this way).

Both are usable directly, the same as any other component:

```vue-html
<SProseH3 id="a-heading">A heading</SProseH3>
<SProsePre code="const x = 1" language="ts" />
```

## Props

### `SProsePre`

| Prop         | Type       | Default                             |
| ------------ | ---------- | ----------------------------------- |
| `code`       | `string`   | -                                   |
| `language`   | `string`   | -                                   |
| `filename`   | `string`   | -                                   |
| `icon`       | `string`   | resolved from `filename`/`language` |
| `showHeader` | `boolean`  | `true`                              |
| `highlights` | `number[]` | -                                   |
| `meta`       | `string`   | -                                   |

`code` drives the copy button (nothing renders if it's unset) and is also
copied verbatim, regardless of what's in the default slot. The header bar
shows `filename` if set, else a plain label for `language` if that's set, else
nothing; set `showHeader` to `false` to hide the whole metadata/copy row.
CodeGroup does this automatically and moves the filename and file-type icon
into its tab. Beside either, a file-type icon is resolved from the filename's
extension first, then the fence language - for example `vue` renders the
`vscode-icons:file-type-vue` glyph - with no icon for an unrecognized
type. Pass `icon` to override that resolution. Long filenames truncate in
the header, with the full path available on hover. Copying changes the button
to a success-colored check; its labels come from `copyCode` and `codeCopied`
in the [message registry](https://selarasui.my.id/utilities/composables/use-messages).

Customize the header through the `prose` theme's `preHeader`, `preLabel`,
`preIcon`, `preFilename`, `preLanguage`, and `preCopyButton` slots in
`app.config.selaras.ui` or `STheme`. `highlights` and `meta` are accepted but currently have no
effect - there's no line-highlighting logic wired up yet anywhere in the
component, so passing either does nothing visible today. They're reserved
for that feature landing later; don't wire them up expecting output.

### `SProseH1`-`SProseH6`

| Prop | Type     | Default |
| ---- | -------- | ------- |
| `id` | `string` | -       |

### Why only these two aren't CSS

Everything else a markdown renderer produces - links, images,
paragraphs, lists, tables, emphasis - is pure styling with no behavior
of its own, so `selaras-prose` covers it entirely. A copy button needs
real JavaScript; an anchor-link heading needs a real `<a>` element in
the actual DOM a renderer produces, which only a *component-based*
renderer (one that resolves each markdown element to a real component
instance with props, `id` included - `@nuxt/content`/`@nuxtjs/mdc` is
the common case) can do at all. A raw-HTML-string pipeline (most non-
Nuxt-Content cases: a CMS, hand-rolled markdown-it, a headless CMS's
rendered body) has no hook to swap in a component per element -
`selaras-prose` still styles whatever plain `<pre>`/`<h1 id="...">`
that pipeline emits, just without the copy button or the clickable
anchor.

## Wiring into `@nuxt/content`

This module registers `ProsePre`/`ProseH1`-`ProseH6` a *second* time
under their own bare, unprefixed names (`ProseH1`, not `SProseH1`).
That's necessary but **not sufficient on its own** - `@nuxtjs/mdc`
ships its own built-in default `ProseH1`/`ProsePre` (styling-only,
no copy button, no anchor link) under those exact same names, and its
own registration wins that naming collision regardless of this
module's own `priority` setting (confirmed by reading
`@nuxtjs/mdc`'s own source - `MDCRenderer` never does a global-name
component *lookup* for these tags at all, so registration order/
priority never even enters into it).

The reliable path is `<ContentRenderer>`'s own `components` prop -
`@nuxtjs/mdc` merges it *over* its built-in defaults (see
`MDCRenderer.vue`'s own `tags` computed), so this always wins:

```vue-html
<ContentRenderer
  :value="page"
  :components="{ h1: 'SProseH1', h2: 'SProseH2', h3: 'SProseH3', h4: 'SProseH4', h5: 'SProseH5', h6: 'SProseH6', pre: 'SProsePre' }"
  class="selaras-prose"
/>
```

This docs site's own pages are wired exactly this way in
`docs/pages/[...slug].vue`, and every heading/code block on this very page
renders through it.

Everything else, `selaras-prose` styles directly - no `components`
entry needed for it, since it's plain HTML either way.

### A known SSR caveat

Confirmed via a real production build (`nuxt build` + serving the
built output, not just dev mode): on the *very first* server-rendered
HTML for a page, any component `@nuxtjs/mdc` resolves dynamically -
headings and code blocks included, regardless of whether it's
resolving to this library's components, its own built-in defaults, or
anything else passed through `:components` - can render as a literal,
unresolved tag (`<SProsePre ...>` as text, not real markup) instead of
the actual element. This traces to `MDCRenderer`'s own `async setup()`
combined with Vue's `resolveComponent`, a known Vue SSR interaction
(dynamic component resolution needs Vue's current-instance context,
which an `await` inside an async `setup()` doesn't reliably preserve
server-side) - not something introduced by this wiring, and not
something this module can fix from the outside. It self-corrects
immediately on client hydration (confirmed: every example on this
page works correctly once loaded in a real browser) - the practical
impact is limited to a no-JS/crawler-only view of the very first
response, not anything a real visitor sees.

## Custom `:ui`

`SProsePre` and `SProseH1`-`SProseH6` all resolve their slots from the
same theme file - overriding `ui` on any one of them reads from, and
merges over, this one shared source. To see exactly what you'd be
overriding - the current default classes for every slot and variant -
here's `Prose`'s own theme file:

:theme-source{name="prose"}


# ReadMore

## Usage


```vue
<template>
  <SReadMore :preview-height="80" class="w-full max-w-md text-sm text-[var(--selaras-resolved-text-muted)]">
    <p>
      Selaras is a Nuxt module that provides a set of UI components built on
      Reka UI primitives, styled with Tailwind CSS v4 and tailwind-variants.
    </p>
    <p class="mt-2">
      Every component accepts a single <code>:ui</code> prop for per-instance
      style overrides, reads its colors from a small set of semantic CSS
      custom properties instead of hardcoded Tailwind classes, and animates
      with CSS alone - no JavaScript animation library anywhere in the
      library.
    </p>
  </SReadMore>
</template>
```


```vue-html
<SReadMore :preview-height="200">
  <p>A long block of content...</p>
</SReadMore>
```

Collapsed height is a real pixel value (`previewHeight`, `200` by default),
not a line-clamp - so it truncates any content, not just plain text. The
reveal animates by transitioning `max-height` toward the content's own
measured height (via `ResizeObserver`, re-measured if it changes), not the
`auto` keyword - CSS can't animate toward `auto`, there's no intermediate
value to interpolate through.

Content shorter than `previewHeight` renders with no truncation UI at
all - the fade and toggle only appear once there's actually more to reveal.
Before the first client-side measurement, though, content renders truncated
by default (the safer assumption for SSR/no-JS output) - it never briefly
flashes fully expanded before collapsing down.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot and variant - here's `ReadMore`'s own theme file:

:theme-source{name="read-more"}

Global and scoped theme recipes use `ui.readMore`.

## Props

| Prop            | Type                                             | Default |
| --------------- | ------------------------------------------------ | ------- |
| `previewHeight` | `number`                                         | `200`   |
| `ui`            | `Partial<Record<ReadMoreSlot, string | object>>` | -       |

## Slots

| Slot    | Description                 |
| ------- | --------------------------- |
| default | The content being truncated |


# DashboardGroup

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardGroup>
  <SDashboardSidebar>
    <template #header>Acme Inc</template>
    <nav>...</nav>
  </SDashboardSidebar>
  <SDashboardResizeHandle />
  <SDashboardPanel>
    <SDashboardNavbar title="Overview" />
    <main>...</main>
  </SDashboardPanel>
</SDashboardGroup>
```

`SDashboardGroup` coordinates the whole shell - place a
[DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar), a
[DashboardResizeHandle](https://selarasui.my.id/composites/dashboard/dashboard-resize-handle), and a
[DashboardPanel](https://selarasui.my.id/composites/dashboard/dashboard-panel) inside it directly (not
wrapped in anything else - it needs to see all three as its own children).
It's a themed wrapper around [Splitter](https://selarasui.my.id/components/layout/splitter) -
`SDashboardSidebar`/`SDashboardPanel` wrap `SSplitterPanel` the same way, so
the resize/collapse/remember-the-width behavior all comes from that same
general-purpose primitive, not logic specific to a dashboard shell.

### Persistence

The sidebar's width (and whether it's collapsed) is remembered across
reloads via a cookie, keyed by `autoSaveId` - give pages that shouldn't
share one remembered layout their own distinct id. A cookie rather than
Reka's own default `localStorage`-backed storage - same-origin
server-readable, portable across a full page reload rather than just
client-side navigation, and works with privacy tooling that blocks
`localStorage` but allows first-party cookies.

The server-rendered sidebar uses its configured pixel default, keeping
the main panel visible before hydration. Remembered width and collapse
state apply after mounting: the splitter restores them when its panels
register and the container can be measured. A returning visitor first sees
the default width, then the saved layout.

### Mobile

Below `mobileBreakpoint` (768px by default), there's no resizable panel at
all - `SDashboardSidebar` switches to rendering its content inside a
[Drawer](https://selarasui.my.id/components/overlays/drawer) overlay instead, and
`SDashboardResizeHandle` renders nothing (there's nothing to drag once the
sidebar isn't part of a split layout). Try resizing this page's own browser
window narrower than a phone to see it switch live.

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `DashboardGroup`'s own theme file:

:theme-source{name="dashboard-group"}

## Props

| Prop               | Type                                       | Default               |
| ------------------ | ------------------------------------------ | --------------------- |
| `autoSaveId`       | `string`                                   | `'selaras-dashboard'` |
| `mobileBreakpoint` | `number`                                   | `768`                 |
| `ui`               | `Partial<Record<'root', string | object>>` | -                     |


# DashboardNavbar

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardNavbar title="Overview">
  <template #leading>
    <SDashboardSidebarToggle />
  </template>
  <SButton size="sm" icon="hugeicons:plus-sign">New</SButton>
</SDashboardNavbar>
```

Distinct from the site-wide [Header](https://selarasui.my.id/components/layout/header) - this one
lives *inside* a [DashboardPanel](https://selarasui.my.id/composites/dashboard/dashboard-panel), scoped
to the main content area only.

Nothing renders in the leading slot by default - matching every other piece
of this family (a [DashboardResizeHandle](https://selarasui.my.id/composites/dashboard/dashboard-resize-handle)
isn't auto-inserted between the sidebar and panel either), a sidebar-toggle
button is something you compose in explicitly rather than something
`SDashboardNavbar` assumes you want. See
[DashboardSidebarToggle](https://selarasui.my.id/composites/dashboard/dashboard-sidebar-toggle) for
what it does and how to customize it - it collapses/expands
[DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) (or opens/closes it
on mobile, see [DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group)'s own
"Mobile" section), and renders nothing itself until there's an actual
sidebar in the same [DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) to
control.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `DashboardNavbar`'s own theme file:

:theme-source{name="dashboard-navbar"}

## Props

| Prop    | Type                                                    | Default |
| ------- | ------------------------------------------------------- | ------- |
| `title` | `string`                                                | -       |
| `ui`    | `Partial<Record<DashboardNavbarSlot, string | object>>` | -       |

## Slots

| Slot      | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `leading` | Empty by default - a sidebar-toggle button, typically                 |
| `title`   | Custom title content, overrides `title` prop                          |
| default   | Trailing content - actions, a search trigger, whatever the page needs |


# DashboardPanel

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardPanel>
  <SDashboardNavbar title="Overview" />
  <main>...</main>
</SDashboardPanel>
```

Must be a direct child of [DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group),
alongside [DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) - a plain
(non-collapsible) [SplitterPanel](https://selarasui.my.id/components/layout/splitter) on desktop,
since Reka's own panel-group layout math needs every direct child to be a
real panel, so this exists even though it isn't independently resizable or
collapsible itself, just fills whatever space the sidebar doesn't take.
Typically
contains a [DashboardNavbar](https://selarasui.my.id/composites/dashboard/dashboard-navbar) plus a
scrollable `<main>` for the actual page content - neither is required
though, `SDashboardPanel` has no opinion on what's inside it.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `DashboardPanel`'s own theme file:

:theme-source{name="dashboard-panel"}

## Props

| Prop      | Type                                       | Default |
| --------- | ------------------------------------------ | ------- |
| `minSize` | `number`                                   | `30`    |
| `ui`      | `Partial<Record<'root', string | object>>` | -       |


# DashboardResizeHandle

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardGroup>
  <SDashboardSidebar>...</SDashboardSidebar>
  <SDashboardResizeHandle />
  <SDashboardPanel>...</SDashboardPanel>
</SDashboardGroup>
```

Placed between [DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) and
[DashboardPanel](https://selarasui.my.id/composites/dashboard/dashboard-panel), both direct children of
[DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) - a thin wrapper around
[SplitterResizeHandle](https://selarasui.my.id/components/layout/splitter) (`direction="horizontal"`
fixed, since a dashboard shell only ever splits left/right). Its transparent
8px hit area overlaps the boundary without taking up layout space or assuming
either panel’s background. A thin border is visible by default, with an accent
color on hover, while dragging, or on keyboard focus. It also adds the mobile check: renders nothing below `mobileBreakpoint` - there's
nothing to drag once the sidebar isn't part of a split layout at all, see
[DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group)'s own "Mobile" section.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `DashboardResizeHandle`'s own theme file:

:theme-source{name="dashboard-resize-handle"}

The `root` slot controls the hit area; `line` controls the visible divider. For
example, hide the divider at rest and reveal it during interaction:

```vue-html
<SDashboardResizeHandle :ui="{ line: 'opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100 group-data-[state=drag]:opacity-100' }" />
```

DashboardPanel remains transparent, so your page or panel background continues
to show through. The standalone SplitterResizeHandle retains its own defaults.

## Props

| Prop | Type                                                         | Default |
| ---- | ------------------------------------------------------------ | ------- |
| `ui` | `Partial<Record<SplitterResizeHandleSlot, string | object>>` | -       |


# DashboardSidebar

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardSidebar :default-size="260" :min-size="200" :max-size="400">
  <template #header="{ isCollapsed }">
    {{ isCollapsed ? 'A' : 'Acme Inc' }}
  </template>
  <template #default="{ isCollapsed }">
    <nav>
      <a href="/">
        <Icon name="..." />
        <span v-if="!isCollapsed">Dashboard</span>
      </a>
    </nav>
  </template>
  <template #footer>...</template>
</SDashboardSidebar>
```

Must be a direct child of [DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) -
see its own page for the resize/collapse/persistence/mobile-drawer behavior,
all shared across the whole shell rather than owned by the sidebar alone.
`header`/default/`footer` mirror [PageAside](https://selarasui.my.id/composites/documentation/page-aside)'s
own slot shape - default content scrolls (via
[ScrollArea](https://selarasui.my.id/components/layout/scroll-area)) independently of the fixed
header/footer.

On desktop, a themed [SplitterPanel](https://selarasui.my.id/components/layout/splitter)
(collapsible, `minSize`/`maxSize`/`defaultSize` passed straight through);
below `mobileBreakpoint`, the same content renders inside a
[Drawer](https://selarasui.my.id/components/overlays/drawer) instead. Sizes are pixels by default
(`sizeUnit="px"`) rather than `SplitterPanel`'s own percentage default - a
sidebar's width reads more naturally in pixels than as a fraction of
however wide the page happens to be.

## Control collapse from outside

Bind `v-model:collapsed` to set the desktop rail state and receive updates from
resizing or `DashboardSidebarToggle`. An explicit value takes precedence over
saved collapse state. Omit it to keep the existing uncontrolled sizing and persistence.


```vue
<script setup lang="ts">
const collapsed = ref(false)
</script>

<template>
  <div class="h-80 overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="dashboard-controlled-example">
      <SDashboardSidebar v-model:collapsed="collapsed">
        <template #header="{ isCollapsed }">
          {{ isCollapsed ? 'A' : 'Acme Inc' }}
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="[{ label: 'Overview', icon: 'hugeicons:dashboard-square-01' }]" orientation="vertical" :collapsed="isCollapsed" tooltip />
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar title="Controlled sidebar" />
        <div class="p-4">
          <SButton variant="outline" @click="collapsed = !collapsed">
            {{ collapsed ? 'Expand sidebar' : 'Collapse sidebar' }}
          </SButton>
        </div>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardSidebar v-model:collapsed="collapsed" />
```

A component ref also exposes `collapse()`, `expand()`, `toggle()`, and
`isCollapsed`. `collapse()` and `expand()` operate on the desktop panel and restore
its previous expanded width. They do nothing on mobile or when `collapsible` is
`false`. `toggle()` retains the normal mobile drawer behavior. The `collapsed`
model does not control the mobile drawer; its value is applied when returning to desktop.
Use the model to capture the user's current choice before temporarily collapsing
for a page, then restore that choice when leaving.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `DashboardSidebar`'s own theme file:

:theme-source{name="dashboard-sidebar"}

## Props

| Prop            | Type                                                     | Default |
| --------------- | -------------------------------------------------------- | ------- |
| `collapsed`     | `boolean`                                                | -       |
| `defaultSize`   | `number`                                                 | `260`   |
| `minSize`       | `number`                                                 | `200`   |
| `maxSize`       | `number`                                                 | `400`   |
| `collapsedSize` | `number`                                                 | `64`    |
| `collapsible`   | `boolean`                                                | `true`  |
| `sizeUnit`      | `'px' | '%'`                                             | `'px'`  |
| `ui`            | `Partial<Record<DashboardSidebarSlot, string | object>>` | -       |

## Slots

| Slot     | Props             | Description                                                    |
| -------- | ----------------- | -------------------------------------------------------------- |
| `header` | `{ isCollapsed }` | Fixed content above the scrollable body (a logo, a brand name) |
| default  | `{ isCollapsed }` | Scrollable body content (typically a nav tree)                 |
| `footer` | `{ isCollapsed }` | Fixed content below the scrollable body (a user menu)          |

`isCollapsed` is always `false` on mobile, where there's no in-between state -
just the drawer open or closed. Use it to swap a header's logo to a narrower
mark, or hide a nav item's label text, once the sidebar collapses to its icon
rail - the live example above does both, along with hiding the footer's name
next to the avatar.

## Events

| Event              | Payload   | Description                                                                         |
| ------------------ | --------- | ----------------------------------------------------------------------------------- |
| `update:collapsed` | `boolean` | Desktop collapse state changed through resizing, the toggle, or a component method. |


# DashboardSidebarToggle

## Usage


```vue
<script setup lang="ts">
const active = ref('Overview')

function link(label: string, icon?: string) {
  return { label, icon, active: active.value === label, onSelect: () => (active.value = label) }
}

// A deliberate mix of icon presence at every level (a leaf with/without
// its own icon, a parent with/without one, a 3rd-level group under a
// 2nd-level one) - every row's label still lands at the same x position
// regardless, the whole point of linkIconWrapper's fixed-width reservation.
const links = computed(() => [
  link('Overview', 'hugeicons:dashboard-square-01'),
  {
    label: 'Analytics',
    icon: 'hugeicons:chart-line-data-01',
    children: [
      link('Traffic', 'hugeicons:chart-line-data-01'),
      link('Conversion'),
      {
        label: 'Reports',
        icon: 'hugeicons:file-01',
        children: [link('Daily'), link('Weekly', 'hugeicons:calendar-01')],
      },
    ],
  },
  link('Customers', 'hugeicons:user-group'),
  {
    label: 'Settings',
    children: [link('General', 'hugeicons:settings-01'), link('Billing')],
  },
])
</script>

<template>
  <div class="h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)]">
    <SDashboardGroup auto-save-id="docs-example-dashboard">
      <SDashboardSidebar>
        <template #header="{ isCollapsed }">
          <span class="font-semibold text-[var(--selaras-resolved-text-default)]">{{ isCollapsed ? 'A' : 'Acme Inc' }}</span>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="links" orientation="vertical" :collapsed="isCollapsed" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-2">
            <SAvatar text="JD" size="sm" />
            <span v-if="!isCollapsed" class="text-sm text-[var(--selaras-resolved-text-muted)]">Jane Doe</span>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="active">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SButton size="sm" icon="hugeicons:plus-sign">
            New
          </SButton>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
          <p>
            Drag the divider to resize the sidebar, or use the navbar's
            toggle button to collapse it down to an icon rail. Shrink the
            browser window to see it switch to a drawer instead.
          </p>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
  </div>
</template>
```


```vue-html
<SDashboardNavbar title="Overview">
  <template #leading>
    <SDashboardSidebarToggle />
  </template>
</SDashboardNavbar>
```

Nothing renders it for you - drop it into
[DashboardNavbar](https://selarasui.my.id/composites/dashboard/dashboard-navbar)'s `leading` slot
(the common case, shown above), or anywhere else inside the same
[DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) that makes sense for a
given layout - inside [DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar)'s
own header instead of the navbar, say, or a custom toolbar.

Renders nothing until there's an actual sibling
[DashboardSidebar](https://selarasui.my.id/composites/dashboard/dashboard-sidebar) in the same
[DashboardGroup](https://selarasui.my.id/composites/dashboard/dashboard-group) to control.

### Replacing the button entirely

The default slot hands a fully custom trigger the same `toggle` function
and `isCollapsed` state the built-in Button uses internally, rather than
just swapping props on it:

```vue-html
<SDashboardSidebarToggle v-slot="{ toggle, isCollapsed, attrs }">
  <button v-bind="attrs" type="button" @click="toggle">
    {{ isCollapsed ? 'Show' : 'Hide' }} sidebar
  </button>
</SDashboardSidebarToggle>
```

### Customizing the icon or button

A thin wrapper around [Button](https://selarasui.my.id/components/elements/button) - `icon` swaps
the glyph, and anything else Button accepts (`color`, `variant`, `size`,
`ui`, ...) passes straight through:

```vue-html
<SDashboardSidebarToggle icon="lucide:menu" color="primary" variant="soft" />
```

The default icon (`hugeicons:sidebar-left-01`) mirrors horizontally once
the sidebar collapses, rather than swapping to a second icon - a custom
`icon` gets the same treatment, so pick one that still reads correctly
flipped.

## Props

| Prop   | Type     | Default                |
| ------ | -------- | ---------------------- |
| `icon` | `string` | `sidebarCollapse` icon |

## Slots

| Slot    | Description                                                                                                                 |
| ------- | --------------------------------------------------------------------------------------------------------------------------- |
| default | Replaces the themed Button entirely - scoped to `{ toggle, isCollapsed, attrs }`; bind `attrs` to forward caller attributes |


# ContentNavigation

## Usage


```vue
<script setup lang="ts">
const navigation = [
  { title: 'Getting Started', path: '/' },
  { title: 'Forms', path: '/components/forms', children: [
    { title: 'Input', path: '/components/forms/input' },
    { title: 'Select', path: '/components/forms/select' },
  ] },
]
</script>

<template>
  <SContentNavigation :navigation="navigation" class="w-56" />
</template>
```


```vue-html
<SContentNavigation :navigation="navigation" />
```

`navigation` is a plain array shaped `{ title, path, children? }[]` - the same
shape `@nuxt/content`'s `queryCollectionNavigation()` returns, so you can pass
its result straight through with no adapter. This library has no hard
dependency on `@nuxt/content` though - hand-build the array yourself if you
don't use it.

The current route's exact path is highlighted. Groups with children render
as an [Accordion](https://selarasui.my.id/components/navigation/accordion) item internally
(`type="multiple"`, so several sections can stay open at once, and every
group starts open by default) rather than a hand-rolled toggle.

This docs site's own left sidebar is exactly this component, fed
`queryCollectionNavigation('docs').order('order', 'ASC')`. It's normally
wrapped in a [PageAside](https://selarasui.my.id/composites/documentation/page-aside) rather than used
bare, which supplies the sticky positioning and scrollable rail chrome - see
[PageHeader](https://selarasui.my.id/composites/documentation/page-header)'s "Assembling a full page
layout" section for how it and [ContentToc](https://selarasui.my.id/composites/documentation/content-toc)
fit together with the rest of a page.

A `path` starting with `http://`/`https://` renders as a real external link
automatically - that's `NuxtLink`'s own default behavior, nothing to opt into.

### Icons

Give a link (or a group) an `icon` and it renders before the title
automatically:


```vue
<script setup lang="ts">
const navigation = [
  { title: 'Getting Started', path: '/', icon: 'hugeicons:rocket-01' },
  { title: 'Forms', path: '/components/forms', icon: 'hugeicons:folder-01', children: [
    { title: 'Input', path: '/components/forms/input' },
    { title: 'Select', path: '/components/forms/select' },
  ] },
]
</script>

<template>
  <SContentNavigation :navigation="navigation" class="w-56" />
</template>
```


```vue-html
<SContentNavigation
  :navigation="[
    { title: 'Getting Started', path: '/', icon: 'hugeicons:rocket-01' },
    { title: 'Forms', path: '/components/forms', icon: 'hugeicons:folder-01', children: [...] },
  ]"
/>
```

### Custom link content

The `link` slot replaces a link's (or a group header's) title content -
scoped with `link` and `active` (always `false` for a group header, since
that only ever describes a leaf link's own exact path):


```vue
<script setup lang="ts">
const navigation = [
  { title: 'Getting Started', path: '/' },
  { title: 'Forms', path: '/components/forms', children: [
    { title: 'Input', path: '/components/forms/input' },
    { title: 'Textarea', path: '/components/forms/textarea' },
  ] },
]
</script>

<template>
  <SContentNavigation :navigation="navigation" class="w-56">
    <template #link="{ link }">
      <span class="flex flex-1 items-center justify-between gap-2">
        {{ link.title }}
        <SBadge v-if="link.path === '/components/forms/textarea'" label="New" color="primary" size="sm" />
      </span>
    </template>
  </SContentNavigation>
</template>
```


```vue-html
<SContentNavigation :navigation="navigation">
  <template #link="{ link }">
    <span class="flex flex-1 items-center justify-between gap-2">
      {{ link.title }}
      <SBadge v-if="link.path === '/components/forms/textarea'" label="New" color="primary" size="sm" />
    </span>
  </template>
</SContentNavigation>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `ContentNavigation`'s own theme file:

Global and scoped theme recipes use `ui.contentNavigation`. Its group slots
adapt the nested Accordion layout while `ui.accordion` and `ui.icon` remain
independent primitive recipes.

:theme-source{name="content-navigation"}

### Accessibility

The active link gets `aria-current="page"` automatically - `NuxtLink`'s own
default behavior for whichever link matches the current route, not
something this component sets itself. Expand/collapse keyboard behavior
for groups comes from the same [Accordion](https://selarasui.my.id/components/navigation/accordion)
primitive used internally - see its own Accessibility section for details.

## Props

| Prop         | Type                                                                 | Default      |
| ------------ | -------------------------------------------------------------------- | ------------ |
| `navigation` | `{ title: string, path: string, icon?: string, children?: [...] }[]` | - (required) |
| `ui`         | `Partial<Record<ContentNavigationSlot, string | object>>`            | -            |

## Slots

| Slot   | Props              | Description                                         |
| ------ | ------------------ | --------------------------------------------------- |
| `link` | `{ link, active }` | Replaces a link's (or group header's) title content |


# ContentSurround

## Usage

```vue-html
<SContentSurround
  :prev="{ title: 'Installation', path: '/overview/getting-started/installation' }"
  :next="{ title: 'Theming', path: '/overview/theming/overview' }"
/>
```


```vue
<template>
  <SContentSurround
    :prev="{ title: 'Installation', path: '#' }"
    :next="{ title: 'Theming', path: '#' }"
  />
</template>
```


Pass only `prev`, only `next`, or neither - `SContentSurround` renders
nothing at all when both are omitted (the first and last page in a
collection have no counterpart on one side). This docs site sources both
from a content collection's own surrounding-page query (e.g.
`queryCollectionItemSurroundings` from `@nuxt/content`), not typed in by
hand - see this page's own "Previous"/"Next" links at the bottom for a live
example.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `ContentSurround`'s own theme file:

Global and scoped theme recipes use `ui.contentSurround`.

:theme-source{name="content-surround"}

## Props

| Prop   | Type                                                                             | Default |
| ------ | -------------------------------------------------------------------------------- | ------- |
| `prev` | `{ title: string, path: string }`                                                | -       |
| `next` | `{ title: string, path: string }`                                                | -       |
| `ui`   | `Partial<Record<'root' | 'link' | 'label' | 'icon' | 'title', string | object>>` | -       |


# ContentToc

## Usage


```vue
<script setup lang="ts">
const links = [
  { id: 'usage', text: 'Usage', depth: 2 },
  { id: 'props', text: 'Props', depth: 2 },
]
</script>

<template>
  <SContentToc :links="links" class="w-48" />
</template>
```


```vue-html
<SContentToc :links="page.body.toc.links" />
```

`links` matches `@nuxt/content`'s `page.body.toc.links` shape directly
(`{ id, text, depth, children? }[]`) - pass it straight through, no adapter
needed. As with [ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation), there's
no hard dependency on `@nuxt/content` - build the array yourself if you don't
use it.

It's normally wrapped in a [PageAside](https://selarasui.my.id/composites/documentation/page-aside)
rather than used bare, which supplies the sticky positioning and scrollable
rail chrome - see [PageHeader](https://selarasui.my.id/composites/documentation/page-header)'s
"Assembling a full page layout" section for how it and
[ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation) fit together
with the rest of a page.

The active heading(s) are tracked by comparing scroll position against
each heading's own content range (from its position down to the next
heading's, or to the end of the document for the last one) - not a single
fixed trigger point, which is why more than one can be active at once
(short adjacent sections both overlapping the trigger band) and why the
very last section always eventually lights up regardless of how little
content it has, even once you've scrolled as far as the page allows.

Active heading(s) are shown on a zigzag rail to the left of the list - a
continuous "wire" connecting every heading, bending inward at each depth
change, with the active stretch(es) lit up in the primary color. Try
scrolling this very page and watching the right-hand rail. The rail is
drawn as an SVG path applied as a CSS mask (not painted directly), so the
same curve shape works for both the always-visible faint track and the
primary-colored active overlay - no JS animation library involved, just a
CSS `transition` on the overlay's position/size, the same "CSS-only
animation" constraint every other component in this library follows.

### Custom link content

The `link` slot replaces a link's plain-text content - scoped with `link`
and `active`, so a single template can react to whichever section is
currently being read:


```vue
<script setup lang="ts">
const links = [
  { id: 'usage', text: 'Usage', depth: 2 },
  { id: 'props', text: 'Props', depth: 2, children: [
    { id: 'slots', text: 'Slots', depth: 3 },
  ] },
]
</script>

<template>
  <SContentToc :links="links" class="w-48">
    <template #link="{ link, active }">
      <span class="flex items-center gap-2">
        {{ link.text }}
        <SBadge v-if="active" label="Reading" color="primary" size="sm" />
      </span>
    </template>
  </SContentToc>
</template>
```


```vue-html
<SContentToc :links="links">
  <template #link="{ link, active }">
    <span class="flex items-center gap-2">
      {{ link.text }}
      <SBadge v-if="active" label="Reading" color="primary" size="sm" />
    </span>
  </template>
</SContentToc>
```

### Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `ContentToc`'s own theme file:

Global and scoped theme recipes use `ui.contentToc`.

:theme-source{name="content-toc"}

### Accessibility

The active link(s) get `aria-current="location"` - the WAI-ARIA token for
"the current location within an environment," matching a table of
contents specifically (not `"page"`, which is for pagination). The rail
itself is purely decorative (`aria-hidden`) - it's a sighted-only visual
echo of what `aria-current` already conveys on the real links, not a
separate source of information.

## Props

| Prop    | Type                                                              | Default          |
| ------- | ----------------------------------------------------------------- | ---------------- |
| `links` | `{ id: string, text: string, depth: number, children?: [...] }[]` | - (required)     |
| `title` | `string`                                                          | `'On this page'` |
| `ui`    | `Partial<Record<ContentTocSlot, string | object>>`                | -                |

## Slots

| Slot    | Props              | Description                                  |
| ------- | ------------------ | -------------------------------------------- |
| `title` | -                  | Custom title content, overrides `title` prop |
| `link`  | `{ link, active }` | Replaces a link's content                    |


# PageAside

## Usage


```vue
<template>
  <div class="flex h-64 w-full rounded-[var(--selaras-resolved-radius-md)] ring-1 ring-[var(--selaras-resolved-border-default)]">
    <SPageAside :ui="{ root: 'static flex h-full w-48' }">
      <template #header>
        <strong class="text-sm">Header</strong>
      </template>
      <div v-for="i in 20" :key="i" class="py-1 text-sm">
        Item {{ i }}
      </div>
    </SPageAside>
    <div class="flex-1 p-4 text-sm text-[var(--selaras-resolved-text-muted)]">
      Main content sits alongside the aside.
    </div>
  </div>
</template>
```


```vue-html
<SPageAside>
  <template #header>
    <strong>Header</strong>
  </template>
  <SContentNavigation :navigation="navigation" />
</SPageAside>
```

By default `SPageAside` is `sticky` and fills the viewport height (`h-screen`) -
meant to sit directly inside a page-level flex row, like this docs site's own
layout does for both the left nav and right [ContentToc](https://selarasui.my.id/composites/documentation/content-toc)
rail. The example above overrides `root` via the `ui` prop to a fixed height
so it fits inline in these docs.

It's also hidden below the `lg` breakpoint by default - a fixed-width rail
alongside the main content column has nowhere to go on a narrow viewport.
This docs site's own right-hand ToC rail simply disappears there; its left
nav instead surfaces through a Drawer triggered from the header, since
unlike the ToC it still needs to be reachable on mobile.

Scrolling is handled by a themed [ScrollArea](https://selarasui.my.id/components/layout/scroll-area)
internally, not a plain `overflow-y-auto` div - so scrollbar styling stays
consistent with the rest of the library.

Typically wraps a [ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation)
(left nav) or a [ContentToc](https://selarasui.my.id/composites/documentation/content-toc) (right rail) -
see [PageHeader](https://selarasui.my.id/composites/documentation/page-header)'s "Assembling a full page
layout" section for how all three combine with a main content column into
one page.

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `PageAside`'s own theme file:

Global and scoped theme recipes use `ui.pageAside`. Its `scrollArea` slot is
the layout override for the composed scroll region; `ui.scrollArea` still
configures `SScrollArea` independently.

:theme-source{name="page-aside"}

## Props

| Prop | Type                                              | Default |
| ---- | ------------------------------------------------- | ------- |
| `ui` | `Partial<Record<PageAsideSlot, string | object>>` | -       |

## Slots

| Slot     | Description                             |
| -------- | --------------------------------------- |
| `header` | Fixed content above the scrollable body |
| default  | Scrollable body content                 |


# PageHeader

## Usage


```vue
<template>
  <SPageHeader title="Component name" description="A one-line summary of what this component does." />
</template>
```


```vue-html
<SPageHeader title="Component name" description="A one-line summary." />
```

This docs site uses it on every component page (via
`page.title`/`page.description` from frontmatter), fixing a gap where those
fields previously went completely unused.

## Assembling a full page layout

`PageHeader` is only the top of the main content column - this docs site
wraps four components together into the full page shell you're reading right
now: a left [PageAside](https://selarasui.my.id/composites/documentation/page-aside) wrapping a
[ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation) for the section
nav, a main column starting with `PageHeader` and followed by the actual
page content, and a right `PageAside` wrapping a
[ContentToc](https://selarasui.my.id/composites/documentation/content-toc) for the "on this page" rail.
The Selaras docs application uses this same arrangement, with a responsive
drawer for the navigation on smaller screens.


```vue
<script setup lang="ts">
// A simplified stand-in for how this docs site itself assembles all four
// components into one page layout: a left PageAside wrapping a
// ContentNavigation, a main column with a PageHeader on top, and a right
// PageAside wrapping a ContentToc, all in one flex row.
// Real, existing routes on this docs site - not just placeholders, so the
// static build's own prerender crawler (which follows every rendered
// NuxtLink) can actually resolve them instead of 404ing.
const navigation = [
  { title: 'Guide', path: '/overview', children: [
    { title: 'Introduction', path: '/overview/getting-started/introduction' },
    { title: 'Installation', path: '/overview/getting-started/installation' },
  ] },
  { title: 'Components', path: '/components', children: [
    { title: 'Button', path: '/components/elements/button' },
    { title: 'Card', path: '/components/layout/card' },
  ] },
]

// Prefixed so these never collide with this very page's own heading ids
// (`#usage`, `#props`, ...) once this example is embedded inline below them.
const tocLinks = [
  { id: 'demo-overview', text: 'Overview', depth: 2 },
  { id: 'demo-usage', text: 'Usage', depth: 2 },
  { id: 'demo-props', text: 'Props', depth: 2 },
]
</script>

<template>
  <div class="flex h-96 w-full overflow-hidden rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)] text-sm">
    <SPageAside :ui="{ root: 'static flex h-full w-40 shrink-0' }">
      <SContentNavigation :navigation="navigation" />
    </SPageAside>
    <main class="min-w-0 flex-1 overflow-y-auto p-6">
      <SPageHeader title="Button" description="A clickable trigger for an action." />
      <div id="demo-overview" class="pt-4 text-[var(--selaras-resolved-text-muted)]">
        A short introduction to the component would go here.
      </div>
      <div id="demo-usage" class="pt-8 text-[var(--selaras-resolved-text-muted)]">
        A live example and a usage snippet would go here.
      </div>
      <div id="demo-props" class="pt-8 text-[var(--selaras-resolved-text-muted)]">
        A Props table would go here.
      </div>
    </main>
    <SPageAside :ui="{ root: 'static flex h-full w-40 shrink-0' }">
      <SContentToc :links="tocLinks" />
    </SPageAside>
  </div>
</template>
```


```vue-html
<div class="flex">
  <SPageAside>
    <SContentNavigation :navigation="navigation" />
  </SPageAside>
  <main class="min-w-0 flex-1">
    <SPageHeader :title="page.title" :description="page.description" />
    <!-- page content -->
  </main>
  <SPageAside>
    <SContentToc :links="page.body.toc.links" />
  </SPageAside>
</div>
```

See also [PageAside](https://selarasui.my.id/composites/documentation/page-aside),
[ContentNavigation](https://selarasui.my.id/composites/documentation/content-navigation) and
[ContentToc](https://selarasui.my.id/composites/documentation/content-toc).

## Custom `:ui`

To see exactly what you'd be overriding - the current default classes for
every slot - here's `PageHeader`'s own theme file:

:theme-source{name="page-header"}

## Props

| Prop          | Type                                               | Default |
| ------------- | -------------------------------------------------- | ------- |
| `title`       | `string`                                           | -       |
| `description` | `string`                                           | -       |
| `ui`          | `Partial<Record<PageHeaderSlot, string | object>>` | -       |

## Slots

| Slot          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `title`       | Custom title content, overrides `title` prop             |
| `description` | Custom description content, overrides `description` prop |
| default       | Extra content below the description                      |


# Dashboard overview


```vue
<script setup lang="ts">
interface Project {
  name: string
  owner: string
  initials: string
  completed: number
  tasks: number
  due: string
  status: 'On track' | 'Needs review'
  next: string
}
const view = ref('Overview')
const sidebar = useTemplateRef('sidebar')
function navigate(label: string) {
  view.value = label
  if (window.matchMedia('(max-width: 767px)').matches)
    sidebar.value?.toggle()
}
const selected = ref<Project>()
const detailsOpen = ref(false)
const projects: Project[] = [
  { name: 'Website refresh', owner: 'Dina Sari', initials: 'DS', completed: 18, tasks: 24, due: 'Oct 24', status: 'On track', next: 'Review the responsive layouts with the team.' },
  { name: 'Customer onboarding', owner: 'Alex Morgan', initials: 'AM', completed: 8, tasks: 16, due: 'Oct 28', status: 'Needs review', next: 'Resolve feedback on the welcome flow.' },
  { name: 'Component audit', owner: 'Rafi Putra', initials: 'RP', completed: 21, tasks: 28, due: 'Nov 02', status: 'On track', next: 'Check keyboard interactions and field labels.' },
  { name: 'Help center', owner: 'Nadia Chen', initials: 'NC', completed: 6, tasks: 20, due: 'Nov 08', status: 'On track', next: 'Draft the first five getting-started articles.' },
]
const activity = [
  { person: 'Dina Sari', initials: 'DS', action: 'completed the homepage layout', project: 'Website refresh', time: '12 minutes ago' },
  { person: 'Alex Morgan', initials: 'AM', action: 'requested a design review', project: 'Customer onboarding', time: '38 minutes ago' },
  { person: 'Rafi Putra', initials: 'RP', action: 'added keyboard testing notes', project: 'Component audit', time: '1 hour ago' },
]
const completed = projects.reduce((sum, project) => sum + project.completed, 0)
const total = projects.reduce((sum, project) => sum + project.tasks, 0)
const navigation = computed(() => [
  { label: 'Workspace', type: 'label' as const },
  ...[
    ['Overview', 'hugeicons:dashboard-square-01'],
    ['Projects', 'hugeicons:folder-01'],
    ['Activity', 'hugeicons:clock-01'],
  ].map(([label, icon]) => ({ label: label!, icon, active: view.value === label, onSelect: () => navigate(label!) })),
])

function showProject(project: Project) {
  selected.value = project
  detailsOpen.value = true
}
</script>

<template>
  <div class="h-screen bg-[var(--selaras-resolved-surface-default)] text-[var(--selaras-resolved-text-default)]">
    <SDashboardGroup auto-save-id="selaras-block-workspace">
      <SDashboardSidebar ref="sidebar" :default-size="220">
        <template #header="{ isCollapsed }">
          <div class="flex items-center gap-2 font-semibold">
            <SIcon name="hugeicons:layers-01" class="size-6 shrink-0 text-[var(--selaras-resolved-color-primary-text)]" />
            <span v-if="!isCollapsed">Studio</span>
          </div>
        </template>
        <template #default="{ isCollapsed }">
          <SNavigationMenu :items="navigation" orientation="vertical" :collapsed="isCollapsed" :ui="{ link: isCollapsed ? undefined : 'w-full text-start' }" />
        </template>
        <template #footer="{ isCollapsed }">
          <div class="flex items-center gap-3">
            <SAvatar text="DS" size="sm" />
            <div v-if="!isCollapsed" class="min-w-0 text-sm">
              <p class="font-medium">
                Dina Sari
              </p>
              <p class="text-xs text-[var(--selaras-resolved-text-muted)]">
                Demo workspace
              </p>
            </div>
          </div>
        </template>
      </SDashboardSidebar>
      <SDashboardResizeHandle />
      <SDashboardPanel>
        <SDashboardNavbar :title="view">
          <template #leading>
            <SDashboardSidebarToggle />
          </template>
          <SBadge color="neutral" variant="soft">
            Sample data
          </SBadge>
        </SDashboardNavbar>
        <main class="flex-1 overflow-y-auto p-5 sm:p-7">
          <h1 class="text-2xl font-semibold tracking-tight">
            {{ view === 'Overview' ? 'A clear view of your work' : view === 'Projects' ? 'Workspace projects' : 'Recent activity' }}
          </h1>
          <p class="mt-2 text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
            {{ view === 'Activity' ? 'The latest updates from your team. All activity shown is illustrative.' : 'Four projects, one shared workspace. Select a project to see its next step.' }}
          </p>
          <dl v-if="view === 'Overview'" class="my-7 grid grid-cols-2 gap-5 border-y border-[var(--selaras-resolved-border-default)] py-5 sm:grid-cols-3">
            <div>
              <dt class="text-sm text-[var(--selaras-resolved-text-muted)]">
                Active projects
              </dt>
              <dd class="mt-2 text-3xl font-semibold tabular-nums">
                {{ projects.length }}
              </dd>
            </div>
            <div>
              <dt class="text-sm text-[var(--selaras-resolved-text-muted)]">
                Completed tasks
              </dt>
              <dd class="mt-2 text-3xl font-semibold tabular-nums">
                {{ completed }}<span class="ms-1 text-base font-normal text-[var(--selaras-resolved-text-muted)]">/ {{ total }}</span>
              </dd>
            </div>
            <div>
              <dt class="text-sm text-[var(--selaras-resolved-text-muted)]">
                Needs review
              </dt>
              <dd class="mt-2 text-3xl font-semibold tabular-nums">
                {{ projects.filter(project => project.status === 'Needs review').length }}
              </dd>
            </div>
          </dl>
          <section v-if="view !== 'Activity'" class="mt-7" aria-labelledby="projects-title">
            <div class="mb-3 flex items-center justify-between gap-3">
              <h2 id="projects-title" class="font-semibold">
                Projects
              </h2>
              <SButton v-if="view === 'Overview'" variant="link" size="sm" @click="view = 'Projects'">
                View all projects
              </SButton>
            </div>
            <STable :data="projects" row-hover>
              <SColumn field="name" header="Project">
                <template #default="{ row }">
                  <SButton variant="link" color="neutral" class="justify-start px-0 text-start" @click="showProject(row)">
                    {{ row.name }}
                  </SButton>
                  <p class="text-xs text-[var(--selaras-resolved-text-muted)]">
                    {{ row.owner }}
                  </p>
                </template>
              </SColumn>
              <SColumn field="completed" header="Progress">
                <template #default="{ row }">
                  <div class="min-w-24 space-y-2">
                    <p class="text-xs tabular-nums">
                      {{ row.completed }} / {{ row.tasks }} tasks
                    </p>
                    <SProgress :model-value="row.completed" :max="row.tasks" :aria-label="`${row.name} task progress`" size="sm" />
                  </div>
                </template>
              </SColumn>
              <SColumn field="status" header="Status">
                <template #default="{ row }">
                  <SBadge :color="row.status === 'On track' ? 'success' : 'warning'" variant="soft" class="whitespace-nowrap">
                    {{ row.status }}
                  </SBadge>
                </template>
              </SColumn>
            </STable>
          </section>
          <section v-if="view !== 'Projects'" class="mt-8" aria-labelledby="activity-title">
            <h2 id="activity-title" class="mb-4 font-semibold">
              Recent activity
            </h2>
            <ul class="divide-y divide-[var(--selaras-resolved-border-default)]">
              <li v-for="item in activity" :key="item.person" class="flex items-start gap-3 py-4 first:pt-0">
                <SAvatar :text="item.initials" size="sm" />
                <div class="min-w-0 flex-1 text-sm leading-6">
                  <p><span class="font-medium">{{ item.person }}</span> {{ item.action }}.</p>
                  <p class="text-xs text-[var(--selaras-resolved-text-muted)]">
                    {{ item.project }} · {{ item.time }}
                  </p>
                </div>
              </li>
            </ul>
          </section>
        </main>
      </SDashboardPanel>
    </SDashboardGroup>
    <SSlideover v-model:open="detailsOpen" :title="selected?.name ?? 'Project details'" description="Project details · sample data">
      <template #body>
        <div v-if="selected" class="space-y-6">
          <div class="flex items-center gap-3">
            <SAvatar :text="selected.initials" /><div>
              <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
                Project owner
              </p><p class="font-medium">
                {{ selected.owner }}
              </p>
            </div>
          </div>
          <SBadge :color="selected.status === 'On track' ? 'success' : 'warning'" variant="soft">
            {{ selected.status }}
          </SBadge>
          <div>
            <h2 class="mb-2 font-semibold">
              Next step
            </h2><p class="text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
              {{ selected.next }}
            </p>
          </div>
          <div>
            <p class="mb-2 text-sm">
              {{ selected.completed }} of {{ selected.tasks }} tasks complete
            </p><SProgress :model-value="selected.completed" :max="selected.tasks" aria-label="Completed tasks" />
          </div>
          <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
            Target date: {{ selected.due }} · illustrative schedule
          </p>
        </div>
      </template>
    </SSlideover>
  </div>
</template>
```



# Data management


```vue
<script setup lang="ts">
interface Member {
  id: string
  name: string
  email: string
  role: string
  status: string
}
const sampleMembers: Member[] = [
  { id: '1', name: 'Dina Sari', email: 'dina@example.com', role: 'Admin', status: 'Active' },
  { id: '2', name: 'Alex Morgan', email: 'alex@example.com', role: 'Member', status: 'Active' },
  { id: '3', name: 'Rafi Putra', email: 'rafi@example.com', role: 'Member', status: 'Active' },
  { id: '4', name: 'Nadia Chen', email: 'nadia@example.com', role: 'Viewer', status: 'Invited' },
  { id: '5', name: 'Jamie Park', email: 'jamie@example.com', role: 'Member', status: 'Active' },
  { id: '6', name: 'Sasha Lee', email: 'sasha@example.com', role: 'Viewer', status: 'Active' },
  { id: '7', name: 'Mika Tan', email: 'mika@example.com', role: 'Admin', status: 'Active' },
  { id: '8', name: 'Ari Santos', email: 'ari@example.com', role: 'Viewer', status: 'Invited' },
]
const members = ref(sampleMembers.map(member => ({ ...member })))
const search = ref('')
const roles: string[] = ['Admin', 'Member', 'Viewer']
const roleFilters = ['All roles', ...roles]
const statuses: string[] = ['Invited', 'Active']
const role = ref('All roles')
const pageIndex = ref(0)
const editorOpen = ref(false)
const editingId = ref<string>()
const form = reactive({ name: '', email: '', role: 'Member', status: 'Invited' })
const pending = ref(false)
const loading = ref(false)
const feedback = ref('')
const formError = ref('')
let nextId = 9
const filtered = computed(() => members.value.filter((member) => {
  const term = search.value.trim().toLowerCase()
  return (role.value === 'All roles' || member.role === role.value)
    && (!term || `${member.name} ${member.email}`.toLowerCase().includes(term))
}))
watch([search, role], () => pageIndex.value = 0)

function edit(member?: Member) {
  editingId.value = member?.id
  Object.assign(form, member ?? { name: '', email: '', role: 'Member', status: 'Invited' })
  formError.value = ''
  editorOpen.value = true
}

async function save() {
  formError.value = ''
  if (members.value.some(member => member.id !== editingId.value && member.email.toLowerCase() === form.email.trim().toLowerCase())) {
    formError.value = 'A member already uses this email address. Enter a different address.'
    return
  }
  pending.value = true
  try {
    // Replace this delay with your API request. Keep the editor open on failure.
    await new Promise(resolve => setTimeout(resolve, 500))
    const member: Member = { id: editingId.value ?? String(nextId++), name: form.name.trim(), email: form.email.trim(), role: form.role, status: form.status }
    members.value = editingId.value ? members.value.map(item => item.id === member.id ? member : item) : [member, ...members.value]
    search.value = ''
    role.value = 'All roles'
    pageIndex.value = 0
    feedback.value = `${member.name} ${editingId.value ? 'updated' : 'added'} in this demo. No email was sent.`
    editorOpen.value = false
  }
  catch {
    formError.value = 'The member couldn’t be saved. Please try again.'
  }
  finally {
    pending.value = false
  }
}

async function resetDemo() {
  loading.value = true
  await new Promise(resolve => setTimeout(resolve, 500))
  members.value = sampleMembers.map(member => ({ ...member }))
  search.value = ''
  role.value = 'All roles'
  pageIndex.value = 0
  nextId = 9
  feedback.value = 'Sample members restored.'
  loading.value = false
}
</script>

<template>
  <main class="min-h-screen bg-[var(--selaras-resolved-surface-default)] px-5 py-8 text-[var(--selaras-resolved-text-default)] sm:px-8">
    <div class="mx-auto max-w-5xl">
      <div class="flex flex-wrap items-start justify-between gap-4">
        <div>
          <h1 class="text-2xl font-semibold tracking-tight">
            Team members
          </h1><p class="mt-2 text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
            Manage workspace access. All members and changes are local demo data.
          </p>
        </div>
        <SButton icon="hugeicons:plus-sign" :disabled="loading" @click="edit()">
          Add member
        </SButton>
      </div>
      <div class="my-6 flex flex-wrap items-end gap-3">
        <SFormField label="Search members" class="min-w-0 flex-1 basis-52">
          <SInput v-model="search" icon="hugeicons:search-01" placeholder="Name or email…" clearable class="w-full" />
        </SFormField>
        <SFormField label="Role" class="w-40">
          <SSelect v-model="role" aria-label="Role" :items="roleFilters" class="w-full" />
        </SFormField>
        <SButton variant="outline" color="neutral" :loading="loading" :disabled="loading" @click="resetDemo">
          Reset demo
        </SButton>
      </div>
      <div role="status" aria-live="polite" class="mb-4">
        <SAlert v-if="feedback" color="success" :description="feedback" closable @close="feedback = ''" />
      </div>
      <p class="mb-3 text-sm text-[var(--selaras-resolved-text-muted)]" aria-live="polite">
        {{ filtered.length }} {{ filtered.length === 1 ? 'member' : 'members' }}{{ search || role !== 'All roles' ? ' match your filters' : ' in your workspace' }}
      </p>
      <STable v-model:page-index="pageIndex" :data="filtered" :page-size="5" :loading="loading" row-hover :get-row-id="row => row.id">
        <SColumn field="name" header="Member" sortable>
          <template #default="{ row }">
            <div class="flex items-center gap-3">
              <SAvatar :text="row.name.split(' ').map((part: string) => part[0]).slice(0, 2).join('')" size="sm" /><div>
                <p class="whitespace-nowrap font-medium">
                  {{ row.name }}
                </p><p class="text-xs text-[var(--selaras-resolved-text-muted)]">
                  {{ row.email }}
                </p>
              </div>
            </div>
          </template>
        </SColumn>
        <SColumn field="role" header="Role" sortable />
        <SColumn field="status" header="Status">
          <template #default="{ row }">
            <SBadge :color="row.status === 'Active' ? 'success' : 'warning'" variant="soft">
              {{ row.status }}
            </SBadge>
          </template>
        </SColumn>
        <SColumn field="id" header="Actions">
          <template #default="{ row }">
            <SButton icon="hugeicons:pencil-edit-02" :aria-label="`Edit ${row.name}`" variant="ghost" color="neutral" size="sm" square :disabled="loading" @click="edit(row)" />
          </template>
        </SColumn>
        <template #empty>
          <div class="py-8 text-center">
            <p class="font-medium">
              No members found
            </p><p class="mt-2 text-sm text-[var(--selaras-resolved-text-muted)]">
              Try a different name, email address or role.
            </p><SButton class="mt-4" variant="outline" color="neutral" @click="search = ''; role = 'All roles'">
              Clear filters
            </SButton>
          </div>
        </template>
      </STable>
    </div>
    <SModal v-model:open="editorOpen" :title="editingId ? 'Edit member' : 'Add member'" description="Changes apply to this demo only. No invitation emails are sent." :dismissible="!pending" :close="!pending">
      <template #body>
        <form class="space-y-5" @submit.prevent="save">
          <SFormField label="Full name" required>
            <SInput v-model="form.name" name="name" autocomplete="name" required :maxlength="80" pattern=".*\S.*" :disabled="pending" class="w-full" />
          </SFormField>
          <SFormField label="Email address" required :error="formError">
            <SInput v-model="form.email" name="email" type="email" autocomplete="email" required :disabled="pending" class="w-full" />
          </SFormField>
          <SFormField label="Member role">
            <SSelect v-model="form.role" aria-label="Member role" :items="roles" :disabled="pending" class="w-full" />
          </SFormField>
          <SFormField label="Access status">
            <SSelect v-model="form.status" aria-label="Access status" :items="statuses" :disabled="pending" class="w-full" />
          </SFormField>
          <div class="flex justify-end gap-2 pt-2">
            <SButton variant="outline" color="neutral" :disabled="pending" @click="editorOpen = false">
              Cancel
            </SButton><SButton type="submit" :loading="pending" :disabled="pending">
              Save member
            </SButton>
          </div>
        </form>
      </template>
    </SModal>
  </main>
</template>
```



# Blocks

| Block                                                                   | Includes                                                                  |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [Sign in](https://selarasui.my.id/blocks/sign-in)                       | Sign-in and password-reset forms, password visibility and pending states. |
| [Dashboard overview](https://selarasui.my.id/blocks/dashboard-overview) | Responsive workspace sidebar, projects, activity and project details.     |
| [Profile settings](https://selarasui.my.id/blocks/profile-settings)     | Profile fields, email preferences, save and reset.                        |
| [Data management](https://selarasui.my.id/blocks/data-management)       | Search, role filters, sorting, pagination and a member editor.            |

Each block has an interactive preview, device controls and copyable source.
Previews follow the selected documentation theme. All data is illustrative;
changes stay in memory and requests are simulated.

## Setup

Follow [Installation](https://selarasui.my.id/overview/getting-started/installation) in a Nuxt app,
then copy a block into `app/pages/`. **Code** includes the module, stylesheet
and `SApp` setup; **Copy Vue** copies the page. Examples use the default `S`
component prefix and Nuxt auto-imports.

For local icons, install `@iconify-json/hugeicons` as a development dependency;
see [Icons](https://selarasui.my.id/overview/getting-started/icons). No additional form or chart package
is needed. Blocks use your app's theme; documentation showcase presets are not
installed by copying their source.

Replace simulated requests with your services and enforce validation and
permissions on the server. The source comments mark integration points.
Block source is also available through [llms.txt](https://selarasui.my.id/llms.txt),
[llms-full.txt](https://selarasui.my.id/llms-full.txt), raw Markdown and the MCP catalog.


# Profile settings


```vue
<script setup lang="ts">
const timezones: string[] = ['Asia/Jakarta', 'Asia/Singapore', 'Europe/London', 'America/New_York']
const initial = {
  name: 'Dina Sari',
  email: 'dina@example.com',
  bio: 'Product designer building thoughtful tools for small teams.',
  timezone: 'Asia/Jakarta',
  updates: true,
  digest: false,
}
const saved = ref({ ...initial })
const profile = reactive({ ...initial })
const pending = ref(false)
const feedback = ref('')
const failed = ref(false)
const dirty = computed(() => JSON.stringify(profile) !== JSON.stringify(saved.value))
const initials = computed(() => profile.name.trim().split(/\s+/).slice(0, 2).map(part => part[0]).join('') || 'DS')

function reset() {
  Object.assign(profile, saved.value)
  feedback.value = ''
}

async function save() {
  pending.value = true
  feedback.value = ''
  failed.value = false
  try {
    // Replace this delay with your profile API. Save the snapshot only on success.
    await new Promise(resolve => setTimeout(resolve, 600))
    saved.value = { ...profile }
    feedback.value = 'Profile saved for this demo. Reloading restores the sample profile.'
  }
  catch {
    failed.value = true
    feedback.value = 'Your changes weren’t saved. Please try again; your edits are still here.'
  }
  finally {
    pending.value = false
  }
}
</script>

<template>
  <main class="min-h-screen bg-[var(--selaras-resolved-surface-default)] px-5 py-8 text-[var(--selaras-resolved-text-default)] sm:px-10">
    <div class="mx-auto max-w-3xl">
      <h1 class="text-2xl font-semibold tracking-tight">
        Profile settings
      </h1>
      <p class="mt-2 text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
        Manage how you appear in your workspace. This is a sample profile.
      </p>
      <form class="mt-8" @submit.prevent="save">
        <fieldset :disabled="pending" class="min-w-0 space-y-8">
          <legend class="sr-only">
            Personal information and notifications
          </legend>
          <div class="flex items-center gap-4">
            <SAvatar :text="initials" size="lg" />
            <div class="min-w-0">
              <p class="break-words font-medium">
                {{ profile.name || 'Your name' }}
              </p>
              <p class="mt-1 text-sm text-[var(--selaras-resolved-text-muted)]">
                Your initials are used as your avatar.
              </p>
            </div>
          </div>
          <div class="grid gap-5 sm:grid-cols-2">
            <SFormField label="Full name" required>
              <SInput v-model="profile.name" name="name" autocomplete="name" required :maxlength="80" class="w-full" />
            </SFormField>
            <SFormField label="Email address" required>
              <SInput v-model="profile.email" name="email" type="email" autocomplete="email" required class="w-full" />
            </SFormField>
          </div>
          <SFormField label="About you" hint="A short introduction for your teammates. Maximum 240 characters.">
            <STextarea v-model="profile.bio" name="bio" :maxlength="240" :rows="3" class="w-full" />
          </SFormField>
          <SFormField label="Time zone" hint="Used to display times in your workspace.">
            <SSelect v-model="profile.timezone" aria-label="Time zone" :items="timezones" :disabled="pending" class="w-full sm:max-w-sm" />
          </SFormField>
          <section class="border-t border-[var(--selaras-resolved-border-default)] pt-6" aria-labelledby="notifications-title">
            <h2 id="notifications-title" class="font-semibold">
              Email preferences
            </h2>
            <div class="mt-5 grid gap-5">
              <SSwitch v-model="profile.updates" label="Project updates" description="Activity on projects you follow." :disabled="pending" />
              <SSwitch v-model="profile.digest" label="Weekly digest" description="A weekly summary of your workspace." :disabled="pending" />
            </div>
          </section>
        </fieldset>
        <div class="mt-7" role="status" aria-live="polite">
          <SAlert v-if="feedback" :color="failed ? 'danger' : 'success'" :description="feedback" />
        </div>
        <div class="mt-6 flex flex-wrap items-center justify-between gap-4 border-t border-[var(--selaras-resolved-border-default)] pt-5">
          <p class="text-sm text-[var(--selaras-resolved-text-muted)]">
            {{ dirty ? 'You have unsaved changes.' : 'All changes saved.' }}
          </p>
          <div class="flex gap-2">
            <SButton variant="outline" color="neutral" :disabled="!dirty || pending" @click="reset">
              Reset
            </SButton>
            <SButton type="submit" :loading="pending" :disabled="!dirty || pending">
              Save changes
            </SButton>
          </div>
        </div>
      </form>
    </div>
  </main>
</template>
```



# Sign in


```vue
<script setup lang="ts">
const email = ref('')
const password = ref('')
const remember = ref(false)
const showPassword = ref(false)
const mode = ref<'sign-in' | 'reset'>('sign-in')
const pending = ref(false)
const feedback = ref('')
const failed = ref(false)

function changeMode(value: 'sign-in' | 'reset') {
  mode.value = value
  feedback.value = ''
  password.value = ''
}

async function submit() {
  pending.value = true
  feedback.value = ''
  failed.value = false
  try {
    // Replace this delay with your authentication or password-reset request.
    // Do not log credentials or persist passwords in browser storage.
    await new Promise(resolve => setTimeout(resolve, 600))
    feedback.value = mode.value === 'sign-in'
      ? 'Demo complete. Connect your authentication service to sign in.'
      : 'Demo complete. Connect your email service to send a reset link.'
    password.value = ''
  }
  catch {
    failed.value = true
    feedback.value = 'We couldn’t complete your request. Please try again.'
  }
  finally {
    pending.value = false
  }
}
</script>

<template>
  <main class="grid min-h-screen place-items-center bg-[var(--selaras-resolved-surface-elevated)] p-5 text-[var(--selaras-resolved-text-default)] sm:p-10">
    <SCard class="w-full max-w-md" :ui="{ body: 'p-6 sm:p-8' }">
      <div class="mb-8 flex items-center gap-3">
        <SIcon name="hugeicons:layers-01" class="size-7 text-[var(--selaras-resolved-color-primary-text)]" />
        <span class="text-lg font-semibold">Studio workspace</span>
      </div>
      <h1 class="text-2xl font-semibold tracking-tight">
        {{ mode === 'sign-in' ? 'Welcome back' : 'Reset your password' }}
      </h1>
      <p class="mt-2 text-sm leading-6 text-[var(--selaras-resolved-text-muted)]">
        {{ mode === 'sign-in' ? 'Sign in to pick up where your team left off.' : 'Enter your email to request a password reset link.' }}
      </p>
      <form class="mt-7 space-y-5" @submit.prevent="submit">
        <SFormField label="Email address" required>
          <SInput v-model="email" name="email" type="email" autocomplete="username" placeholder="you@example.com" required :disabled="pending" class="w-full" />
        </SFormField>
        <SFormField v-if="mode === 'sign-in'" label="Password" required>
          <SInput v-model="password" name="password" :type="showPassword ? 'text' : 'password'" autocomplete="current-password" :minlength="8" required :disabled="pending" class="w-full">
            <template #trailing="{ buttonSize }">
              <SButton :icon="showPassword ? 'hugeicons:view-off' : 'hugeicons:view'" :aria-label="showPassword ? 'Hide password' : 'Show password'" :aria-pressed="showPassword" :size="buttonSize" variant="ghost" color="neutral" square @click="showPassword = !showPassword" />
            </template>
          </SInput>
        </SFormField>
        <div v-if="mode === 'sign-in'" class="flex flex-wrap items-center justify-between gap-3">
          <SCheckbox v-model="remember" label="Remember me" :disabled="pending" />
          <SButton variant="link" size="sm" :disabled="pending" @click="changeMode('reset')">
            Forgot password?
          </SButton>
        </div>
        <SButton type="submit" :loading="pending" :disabled="pending" class="w-full">
          {{ mode === 'sign-in' ? 'Sign in' : 'Request reset link' }}
        </SButton>
        <SButton v-if="mode === 'reset'" variant="link" color="neutral" :disabled="pending" class="w-full" @click="changeMode('sign-in')">
          Back to sign in
        </SButton>
        <div role="status" aria-live="polite">
          <SAlert v-if="feedback" :color="failed ? 'danger' : 'info'" :description="feedback" />
        </div>
      </form>
      <p class="mt-7 border-t border-[var(--selaras-resolved-border-default)] pt-5 text-xs leading-5 text-[var(--selaras-resolved-text-muted)]">
        Interactive demo. Use made-up credentials; nothing is sent or stored. Passwords must contain at least 8 characters.
      </p>
    </SCard>
  </main>
</template>
```



# useConfirm

`useConfirm()` opens the library's accessible `<SAlertDialog>` and resolves a
boolean. Use it when the action needs a yes/no decision but should not own a
dialog and its state in the template.

## Usage

```vue
<script setup lang="ts">
const { confirm } = useConfirm()

async function handleDelete() {
  const accepted = await confirm({
    title: 'Delete this project?',
    description: 'This action cannot be undone.',
    confirmLabel: 'Delete project',
    confirmColor: 'danger',
    icon: 'hugeicons:delete-02',
  })

  if (!accepted)
    return

  await deleteProject()
}
</script>
```

Only an explicit confirmation resolves `true`. Cancel, Escape, or the renderer
being unmounted resolves `false`. The title defaults to the localized
`confirmation` message; the action and cancel labels use the same `continue`
and `cancel` messages as `<SAlertDialog>`.

## API

```ts
function useConfirm(): {
  confirm: (options?: UseConfirmOptions) => Promise<boolean>
}
```

### `UseConfirmOptions`

| Option         | Type        | Default                    |
| -------------- | ----------- | -------------------------- |
| `title`        | `string`    | localized “Confirm action” |
| `description`  | `string`    | -                          |
| `confirmLabel` | `string`    | localized continue message |
| `cancelLabel`  | `string`    | localized cancel message   |
| `confirmColor` | `ColorRole` | component default          |
| `icon`         | `string`    | -                          |

The composable is client-only. It uses the same `<SAlertDialog>` markup and
theme as declarative dialogs, and snapshots the caller's active `<STheme>`
while it is open. Like the other programmatic overlays, it requires `<SApp>`
once around the app root.

## Setup

```vue-html
<SApp>
  <NuxtPage />
</SApp>
```


# useDrawer

`useDrawer()` mirrors [useModal](https://selarasui.my.id/utilities/composables/use-modal) exactly,
for `<SDrawer>` instead - a panel sliding in from an edge of the screen,
draggable and snap-point aware, rather than a centered dialog.

## Usage

```vue
<script setup lang="ts">
const { open } = useDrawer()

async function handleFilters() {
  const applied = await open(FilterPanel, {
    props: { category: 'shoes' },
    side: 'bottom',
  })
}
</script>
```

## API

```ts
function useDrawer(): {
  open: <T = void>(component: Component, options?: UseDrawerOpenOptions) => Promise<T | undefined>
}
```

### `UseDrawerOpenOptions`

Same options as [`useModal`](https://selarasui.my.id/utilities/composables/use-modal), plus a few
more unique to a draggable, snap-point-aware panel:

| Option                                                                  | Type                                  | Description                                                                                                                      |
| ----------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `side`                                                                  | `'top' | 'right' | 'bottom' | 'left'` | Which edge the panel slides in from.                                                                                             |
| `handle`                                                                | `boolean`                             | Whether a grip bar shows at the top, signaling it's draggable.                                                                   |
| `snapPoints`                                                            | `(number | string)[]`                 | Resting heights/widths the panel snaps to while dragging - fractions (0-1), pixels (>1), or CSS length strings.                  |
| `snapPoint`                                                             | `number | string | null`              | The currently active snap point.                                                                                                 |
| `snapToSequentialPoints`                                                | `boolean`                             | Snap to the next sequential point one step at a time, instead of whichever is nearest by drag distance.                          |
| `modal`                                                                 | `boolean | 'trap-focus'`              | `'trap-focus'` traps focus but allows outside pointer events - see [Drawer](https://selarasui.my.id/components/overlays/drawer). |
| `props`, `title`, `description`, `dismissible`, `overlay`, `transition` |                                       | Same as `useModal`.                                                                                                              |

## Setup

Same as `useModal` - wrap your app's root with `<SApp>` once and
`useDrawer()` works anywhere underneath.


# useIcons

Every internal icon this library renders itself - a button's loading
spinner, a chip's remove glyph, a select's dropdown chevron, a toast's
success/danger icon, and so on - resolves from one semantic-purpose
registry, `useIcons()`, rather than being hardcoded per component. `name`
props you set yourself (`SButton`'s `icon`, `SInput`'s `icon`, ...) are
unaffected - this registry is only for icons a component renders on its
own.

## Usage

Override any key globally in `app.config.ts`:

```ts
export default defineAppConfig({
  selaras: {
    icons: {
      close: 'lucide:x',
      loading: 'lucide:loader-2',
    },
  },
})
```

Only the keys you set are overridden; everything else keeps its
[Hugeicons](https://hugeicons.com){rel="&#x22;nofollow&#x22;"} default. This changes every component
that uses that key at once - setting `close` reskins the dismiss icon on
`Modal`, `Toast`, `Input`'s clear button, and `Chip`'s remove button all
together, rather than needing a separate override for each.

## Registry

| Key               | Default                         | Used by                                                  |
| ----------------- | ------------------------------- | -------------------------------------------------------- |
| `close`           | `hugeicons:cancel-01`           | Modal, Toast, Chip, Input's clear button, CommandPalette |
| `check`           | `hugeicons:tick-02`             | Checkbox, Select's selected-item marker                  |
| `indeterminate`   | `hugeicons:minus-sign`          | Checkbox's indeterminate state                           |
| `chevronUp`       | `hugeicons:arrow-up-01`         | Accordion, InputNumber's stepper                         |
| `chevronDown`     | `hugeicons:arrow-down-01`       | Select, Autocomplete, DatePicker, InputNumber's stepper  |
| `chevronRight`    | `hugeicons:arrow-right-01`      | Tree, NavigationMenu                                     |
| `chevronLeft`     | `hugeicons:arrow-left-01`       | Pagination, DatePicker's month nav                       |
| `chevronsLeft`    | `hugeicons:previous`            | Pagination's first-page control                          |
| `chevronsRight`   | `hugeicons:next`                | Pagination's last-page control                           |
| `loading`         | `hugeicons:loading-02`          | Button/Switch's loading spinner                          |
| `search`          | `hugeicons:search-01`           | CommandPalette, Autocomplete                             |
| `sortUnsorted`    | `hugeicons:sorting-05`          | Table's sortable column headers when not sorted          |
| `sortAscending`   | `hugeicons:arrow-up-02`         | Table's ascending sort state                             |
| `sortDescending`  | `hugeicons:arrow-down-02`       | Table's descending sort state                            |
| `filter`          | `hugeicons:filter`              | Table column filter trigger                              |
| `columns`         | `hugeicons:table-columns-split` | Table's column-toggle control                            |
| `copy`            | `hugeicons:copy`                | CodeButton                                               |
| `lightMode`       | `hugeicons:sun-01`              | ColorModeToggle                                          |
| `darkMode`        | `hugeicons:moon`                | ColorModeToggle                                          |
| `calendar`        | `hugeicons:calendar-01`         | DatePicker                                               |
| `clock`           | `hugeicons:clock-01`            | DatePicker's time picker                                 |
| `plus`            | `hugeicons:plus-sign`           | InputNumber's stepper                                    |
| `minus`           | `hugeicons:minus-sign`          | InputNumber's stepper                                    |
| `success`         | `hugeicons:checkmark-circle-01` | Toast, Alert                                             |
| `danger`          | `hugeicons:cancel-circle`       | Toast, Alert                                             |
| `warning`         | `hugeicons:alert-circle`        | Toast, Alert                                             |
| `info`            | `hugeicons:information-circle`  | Toast, Alert                                             |
| `user`            | `hugeicons:user`                | Avatar's fallback                                        |
| `maximize`        | `hugeicons:fullscreen`          | Modal's fullscreen toggle                                |
| `minimize`        | `hugeicons:collapse`            | Modal's fullscreen toggle                                |
| `star`            | `hugeicons:star`                | Rating                                                   |
| `upload`          | `hugeicons:upload-01`           | FileUpload                                               |
| `file`            | `hugeicons:file-01`             | FileUpload, FileTree                                     |
| `folder`          | `hugeicons:folder-01`           | FileTree                                                 |
| `folderOpen`      | `hugeicons:folder-open`         | FileTree                                                 |
| `more`            | `hugeicons:more-horizontal`     | Table's row-actions trigger                              |
| `sidebarCollapse` | `hugeicons:sidebar-left-01`     | DashboardSidebarToggle                                   |

## API

```ts
function useIcons(): ComputedRef<IconRegistry>
```

Returns the merged registry (your `app.config.selaras.icons` overrides applied
on top of the Hugeicons defaults above) - use this if you're building
your own component and want it to respect the same overrides a consumer
already set, instead of hardcoding an icon name directly:

```vue
<script setup lang="ts">
const icons = useIcons()
</script>

<template>
  <SIcon :name="icons.close" />
</template>
```


# useLocale

`DatePicker`, `InputNumber`, and `TimeStepper` (DatePicker's own internal
time section) each take a `locale` prop for their own real `Intl`/
`@internationalized/date`-driven formatting - a BCP-47 code like `de-DE`
or `ar-EG`. Without a global default, every instance across an app needs
that prop repeated explicitly, and forgetting one silently falls back to
`en-US`.

## Usage

Set the default once in `app.config.ts`:

```ts
export default defineAppConfig({
  selaras: {
    locale: 'de-DE',
  },
})
```

Every `DatePicker`/`InputNumber` instance that doesn't set its own
`locale` prop now formats against `de-DE` instead of `en-US` - an
explicit per-instance `locale` still overrides this, exactly as before.

This is deliberately just the *date/time-formatting* locale, not a
combined "app language" switch - it's a separate axis from
[`useMessages`](https://selarasui.my.id/utilities/composables/use-messages) (the text every
component renders) and from `SApp`'s own `dir` prop (RTL/LTR layout).
Number formatting (`InputNumber`'s `formatOptions`, `Table`'s cell
formatting) reads from the same locale too, but per component instance -
a data grid legitimately showing figures in more than one locale side by
side doesn't need to fight a single global setting.

`SApp` itself reads this to set `<html lang>` alongside its existing
`dir` attribute - no extra wiring needed.

## API

```ts
function useLocale(): ComputedRef<string>
```

Returns your `app.config.selaras.locale` override, or `'en-US'` if unset - use
this if you're building your own component and want its own formatting to
respect the same app-wide default DatePicker/InputNumber already do:

```vue
<script setup lang="ts">
const locale = useLocale()
const formatter = computed(() => new Intl.NumberFormat(locale.value))
</script>
```


# useMessages

Every visible string a component renders itself - "Clear", "No results
found", a Pagination page count, an aria-label a screen reader announces -
resolves from one registry, `useMessages()`, rather than being hardcoded
per component. Text you pass yourself (an item's own `label`, a column's
own header) is unaffected - this registry is only for text a component
supplies on its own.

## Usage

Override any key globally in `app.config.ts`:

```ts
export default defineAppConfig({
  selaras: {
    messages: {
      clear: 'Effacer',
      search: 'Rechercher...',
    },
  },
})
```

Only the keys you set are overridden; everything else keeps its English
default. This changes every component that uses that key at once -
setting `close` reskins the dismiss label on `Modal`, `Toast`, `Input`'s
clear button, and `CommandPalette`'s footer hint all together, rather than
needing a separate override for each.

There's no bundled translation for any other language - this registry is
the mechanism, not a set of ready-made locale files. A full translation is
a single object literal covering every key below.

## Registry

| Key                                   | Default                                                                 | Used by                                                  |
| ------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| `loading`                             | `Loading`                                                               | Button/Switch's loading state                            |
| `clear`                               | `Clear`                                                                 | Input, Select, DatePicker's clear button                 |
| `close`                               | `Close`                                                                 | Modal, Toast, CommandPalette's footer hint               |
| `cancel`                              | `Cancel`                                                                | AlertDialog's default footer                             |
| `continue`                            | `Continue`                                                              | AlertDialog's default footer                             |
| `colorModeToggle`                     | `Toggle color mode`                                                     | ColorModeToggle                                          |
| `colorPicker`                         | `Color picker`                                                          | ColorPicker                                              |
| `colorPickerDescription`              | `Drag to adjust hue, saturation, and lightness`                         | ColorPicker's adaptive sr-only description               |
| `search`                              | `Search...`                                                             | CommandPalette, Autocomplete                             |
| `searchDescription`                   | `Type to filter, then use arrow keys and enter to select`               | Select/Autocomplete's adaptive sr-only description       |
| `columns`                             | `Columns`                                                               | Table's column-toggle control                            |
| `filterPlaceholder`                   | `Filter...`                                                             | Table's filter input                                     |
| `filterColumn`                        | `column => \`Filter ${column}\`\`                                       | Accessible label and heading for a Table column filter   |
| `previous`                            | `Previous`                                                              | Pagination, ContentSurround                              |
| `next`                                | `Next`                                                                  | Pagination, ContentSurround                              |
| `first`                               | `First`                                                                 | Pagination                                               |
| `last`                                | `Last`                                                                  | Pagination                                               |
| `stepper`                             | `Progress`                                                              | Stepper group accessible name                            |
| `stepperProgress`                     | `` (step, total) => `Step ${step} of ${total}` ``                       | Stepper live-region announcement                         |
| `pagination`                          | `Pagination`                                                            | Pagination's nav aria-label                              |
| `scrollTabsLeft`                      | `Scroll tabs left`                                                      | Tabs' left overflow button                               |
| `scrollTabsRight`                     | `Scroll tabs right`                                                     | Tabs' right overflow button                              |
| `datePicker`                          | `Date picker`                                                           | DatePicker                                               |
| `datePickerDescription`               | `Use arrow keys to navigate days, enter to select`                      | DatePicker's adaptive sr-only description                |
| `dateRangePicker`                     | `Date range picker`                                                     | DatePicker (range mode)                                  |
| `dateRangePickerDescription`          | `Use arrow keys to navigate days, enter to select a start and end date` | DatePicker (range mode)'s adaptive sr-only description   |
| `timePicker`                          | `Time picker`                                                           | DatePicker (time section)                                |
| `timePickerDescription`               | `Use arrow keys to adjust the highlighted field`                        | DatePicker (time section)'s adaptive sr-only description |
| `pickTime`                            | `Pick a time`                                                           | DatePicker (timeOnly mode)                               |
| `previousMonth`                       | `Previous month`                                                        | DatePicker                                               |
| `nextMonth`                           | `Next month`                                                            | DatePicker                                               |
| `previousYear`                        | `Previous year`                                                         | DatePicker                                               |
| `nextYear`                            | `Next year`                                                             | DatePicker                                               |
| `previousDecade`                      | `Previous decade`                                                       | DatePicker (year view)                                   |
| `nextDecade`                          | `Next decade`                                                           | DatePicker (year view)                                   |
| `pickDate`                            | `Pick a date`                                                           | DatePicker                                               |
| `chooseMonth`                         | `Choose month`                                                          | DatePicker (month view)                                  |
| `chooseYear`                          | `Choose year`                                                           | DatePicker (year view)                                   |
| `hour`                                | `Hour`                                                                  | DatePicker's time stepper                                |
| `minute`                              | `Minute`                                                                | DatePicker's time stepper                                |
| `done`                                | `Done`                                                                  | DatePicker's time section                                |
| `increment`                           | `Increment`                                                             | InputNumber's stepper                                    |
| `decrement`                           | `Decrement`                                                             | InputNumber's stepper                                    |
| `noOptions`                           | `No options`                                                            | Select, Autocomplete                                     |
| `selectAll`                           | `Select all`                                                            | Listbox, TransferList                                    |
| `transferSource`                      | `Available`                                                             | TransferList's source heading                            |
| `transferTarget`                      | `Assigned`                                                              | TransferList's destination heading                       |
| `moveToTarget`                        | `Add selected`                                                          | TransferList's add button                                |
| `moveToSource`                        | `Remove selected`                                                       | TransferList's remove button                             |
| `listSelectionCount(selected, total)` | `${selected} of ${total} selected`                                      | TransferList's panel counts                              |
| `transferItems(count, target)`        | `${count} item(s) moved to ${target}`                                   | TransferList's live announcement                         |
| `noResultsFound`                      | `No results found`                                                      | Autocomplete, CommandPalette                             |
| `createOption(value)`                 | `Create "${value}"`                                                     | Autocomplete's free-text suggestion                      |
| `noData`                              | `No data`                                                               | Table                                                    |
| `expandRow`                           | `Expand row`                                                            | Table                                                    |
| `collapseRow`                         | `Collapse row`                                                          | Table                                                    |
| `maximize`                            | `Maximize`                                                              | Modal's fullscreen toggle                                |
| `minimize`                            | `Minimize`                                                              | Modal's fullscreen toggle                                |
| `removeItem(label?)`                  | `Remove ${label}` / `Remove`                                            | Chip, FileUpload's remove button                         |
| `moreItems(count)`                    | `+${count} more`                                                        | Select/Autocomplete's chip-overflow indicator            |
| `avatarGroupOverflow(count)`          | `+${count}`                                                             | AvatarGroup's overflow indicator                         |
| `paginationInfo(page, total)`         | `Page ${page} of ${total}`                                              | Pagination                                               |
| `codeTabFallback(index)`              | `Tab ${index}`                                                          | Tabs (code block group)                                  |
| `copyCode`                            | `Copy code`                                                             | Code block copy button                                   |
| `codeCopied`                          | `Copied!`                                                               | Code block copy feedback                                 |
| `dropFiles`                           | `Drop files here or click to browse`                                    | FileUpload                                               |
| `invalidFileType(name)`               | `${name}: invalid file type`                                            | FileUpload                                               |
| `invalidFileSize(name, max)`          | `${name}: exceeds the ${max} size limit`                                | FileUpload                                               |
| `tooManyFiles(max)`                   | `Only ${max} file(s) allowed`                                           | FileUpload                                               |
| `showMore`                            | `Show more`                                                             | ReadMore                                                 |
| `showLess`                            | `Show less`                                                             | ReadMore                                                 |
| `selectFile`                          | `Select a file to view its content`                                     | FileTree                                                 |
| `toggleSidebar`                       | `Toggle sidebar`                                                        | DashboardSidebarToggle                                   |
| `breadcrumb`                          | `Breadcrumb`                                                            | Breadcrumb's nav aria-label                              |
| `showHiddenBreadcrumbItems`           | `Show hidden breadcrumb items`                                          | Breadcrumb's overflow trigger                            |
| `commandPalette`                      | `Command palette`                                                       | CommandPalette's sr-only title                           |
| `commandPaletteDescription`           | `Search for a command and press enter`                                  | CommandPalette's sr-only description                     |
| `navigate`                            | `Navigate`                                                              | CommandPalette's footer hint                             |
| `select`                              | `Select`                                                                | CommandPalette's footer hint                             |
| `onThisPage`                          | `On this page`                                                          | ContentToc's default heading                             |
| `upToSize(size)`                      | `Up to ${size}`                                                         | FileUpload's max-size hint                               |

There's deliberately no `am`/`pm` entry: `DatePicker`'s time section
derives that text directly from [`useLocale`](https://selarasui.my.id/utilities/composables/use-locale)
via `Intl`, so it always matches the same locale driving the hour-cycle
display next to it, rather than needing a separate translation kept in
sync by hand.

## API

```ts
function useMessages(): ComputedRef<MessageRegistry>
```

Returns the merged registry (your `app.config.selaras.messages` overrides applied
on top of the English defaults above) - use this if you're building your
own component and want it to respect the same overrides a consumer
already set, instead of hardcoding a string directly:

```vue
<script setup lang="ts">
const messages = useMessages()
</script>

<template>
  <button :aria-label="messages.close">
    ...
  </button>
</template>
```


# useModal

`useModal()` lets you open a `<SModal>` (or any component you point it at)
without placing it in your template - useful for confirmation dialogs
triggered from a click handler, or flows where the modal's content isn't
known until runtime.

## Usage

```vue
<script setup lang="ts">
const { open } = useModal()
const modal = useTemplateRef('confirmModal')

async function handleDelete() {
  const confirmed = await open(ConfirmDeleteDialog, {
    props: { itemName: 'My project' },
  })
  if (confirmed) {
    // ...
  }
}
</script>
```

The component you pass to `open()` resolves the returned promise by emitting
`close` with its result. Escape, an outside click, or the shell's close button
resolve it with `undefined`.

## API

```ts
function useModal(): {
  open: <T = void>(component: Component, options?: UseModalOpenOptions) => Promise<T | undefined>
}
```

`open()` resolves with `undefined` if the modal is dismissed without an
explicit value (e.g. Escape, backdrop click).

### `UseModalOpenOptions`

| Option        | Type                      | Description                                                                                                                                              |
| ------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `props`       | `Record<string, unknown>` | Props passed to the opened component.                                                                                                                    |
| `title`       | `string`                  | Registered with Reka as the dialog's accessible name, visually hidden - the opened component still supplies its own visible header via the content slot. |
| `description` | `string`                  | Registered with Reka as the dialog's accessible description, visually hidden.                                                                            |
| `dismissible` | `boolean`                 | Whether Escape/backdrop click closes it.                                                                                                                 |
| `modal`       | `boolean`                 | Whether it traps focus and blocks interaction outside.                                                                                                   |
| `overlay`     | `boolean`                 | Whether a backdrop is rendered.                                                                                                                          |
| `transition`  | `boolean`                 | Whether the open/close animation plays.                                                                                                                  |

Every option is forwarded straight through to the underlying `SModal`
instance, and defaults to `SModal`'s own defaults when omitted. Since the
opened component always renders through `SModal`'s `content` slot (see
[Modal](https://selarasui.my.id/components/overlays/modal#custom-content)), `title`/`description`
are the only way to give a programmatically-opened dialog a real
accessible name/description - pass them if the opened component's own
content doesn't already include a heading Reka can associate with it.

## Setup

The render loop that actually mounts opened modals lives inside `<SApp>` -
wrap your app's root with it once (typically in `app.vue`) and `useModal()`
works anywhere underneath:

```vue-html
<SApp>
  <NuxtPage />
</SApp>
```


# useSlideover

`useSlideover()` mirrors [useModal](https://selarasui.my.id/utilities/composables/use-modal) exactly,
for `<SSlideover>` instead - a panel sliding in from an edge of the screen
rather than a centered dialog.

## Usage

```vue
<script setup lang="ts">
const { open } = useSlideover()

async function handleEdit() {
  const saved = await open(EditItemPanel, {
    props: { itemId: '123' },
    side: 'right',
  })
}
</script>
```

## API

```ts
function useSlideover(): {
  open: <T = void>(component: Component, options?: UseSlideoverOpenOptions) => Promise<T | undefined>
}
```

### `UseSlideoverOpenOptions`

Same options as [`useModal`](https://selarasui.my.id/utilities/composables/use-modal), plus two more
unique to a slide-in panel:

| Option                                                                           | Type                                  | Description                                                            |
| -------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| `side`                                                                           | `'top' | 'right' | 'bottom' | 'left'` | Which edge the panel slides in from.                                   |
| `inset`                                                                          | `boolean`                             | Whether the panel floats with a gap instead of flush against the edge. |
| `props`, `title`, `description`, `dismissible`, `modal`, `overlay`, `transition` |                                       | Same as `useModal`.                                                    |

## Setup

Same as `useModal` - wrap your app's root with `<SApp>` once and
`useSlideover()` works anywhere underneath.


# v-hotkey

`v-hotkey` listens for a keyboard shortcut while its bound element is
mounted. It is auto-imported in Nuxt apps and is also available from
`@sewadah/selaras/directives`.

## Usage

Bind a shortcut to the element's regular click behavior:

```vue-html
<SButton v-hotkey="'mod+k'" @click="openSearch">
  Search
</SButton>
```

Or pass a handler directly:

```vue-html
<SButton v-hotkey="{ keys: 'mod+s', handler: save }">
  Save
</SButton>
```

`mod` resolves to Command on macOS and Control on other platforms. Other
modifiers include `ctrl`, `meta`, `alt`, and `shift`; common keys include
`enter`, `escape`, `space`, and the arrow names.

## Options

| Option            | Type                                    | Default             | Description                                                                           |
| ----------------- | --------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
| `keys`            | `string`                                | -                   | A `+`-separated key chord, such as `mod+k`.                                           |
| `handler`         | `(event: KeyboardEvent) => void`        | bound element click | Runs instead of clicking the bound element.                                           |
| `when`            | `boolean | (element, event) => boolean` | `true`              | Enables the shortcut only while the condition is true.                                |
| `allowInEditable` | `boolean`                               | `false`             | Allows the shortcut while focus is in an input, textarea, select, or editable region. |

Printable single-key shortcuts only run while the bound element (or one of
its descendants) has focus. Modifier shortcuts are global while mounted; use
`when` to scope them to state such as an open menu. Editable controls are
ignored by default.

## Menu item shortcuts

Dropdown, ContextMenu, NavigationMenu, and CommandPalette items accept
`shortcut` to show a [`Kbd`](https://selarasui.my.id/components/elements/kbd) hint. Add
`hotkey: true` to activate it too. Menu shortcuts only run while their menu
is active; NavigationMenu shortcuts run while that item is focused. The
shortcut follows the item's normal activation path, so it calls `onSelect`
or follows the item's link destination. A visible hint alone does not
register a shortcut.

```ts
const item = { label: 'Save', shortcut: 'mod+s', hotkey: true, onSelect: save }
```


# v-mask

`v-mask` formats text as it is entered. The input shows the formatted text,
while `v-model` receives the raw value without the mask's literal
characters. It works on native inputs and single-input components such as
`SInput`.

## Usage

In Nuxt, the directive is auto-imported. Pass the mask pattern as a string -
it's a JavaScript expression, so it needs its own quotes:

```vue-html
<input v-model="phone" v-mask="'(###) ###-####'" inputmode="tel">
```

Typing `5551234567` shows `(555) 123-4567`, and `phone` is `5551234567`.
Setting `phone` from code formats it the same way.

It works the same on `SInput`:


```vue
<script setup lang="ts">
const phone = ref('')
</script>

<template>
  <div class="grid gap-2">
    <SInput v-model="phone" v-mask="'(###) ###-####'" inputmode="tel" placeholder="(555) 123-4567" />
    <p class="text-sm text-content-muted">
      Value: {{ phone || '—' }}
    </p>
  </div>
</template>
```


```vue-html
<SInput v-model="phone" v-mask="'(###) ###-####'" inputmode="tel" />
```

## Tokens

| Token | Matches             |
| ----- | ------------------- |
| `#`   | A digit             |
| `@`   | A letter            |
| `*`   | A letter or a digit |

Any other character in the mask is a literal, inserted automatically as the
user types. Characters that don't fit the next token are skipped.

A date-shaped mask like `##/##/####` formats text only; it doesn't check
that the date is a real calendar date:

```vue-html
<SInput v-model="date" v-mask="'##/##/####'" placeholder="dd/mm/yyyy" />
```

Literal prefixes work too. With `+62####`, typing `8123` shows `+628123`,
and the raw value stays `8123`.

## Options

Pass an object for custom tokens or to read the formatted value as well:

| Option   | Type                                                                        | Description                                                                          |
| -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `mask`   | `string`                                                                    | The mask pattern.                                                                    |
| `tokens` | `Record<string, { pattern: RegExp, transform?: (char: string) => string }>` | Extra tokens, merged over the defaults.                                              |
| `onMask` | `(detail: MaskDetail) => void`                                              | Called with `{ value, maskedValue, completed }` whenever the formatted text changes. |

Custom tokens can transform what they accept - here, a hex code shown in
uppercase:

```vue-html
<SInput
  v-model="color"
  v-mask="{
    mask: 'HHHHHH',
    tokens: { H: { pattern: /[\da-f]/i, transform: char => char.toUpperCase() } },
  }"
/>
```

Use `onMask` when you need the formatted text or want to know whether every
position is filled. `value` matches `v-model`, `maskedValue` is what the
input shows, and `completed` is `true` once every token is filled:

```vue-html
<SInput
  v-model="phone"
  v-mask="{ mask: '(###) ###-####', onMask: ({ maskedValue }) => formatted = maskedValue }"
/>
```

The same detail is also dispatched as a bubbling native `mask` event on the
input.


# v-ripple

`v-ripple` spawns a growing, fading circle from the pointer's position on
`pointerdown` - the classic ripple-style click feedback. It works on any
element, not just Selaras components.

## Usage

Auto-imported, no explicit import needed inside a Nuxt app:

```vue-html
<button v-ripple>
  Click me
</button>
```

Opt out per-element with `v-ripple="false"`, or override the defaults:

```vue-html
<button v-ripple="{ color: 'var(--selaras-resolved-color-primary-fill)', opacity: 0.4, duration: 700 }">
  Click me
</button>
```

### `RippleOptions`

| Option     | Type     | Default          | Description                                        |
| ---------- | -------- | ---------------- | -------------------------------------------------- |
| `color`    | `string` | `'currentColor'` | Fill color for the ripple.                         |
| `opacity`  | `number` | `0.25`           | Peak opacity before fading out.                    |
| `duration` | `number` | `500`            | How long the ripple takes to grow and fade, in ms. |

### Disabling it globally

`app.config.selaras.ripple = false` turns ripples off everywhere, instead of
opting out one element at a time:

```ts
// app.config.ts
export default defineAppConfig({
  selaras: {
    ripple: false,
  },
})
```

This only reaches components that actually check it - Selaras's own
components that use `v-ripple` internally (like `SButton`) already do, via
the `useRippleEnabled()` composable. A bare `v-ripple` you write yourself
on a plain element doesn't read `app.config.selaras.ripple` automatically (a
directive's own lifecycle hooks can't call `useAppConfig()` - it needs a
component's `setup()` context) - read it yourself and pass it as the
binding value if you want your own elements to respect the same global
toggle:

```vue-html
<script setup lang="ts">
const rippleEnabled = useRippleEnabled()
</script>

<template>
  <button v-ripple="rippleEnabled">
    Click me
  </button>
</template>
```

## Behavior notes

- The host element gets `position: relative; overflow: hidden` applied
  automatically if it doesn't already have an opinion on either, so the
  ripple stays contained to its shape without any extra CSS from you.
- Respects `prefers-reduced-motion` automatically, through the same
  reduced-motion handling every other animation in the library goes
  through - no separate configuration needed.


# Documentation exports

## Documentation exports

Selaras publishes documentation as plain text and Markdown for coding assistants:

- [llms.txt](https://selarasui.my.id/llms.txt) is a compact index with links to individual documentation pages.
- [llms-full.txt](https://selarasui.my.id/llms-full.txt) contains the complete documentation in one file.
- Individual pages are available under `/raw/`, for example
  [Button Markdown](https://selarasui.my.id/raw/components/elements/button.md).

The full export and individual pages include the Vue source of live examples,
alongside component props, slots, and usage guidance. These files are regenerated
with the documentation site, so they follow the published documentation version.

## Using an assistant

Give your assistant the documentation index URL and ask it to read the relevant
component pages before writing code. Prefer existing Selaras components and
customize them through props, slots, `ui` overrides, and theme configuration.

For example:

```text
Use Selaras for this settings page. Read its llms.txt index and the relevant
form, layout, and overlay documentation first. Reuse existing components and
check their documented props and slots before implementing custom UI.
```


# MCP

Selaras includes a local, read-only MCP server named `selaras-mcp`. Your agent client launches it as a subprocess and communicates over standard input and output (`stdio`). No hosted server, account, API key, or authentication service is needed.

The catalog is bundled with the package and generated from the same documentation and Vue examples as the website. After installation, the server works without fetching documentation from the network. Its catalog version matches the installed package.

## Configure your client

Install a Selaras release containing the MCP server in your application. Add this entry to your client's MCP configuration:

```json
{
  "mcpServers": {
    "selaras": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-project/node_modules/@sewadah/selaras/agent/mcp.mjs"
      ]
    }
  }
}
```

Replace the absolute path with your application's location. The example uses a common JSON configuration shape; your client may use a different file or format. Use the Node.js version supported by Selaras and restart or reconnect the client after changing its configuration.

The package also exposes the `selaras-mcp` executable. Clients that launch commands from your project directory can use `npx --no-install selaras-mcp`, so the server uses your existing installation rather than downloading a potentially different version.

For development in this repository, run `bun run agent:build` first, then point your client at the repository's `agent/mcp.mjs`. The npm command becomes available after a package release containing this implementation.

## Tools

| Tool                   | Arguments                                            | Result                                                                   |
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| `list_components`      | Optional `category`, such as `forms` or `overlays`   | Component names, descriptions, guide paths, and example names.           |
| `search_documentation` | `query`; optional `limit` from 1 to 20               | Ranked guide matches across components, composables, setup, and theming. |
| `get_documentation`    | `path` or component name; optional `section` heading | Markdown API guidance with complete Vue example source.                  |
| `get_example`          | Example `name` from the catalog                      | The exact Vue source of that example.                                    |

The server also exposes `selaras://catalog` and documentation resources under `selaras://docs/...` for clients that support MCP resources.

## Example workflow

```text
Use Selaras for this settings page. Discover components with list_components,
then read the Select, FormField, and Modal documentation and relevant examples.
Use the project's existing theme and enable adaptive presentation where useful.
```

The tools retrieve information; the agent makes component recommendations based on your requirements. They do not modify your project or generate files.

## MCP versus a skill

The [skill](https://selarasui.my.id/overview/agent-support/skills) provides guidance about how to build with Selaras. MCP provides structured access to the installed version's documentation. Either can be used independently; combining them gives the agent both guidance and retrieval tools.

Public documentation does not require MCP. [llms.txt and Markdown exports](https://selarasui.my.id/overview/agent-support/documentation) remain available for clients that can read URLs. A hosted HTTP MCP service would be another distribution option, but Selaras currently supplies the local stdio server only.


# Agent support

Give agents access to the component catalog and API guides before asking them to implement an interface. The documentation exports include real Vue example source rather than just rendered previews.

## Available today

[Documentation exports](https://selarasui.my.id/overview/agent-support/documentation) explains `llms.txt`, `llms-full.txt`, and individual Markdown pages. Start with the index, then retrieve the component pages needed for the task.

## Suggested instructions

```text
Use Selaras components for existing UI patterns.
Read the relevant component documentation before implementing.
Use documented props, models, events, slots, and ui overrides.
Check shared configuration for icons, messages, color modes, and adaptive presentation.
Build custom components only when the catalog does not cover the required behavior.
```

## Skills and MCP

Use the [Selaras skill](https://selarasui.my.id/overview/agent-support/skills) to guide component selection, API discovery, and customization. Connect the [local MCP server](https://selarasui.my.id/overview/agent-support/mcp) for structured search and access to documentation bundled with your installed package version.

The skill can work with public documentation alone. MCP is optional and does not need hosting or authentication. These integrations become available from the repository when pushed and from npm in a release containing them.


# Skills

The `selaras` skill teaches an agent how to discover components, read their contracts, and customize them through props, slots, themes, icons, and messages. It works with public Markdown documentation and can also use the [local MCP server](https://selarasui.my.id/overview/agent-support/mcp).

## Install

Use the [Skills CLI](https://github.com/vercel-labs/skills){rel="&#x22;nofollow&#x22;"} from your application directory:

```bash
npx skills add sewadahapp/selaras --skill selaras
```

Choose your agent and installation scope when prompted. The repository stores the skill at `skills/selaras/SKILL.md`; you can also copy that folder into your agent's supported skill directory.

The npm package includes the skill as well. To install the copy matching your dependency version:

```bash
npx skills add ./node_modules/@sewadah/selaras/skills/selaras
```

Repository installation becomes available when these changes are pushed; package installation requires a release containing the skill. The repository copy follows its current branch, while the package copy follows your installed version.

## Use it

Ask your agent to use the Selaras skill for a concrete interface:

```text
Use the Selaras skill to build a customer management page with a searchable
Table, an edit Modal, and a confirmation dialog. Read the relevant component
contracts and examples first, and use the project's existing theme.
```

Clients with automatic skill discovery may select it when working on a Selaras project. Explicit invocation syntax depends on your client.

## What it provides

The skill helps agents look beyond basic buttons and inputs, find components and composables for the requested interaction, and check the actual API before implementing. It also distinguishes global configuration from local props and slots.

A skill provides instructions rather than executable component recommendations. The agent still chooses components and validates its implementation. Without MCP, it reads the documentation exports directly; with MCP, it can retrieve the installed version's catalog and examples through tools.