# TheUI Svelte - full documentation

> theui-svelte is an accessible, customizable component library for Svelte 5 and Tailwind CSS v4: 70 components covering forms, navigation, overlays, data display and feedback, each with a typed prop API, dark mode and RTL support.

Source: https://www.theui.dev. This file is generated from the documentation, so it carries
the same content as the individual pages.

## Install

```bash
npm i theui-svelte
```

Then in the consumer's `src/app.css`:

```css
@import 'tailwindcss';
@import 'theui-svelte/style';
```

Those two lines are the whole setup. The stylesheet registers the package's own
markup for Tailwind to scan, so there is no `@source` line to add. Versions
before 3.1.0 needed `@source "../node_modules/theui-svelte";` as well; a project
that still carries it is redundant, not broken.

## Agent setup

```bash
npx theui ai
```

Run this once in the project root, after the install above. It writes a short
pointer block into the instruction files the project already has - `AGENTS.md`,
`CLAUDE.md`, Copilot, Cursor, Windsurf, Gemini - each naming
`node_modules/theui-svelte/AGENTS.md`, which carries the full rules for the
exact version installed. It points rather than copies, so it cannot overwrite
rules the project already wrote, and re-running replaces the block in place -
which makes it the right thing to do after an upgrade too.

Nothing about how the library works depends on this. It only decides how much
an agent gets right on the first attempt.

## Writing code with this library

- Svelte 5 runes only. Props are `let { x } = $props()`, state is `$state`,
  derived values are `$derived`. Never `export let`, `on:click`, `<slot>`,
  `createEventDispatcher` or stores.
- Content holes are Snippet props rendered with `{@render children?.()}`.
- Import from the barrel: `import { Button, Card } from "theui-svelte"`. Deep
  import paths are flat and always `theui-svelte/<Name>.svelte`, whatever folder
  the component lives in: `theui-svelte/AccordionItem.svelte`, not
  `theui-svelte/Accordion/AccordionItem.svelte`.
- Types and helpers: `import type { ROUNDED } from "theui-svelte/type"` and
  `import { notify } from "theui-svelte/function"`.
- `class` is merged with `twMerge`, so a class you pass wins over the library
  default for the same property.
- Rest props spread onto the root element, so any HTML attribute, `data-*` or
  event handler passes through.
- Build with the semantic tokens - `bg-primary`, `bg-secondary`, `text-default`,
  `text-muted`, `brand-50..950`, `error-*`, `info-*`, `success-*`, `warning-*` -
  rather than raw palette colors, so themes and dark mode keep working.
- Pair every color with a `dark:` counterpart. Dark mode is class based: `.dark`
  on `<html>`, toggled by `<DarkMode />` and persisted to
  `localStorage["theui-theme"]`.
- Use logical properties for RTL - `ms-*`, `me-*`, `ps-*`, `pe-*`, `start`, `end` -
  never `left`, `right`, `ml-*` or `mr-*`.
- Boolean props are written bare: `<Card horizontal>`, `<AccordionItem open flush>`,
  `<Pagination flat hidePreviousNext />`, `<Progress vertical>`, `<Alert dismissible icon>`,
  `<Badge grow fixed>`, `<Drawer fullscreen>`.

## Things that are easy to get wrong

- `Accordion.standalone` reads backwards: `true` (the default) means only one
  item may be open at a time. Pass `standalone={false}` to let several stay open.
- `Tabs.variant` defaults to `"pills"`, not `"tabs"`.
- `Tab` and `TabPanel` pair by matching `value`, not by document order, and
  `value` is required on both.
- There is no `Textarea` component. Use `<Input type="textarea" />`.
- `Tooltip` and `Notification` are page-level singletons. Render each once, in
  `+layout.svelte`. A second instance doubles up listeners.
- `Popover.trigger` is a DOM element `id` string, not a Snippet, and fails
  silently when the id does not resolve at mount.
- `Table` with `Record` rows needs `keys` to fix column order, or it renders no
  cells at all - silently.
- `DropdownItem` belongs inside `Dropdown`. Inside `NavDropdown` use `NavLink`:
  they are two different context systems and mixing them throws.
- `Slide` must be a direct child of `Slider`, and does not deregister on
  destroy, so build the slide list up front.
- These throw at runtime outside their parent: `Tab`, `TabPanel` (need `Tabs`),
  `Slide` (needs `Slider`), `DropdownItem` (needs `Dropdown`), and `NavBrand`,
  `NavCollapse`, `NavLinkGroup`, `NavLink`, `NavDropdown` (need `Navbar`).
- `notify()` is browser only - it returns `""` and does nothing during SSR - and
  its per-call `position` is ignored. Set placement on `<Notification position={...} />`.
- Form config cascades `Fieldset` over `Form`, and an explicit prop over both.
- Floating labels need the label after the input, because the CSS uses Tailwind's
  `peer` modifier. Do not reorder the markup inside `Input` or `Select`.
- The z-index ladder is fixed and should not be overridden: Navbar 100,
  Dropdown 200, Drawer 300, Modal 400, Popup 500, Tooltip 600, Notification 700.

---

Source: https://www.theui.dev/docs/accessibility

# Accessibility Guide

What **theui-svelte** handles for you, what is left to you, and the keys every component answers to.

Every component ships with its roles, its keyboard behavior and its focus handling already in place, so a modal traps focus and a tab list answers to the arrow keys without any work from you. What the library cannot know is your content: the name of an icon-only button, the text of a label, the colors you pick. That part is yours, and this page marks the line between the two.

## Why Accessibility Matters

Accessible pages let people understand, navigate and use your site whether they see it, hear it, or drive it from the keyboard alone. Much of it is also plain good practice: a page that works without a mouse works on a broken trackpad too, and a field with a real label is easier for everyone to fill in.

## What the Components Handle

These behaviors come with the components. You do not have to add them, and you should not need to work around them.

- **Roles and structure**: `Modal` is a dialog, `Tabs` renders a real tab list, `Dropdown` items carry `menuitem`, `Progress` is a progress bar, `Rating` is a group of radio buttons, and `Breadcrumb`, `Pagination` and `NavLink` mark the current page with `aria-current`.

- **Keyboard**: arrow keys, `Home` and `End` work inside tabs, sliders, menus, the calendar, the time fields, one-time-code boxes and pagination. The table below lists them all.

- **Focus**: a `Modal` moves focus into itself, keeps `Tab` inside while it is open, and hands focus back to whatever opened it. `Escape` closes the modal on top, not all of them. Closed modals and drawers are `inert`, so the keyboard skips what is hidden behind them.

- **Descriptions**: `helperText` is tied to its field with `aria-describedby`, so a screen reader reads the hint along with the label. `Tooltip` and `Popover` describe the element they belong to.

- **Announcements**: a notification announces itself as an alert, the calendar announces the month you move into, and a slider announces slide changes once its autoplay is paused.

- **Tables**: header cells carry `scope`, so a screen reader ties every cell to its column, and a table too wide for its container becomes a named region you can scroll with the keyboard.

- **Motion**: when the system asks for reduced motion, a slider stops playing by itself. Setting `animationSpeed="none"` turns transitions off wherever the prop exists.

## Keyboard Reference

Beyond `Tab` and `Shift + Tab`, which move between the controls on the page, the components answer to these keys.

| Component | Keys |
| --- | --- |
| Tabs | `←` `→` move between tabs, `Home` first, `End` last |
| Slider | Arrow keys move one slide, `Home` first slide, `End` last slide |
| Dropdown, NavDropdown | `↑` `↓` open the menu, `Escape` closes it and returns focus to the trigger, `Enter` follows a link, `Space` presses a button |
| Combobox | Type to filter, `↑` `↓` move, `Home` and `End` jump, `Enter` picks, `Escape` closes, `Backspace` removes the last chip |
| DatePicker | `↓` opens the calendar, arrow keys move by day and week, `Home` and `End` jump to the ends of the week, `PageUp` and `PageDown` change month (with `Shift`, year), `Escape` closes |
| TimePicker | `↑` `↓` change the part you are on, `←` `→` move between hour, minute and AM/PM, `Home` and `End` jump to the lowest and highest value |
| OtpInput | `←` `→` move between boxes, `Backspace` and `Delete` clear, `Home` and `End` jump to the first and last box, and a paste fills the boxes |
| Pagination | `←` `→` move between page links |
| Rating | Arrow keys pick a value, as in any radio group |
| Modal, Drawer, Popup | `Escape` closes the one on top, and `Tab` stays inside an open modal |
| Accordion, Collapse | `Enter` or `Space` on the heading opens and closes it |

## What You Still Have to Do

The library never invents words for your interface. These are the pieces only you can supply.

- **Name icon-only controls.** A button with nothing but an icon has no name to read out. Give it `ariaLabel`. From version 3 the library no longer guesses a name for `Button`, `QabItem` or `NavBrand`, because a guessed name read over the visible text is worse than none.

- **Label every field.** Write the label as the content of the field, and keep `helperText` for the hint. Both are tied to the input for you.

- **Describe images.** A `Slide` with `src` and an `Avatar` with a picture both take `alt`. Leave it empty only when the image says nothing the text does not already say.

- **Mark the current page.** Set `active` on the `NavLink` of the page you are on, and it gets `aria-current="page"`.

- **Name what has no text of its own.** A `Table` takes `ariaLabel` or a `<caption>`, and a `Close` button takes `ariaLabel` to say what it closes. Name a `Container` only when the area is somewhere people would want to jump to, since a named `Container` becomes a landmark.

- **Keep the focus ring.** The components draw a visible ring when a control is focused from the keyboard. If your own CSS removes outlines, put a visible replacement back.

- **Check your colors.** Components take their colors from your theme, so contrast depends on the palette you choose. Aim for 4.5:1 on normal text and 3:1 on large text, icons and borders.

**Name an icon-only button**

```svelte
<Button ariaLabel="Close the menu">
  <Svg><path d="M6 18L18 6M6 6l12 12" /></Svg>
</Button>
```

## Motion and Animation

People who ask their system for reduced motion get less of it: a `Slider` will not play on its own, and its timer bar stays still. The choice is theirs, not a prop, so test it by turning reduced motion on in your operating system. Where you want an element calm for everyone, `animationSpeed="none"` removes its transition.

## Color and Contrast

The components inherit your brand colors, so they are exactly as readable as the palette behind them. Check the shades you picked on the [colors page](https://www.theui.dev/docs/colors) against the background they sit on, in both light and dark mode, and remember that a color alone should never be the only thing carrying a meaning: pair it with text, an icon or a shape.

## Testing Your Pages

Automatic checks catch perhaps a third of what matters. Do the first item on this list before the others.

- **Put the mouse away**: reach every control with `Tab`, use it, and make sure you can always see where you are and can get out of anything you opened.

- **axe DevTools** or **WAVE**: browser extensions that report missing names, bad contrast and broken structure.

- **Lighthouse**: built into Chrome DevTools, useful as a quick pass over a whole page.

- **A screen reader**: VoiceOver on macOS and iOS, NVDA or JAWS on Windows, TalkBack on Android. Listening to one page end to end teaches more than any report.

## Per-Component Notes

Every component page ends with its own **Accessibility** section, covering what that component does, the props that affect it and anything it needs from you. See [Modal](https://www.theui.dev/docs/modal#accessibility), [Tabs](https://www.theui.dev/docs/tabs#accessibility) or [Combobox](https://www.theui.dev/docs/combobox#accessibility) for the shape of it.

## Further Support and Feedback

If something here does not hold up in practice, that is a bug worth reporting. Open an issue on [GitHub](https://github.com/mbparvezme/theui-svelte/issues) with the component and how you were using it, and it will be looked at.

---

Source: https://www.theui.dev/docs/ai-assistants

# AI Coding Assistants

A coding agent that has never seen **theui-svelte** guesses at the API, and the guesses fail quietly rather than loudly. The package ships the rules it cannot guess, and one command hands them to your agent — the difference between an agent that invents props and one that writes working components.

## What Comes With The Package

Everything an agent needs is inside the installed package. The pages on this site are a convenience for tools that fetch URLs, not a dependency — an agent working offline has the whole contract locally.

- `node_modules/theui-svelte/AGENTS.md` — the composition rules, the shared prop contract, which children throw outside their parent, and the behaviours that are easy to get wrong.

- `node_modules/theui-svelte/dist/**/*.d.ts` — every prop name and type, for the exact version installed. These cannot drift from the code, so they are the better answer to *what props does this take*.

- The same documentation as Markdown over HTTP, for tools that would rather read a URL. See [further down](#markdown).

Because the rules travel with the package, they describe the version you installed rather than whatever is newest, and they keep working when a future library is published under its own name.

## Setting It Up

Agents look for instructions in a **project root**, and none of them promise to read anything from inside `node_modules`. So the rules that ship with the package have to be connected to the files your tools already read. One command does that:

**Run this once, in your project root**

```bash
npx theui ai
```

It writes a short block into whichever instruction files your project already has — `AGENTS.md`, `CLAUDE.md`, Copilot, Cursor, Windsurf, Gemini — each naming the path to the rules inside the package, then prints back which files it touched. The [CLI reference](https://www.theui.dev/docs/cli) covers every option and the exact block it writes.

It writes a **pointer rather than a copy**, which matters twice. It cannot overwrite rules you wrote yourself, because it only ever adds its own block between two markers. And it cannot go stale: upgrading the library upgrades what your agent reads, with nothing to refresh.

To do it by hand instead, add one line to your `AGENTS.md`, creating the file if you have none. That is the whole setup for every tool following the [AGENTS.md](https://agents.md) convention, which is now a Linux Foundation standard rather than any one vendor's format:

**AGENTS.md**

```md
## theui-svelte

Before writing or changing code that uses a theui-svelte component, read
`node_modules/theui-svelte/AGENTS.md`.
```

Commit whichever you choose, so everyone on the project works from the same rules. One tool needs a line of its own, and it is the one most Svelte developers use. That is next.

## Claude Code

Claude Code reads `AGENTS.md` only as a **fallback**. If a `CLAUDE.md` exists in the directory or any directory above it, `AGENTS.md` is ignored completely — so a project that already has a `CLAUDE.md` never sees a root `AGENTS.md` at all.

This is the one case convention does not cover, so the command writes an extra line into `CLAUDE.md` itself: an `@` import, which Claude Code resolves and pulls in rather than looking up later. By hand it is one line at the top, and nothing needs updating when you upgrade the library:

**CLAUDE.md**

```md
@node_modules/theui-svelte/AGENTS.md

# My project
...your own notes...
```

> **Note:** If you have no `CLAUDE.md` at all, a root `AGENTS.md` is picked up on its own and there is nothing more to do — which is why the command creates that file but never creates a `CLAUDE.md` in a project that does not use Claude Code.

## Every Other Tool

Most tools read the root `AGENTS.md` directly. The ones that keep their own instructions file do not need a second copy of the rules — a single line naming the path is enough, and it will not go stale. `npx theui ai` writes that line into each of the files below that your project already has, so this table is both what it does and what to do yourself if you would rather.

| Tool | Where its instructions live | What to do |
| --- | --- | --- |
| Codex | `AGENTS.md` | Nothing. Reads the root file, and a nested one wins for files beside it. |
| Cursor | `AGENTS.md` | Nothing. A root file carries the same weight as a project rule. |
| GitHub Copilot | `AGENTS.md` | Nothing, in the editor and in the coding agent. |
| VS Code, repository-wide | `.github/copilot-instructions.md` | Optional. VS Code already reads `AGENTS.md`; use this when you also want always-on rules of your own. |
| Cursor, path-scoped rules | `.cursor/rules/*.mdc` | Optional. The extension must be `.mdc` — a plain `.md` in that folder is skipped. |
| Claude Code | `CLAUDE.md` | Add `@node_modules/theui-svelte/AGENTS.md`. See [above](#claude-code). |
| Gemini CLI | `GEMINI.md` | Add a line naming `node_modules/theui-svelte/AGENTS.md`. |
| Aider | `.aider.conf.yml` | Add `node_modules/theui-svelte/AGENTS.md` under `read:`, since Aider needs the file named explicitly. |
| Windsurf, Zed, Junie, Jules, Devin, Amp | `AGENTS.md` | Nothing. |

For any file in the middle column, this is all it takes:

**Pointing another instructions file at the rules**

```md
Follow the conventions in node_modules/theui-svelte/AGENTS.md when writing
theui-svelte components.
```

Tools change quickly, and this table will drift. The root `AGENTS.md` is the part that keeps working: it is a published standard, not a per-vendor setting.

## The Stylesheet Is Two Lines

Tailwind CSS v4 finds classes by scanning files, and it skips `node_modules`. Until version 3.1.0 that meant a third line in your CSS pointing Tailwind back at the package, and forgetting it rendered every component unstyled with nothing logged — the single most common report that the library was broken.

The package registers its own markup now, so there is nothing to remember:

**./src/app.css**

```diff
     @import 'tailwindcss';
+    @import 'theui-svelte/style';
```

> **Note:** A project carrying the old `@source "../node_modules/theui-svelte";` line is fine — it is redundant now rather than harmful, and can be deleted whenever convenient. If components still render unstyled, the thing to check is that `@import 'theui-svelte/style'` is there at all, because that import is how Tailwind reaches the library.

## Fetch The Documentation As Markdown

Rendered HTML costs an agent a great deal of context for very little content, so every page here is published as Markdown too. These addresses are per library, which leaves room for others to be published beside this one.

- [`/svelte/llms.txt`](https://www.theui.dev/svelte/llms.txt) — the index. Every page with a one-line description, preceded by the install steps and the rules most often got wrong. Small enough to paste into a prompt.

- [`/svelte/llms-full.txt`](https://www.theui.dev/svelte/llms-full.txt) — the whole set in one file. Thorough, and large: for a tool that indexes the library once rather than on every request.

- `/docs/<name>.md` — a single page. Append `.md` to any documentation address, as in [`/docs/button.md`](https://www.theui.dev/docs/button.md). This is the one to reach for when an agent needs one component, because it is a single request.

- [`/llms.txt`](https://www.theui.dev/llms.txt) — the root index, which only says which libraries exist and where each one's index is.

Every page also advertises its Markdown twin with an `alternate` link tag, so a crawler finds it without being told. The props table survives the conversion, so a twin carries the same API reference as the page you are reading rather than a summary of it.

## What The Rules Actually Say

These are the things a model gets wrong when it reasons from component names alone. They are in `AGENTS.md` and in [the index](https://www.theui.dev/svelte/llms.txt), and they are worth knowing yourself.

- Deep import paths are flat. `AccordionItem` sits in the `Accordion` folder but imports from `theui-svelte/AccordionItem.svelte`, never from a nested path.

- Content holes are Svelte 5 snippets. There are no slots, no `export let`, no `createEventDispatcher` and no stores anywhere in the library.

- The `standalone` prop of [`Accordion`](https://www.theui.dev/docs/accordion) reads backwards. Its default of `true` means only one panel opens at a time; it does not mean an item works on its own.

- [`Tabs`](https://www.theui.dev/docs/tabs) defaults to `pills` rather than `tabs`, and a `Tab` pairs with its `TabPanel` by matching `value` instead of by order.

- There is no `Textarea` component. It is an [`Input`](https://www.theui.dev/docs/input) whose `type` is `textarea`.

- [`Tooltip`](https://www.theui.dev/docs/tooltip) and [`Notification`](https://www.theui.dev/docs/notification) are page-level singletons. Render each once in your layout; a second instance doubles the listeners.

- [`Popover`](https://www.theui.dev/docs/popover) takes the `id` of its trigger as a string, not a snippet, and stays silent when that id does not resolve.

- A [`Table`](https://www.theui.dev/docs/table) built from objects needs `keys` to fix the column order. Without it the rows render no cells, and nothing is logged.

- `DropdownItem` belongs to [`Dropdown`](https://www.theui.dev/docs/dropdown). Inside a `NavDropdown` use `NavLink`: they are two separate context systems, and mixing them throws.

- Some children throw outside their parent rather than falling back: `Tab`, `TabPanel`, `Slide`, `DropdownItem`, and the whole [`Navbar`](https://www.theui.dev/docs/navbar) family.

Build with the [semantic color tokens](https://www.theui.dev/docs/colors) and pair every color with a `dark:` counterpart, and generated pages follow your theme instead of hard-coding one.

---

Source: https://www.theui.dev/docs/cli

# CLI

The library ships a command line tool with one job: hand your coding assistant the rules it cannot guess. It is a single command, it writes a pointer rather than a copy, and everything it does can be undone by deleting a few lines.

## The Command

Run it in your project root, after `theui-svelte` is installed:

**Your project root**

```bash
npx theui ai
```

It reports what it touched, so you can see exactly what changed:

**Output**

```bash
  theui-svelte · AI rules

  ✓ AGENTS.md                        created    the AGENTS.md standard
  ✓ CLAUDE.md                        updated    Claude Code
  ✓ .github/copilot-instructions.md  updated    GitHub Copilot

  Your agent now reads node_modules/theui-svelte/AGENTS.md.
  Start a new agent session to pick it up.
```

Start a new session in your assistant afterwards. Instruction files are read when a session begins, so one already running will not see the change.

## Why A Command At All

The rules themselves ship inside the package, at `node_modules/theui-svelte/AGENTS.md`. The problem is that no coding agent reads them from there. Every one of them looks for instructions in a **project root**, and none promises to look inside `node_modules`.

So something has to connect the two. The command writes that connection into the files your tools already read — which is work you can also do by hand in about a minute, and [AI coding assistants](https://www.theui.dev/docs/ai-assistants#tools) shows how.

## What It Writes

A short block, between two HTML comment markers, naming the path to the rules:

**AGENTS.md**

```md
<!-- theui-svelte:start -->

## theui-svelte v3.1.0

This project builds its UI with **theui-svelte**, a Svelte 5 component library on
Tailwind CSS v4.

Before writing or changing any code that uses one of its components, read:

`node_modules/theui-svelte/AGENTS.md`

That file carries what the type definitions cannot - which component to reach for,
how the compound families compose, which children throw without their parent, and
the gotchas that fail silently rather than erroring.

Prop names and types are in the bundled `.d.ts` files, so trust those for the shape
of a component and the file above for the intent behind it.

Documentation as Markdown: https://www.theui.dev/svelte/llms.txt

<!-- theui-svelte:end -->
```

A pointer, not a copy, for two reasons. It cannot overwrite rules you wrote yourself, because it only ever adds its own block to the end of a file. And it cannot go stale: upgrading the library upgrades what your assistant reads, with nothing to refresh.

In a `CLAUDE.md` the block carries one extra line, `@node_modules/theui-svelte/AGENTS.md`, because Claude Code resolves that as a real import and pulls the rules in rather than looking them up later.

## Which Files It Touches

Only the tools your project shows a sign of. A `CLAUDE.md` written into a project that does not use Claude Code would be noise, so the command does not create one.

| File | Tool | When |
| --- | --- | --- |
| `AGENTS.md` | Codex, Cursor, Copilot, Zed, Aider, Jules | Always. Created if missing, since one file has to carry the pointer. |
| `CLAUDE.md` | Claude Code | If the file already exists. |
| `.github/copilot-instructions.md` | GitHub Copilot in VS Code | If the file already exists. |
| `.cursor/rules/theui-svelte.mdc` | Cursor | If a `.cursor` folder exists. |
| `.windsurf/rules/theui-svelte.md` | Windsurf | If a `.windsurf` folder exists. |
| `GEMINI.md` | Gemini CLI | If the file or a `.gemini` folder exists. |

`AGENTS.md` alone covers most of the ecosystem: it is a published convention rather than one vendor's format, and Claude Code falls back to it when a project has no `CLAUDE.md`. The rest of the table is for the tools that keep their own file.

## Options

| Option | What it does |
| --- | --- |
| *none* | Writes the pointer. This is the normal choice. |
| `--copy` | Copies the rules to `.theui-svelte/AGENTS.md` and points there instead. For a project that would rather commit the rules, or one whose agents run before anyone has installed anything. |
| `--dry` | Prints what would change and writes nothing. Works with either of the above. |
| `-h`, `--help` | The usage summary. |
| `-v`, `--version` | The installed library version. |

Look before you leap, if you would rather:

**See the changes without making them**

```bash
npx theui ai --dry
```

The command is also published as `npx theui-svelte ai`, which is the same tool under the package's own name. Use whichever reads better; `theui` is the one these pages use.

## Running It Again, And Undoing It

Re-running is safe and is the right thing to do after an upgrade. The block names the version it was written for, so the command replaces the old one in place rather than adding a second copy, and tells you nothing changed when nothing needed to:

**Already current**

```bash
  theui-svelte · AI rules

  · AGENTS.md  unchanged  the AGENTS.md standard
  · CLAUDE.md  unchanged  Claude Code

  Everything was already current for v3.1.0.
```

To undo it, delete the block between `<!-- theui-svelte:start -->` and `<!-- theui-svelte:end -->`. Nothing else in the file is ever touched, and the two files the command owns outright — the Cursor and Windsurf rules — can simply be deleted.

## When It Cannot Find The Library

The command points at the installed package, so it needs the package to be there. If it is not, it says so rather than writing a path that leads nowhere:

**Nothing installed yet**

```bash
  theui-svelte is not installed here.

  Run npm i theui-svelte first.
  Or pass --copy to write the rules into the project rather than
  pointing at the installed package.
```

> **Note:** `npx theui ai` resolves the tool from your own `node_modules`, which is why the library has to be installed first. In a workspace it looks upwards as well, so a dependency hoisted to the repository root is found from a package inside it.

It also stops if there is no `package.json` beside you, which almost always means the terminal is in the wrong folder.

---

Source: https://www.theui.dev/docs/colors

# Colors and Branding

One of the main features of theui-svelte components library is its customizable color options, allowing you to maintain brand identity and ensure consistent theming efficiently.

On top of Tailwind's own palette, the library defines a set of brand and status colors in a `@theme` block. They behave exactly like Tailwind's native color classes, shades included, and every component reads from them, so changing one variable restyles the whole library.

## Available Color Classes

The library exposes these colors as utility classes you can use in your own markup. Here is the full list:

#### Shaded Colors

        50
        100
        200
        300
        400
        500
        600
        700
        800
        900
        950

> **Note:** **[T]** = **Type** (e.g., `bg`, `text`, `border`, `fill`, etc.) **[S]** = **Shade** (e.g., 50, 100-900, 950) **Class example**: `bg-brand-500`, `text-brand-600`, `bg-error-400` The foreground colors have no shades: `text-on-brand`, `text-default`, `text-muted`.

#### Non-shaded Colors

|  | Light mode | Dark mode |  |
| --- | --- | --- | --- |
| {colorData.propertyName} | {color.title} ({color.className}) {color.variable} |  |  |

## What Each Color Controls

Before changing anything, it helps to know which token does what. Most of the library runs on a handful of them.

| Token | Where you see it |
| --- | --- |
| `--color-brand-*` | Primary buttons, the active tab, the selected day of a calendar, the filled part of a range, wizard steps, links and every focus ring. Shade `500` carries most of it, with `600` for hover and `300` for lighter accents. |
| `--text-color-on-brand` | The text and icons that sit on top of a brand background. It is one value, not a scale. |
| `--color-error-*`, `info`, `success`, `warning` | Alerts, badges, notifications, and the states of a form field. |
| `--background-color-*` | Surfaces: the page (`primary`), cards, menus and panels (`secondary`), the layer above those (`tertiary`), and the inverted one (`alt`). |
| `--text-color-*` | Body text (`default`), secondary text such as helper text and placeholders (`muted`), and text on the inverted surface (`alt`). |

So a rebrand is usually two things: the brand scale, and the foreground that goes on top of it. Everything else follows.

## Rebrand In One Step

The library's own brand scale is nothing but aliases of Tailwind's rose palette. Point those eleven variables at another Tailwind palette and every component moves with it.

**./src/app.css**

```css
@import 'tailwindcss';
@import 'theui-svelte/style';

@theme {
  --color-brand-50: var(--color-indigo-50);
  --color-brand-100: var(--color-indigo-100);
  --color-brand-200: var(--color-indigo-200);
  --color-brand-300: var(--color-indigo-300);
  --color-brand-400: var(--color-indigo-400);
  --color-brand-500: var(--color-indigo-500);
  --color-brand-600: var(--color-indigo-600);
  --color-brand-700: var(--color-indigo-700);
  --color-brand-800: var(--color-indigo-800);
  --color-brand-900: var(--color-indigo-900);
  --color-brand-950: var(--color-indigo-950);
}
```

Your own palette works the same way, with values in place of the aliases. Any CSS color will do, though `oklch` is what Tailwind itself uses, and it keeps the steps between shades even.

**./src/app.css**

```css
@theme {
  --color-brand-500: oklch(0.62 0.19 264);
  --color-brand-600: oklch(0.55 0.19 264);
  /* ... and the rest of the scale */
}
```

**Where you put this matters.** The override has to come after `@import 'theui-svelte/style'`. Both declarations land in the same layer, so the later one wins; put it above the import and nothing changes.

**Check the contrast while you are here.** `--text-color-on-brand` is white, which suits a mid or dark brand color. Pick a light one, such as amber or lime, and every primary button becomes white on light, which nobody can read. Set the foreground with the brand, aiming for at least 4.5:1 against shade `500`; the [accessibility guide](https://www.theui.dev/docs/accessibility) covers the targets.

**./src/app.css**

```css
@theme {
  --color-brand-500: var(--color-amber-400);
  --text-color-on-brand: #16161D;   /* dark text on a light brand */
}
```

## Colors In Dark Mode

Surfaces and text colors are declared twice: once for light mode in `@theme`, and again inside `.dark` in the base layer. The base layer comes after the theme layer, so the dark values win whenever the `dark` class is on the page. An override in `@theme` alone therefore changes light mode only, and the change appears to vanish the moment you switch to dark.

To change both, write both. Surfaces and text go in two places; the brand and status scales are not re-declared for dark mode, so those need the `@theme` block only.

**./src/app.css**

```css
@import 'tailwindcss';
@import 'theui-svelte/style';

@theme {
  /* light mode, and the brand scale for both modes */
  --color-brand-500: var(--color-indigo-500);
  --background-color-primary: #ffffff;
  --background-color-secondary: #f4f4f7;
  --text-color-muted: #5a5a63;
}

@layer base {
  .dark {
    /* dark mode only */
    --background-color-primary: #0b0b10;
    --background-color-secondary: #14141b;
    --text-color-muted: #9b9ba3;
  }
}
```

The `dark` class itself belongs on the `<html>` element. The [DarkMode](https://www.theui.dev/docs/dark-mode) component puts it there and remembers the choice.

## Reskin Every Surface At Once

Behind the surface and text tokens sit eight raw values. Six are the surfaces, three for light and three for dark: every `bg-*` token is built from those, and `text-default` and `text-alt` borrow from them too. That makes them the shortest way to change the feel of a whole app without touching a single component.

The other two are `--text-muted-on-light` and `--text-muted-on-dark`, which feed `--text-color-muted`, the color of the `text-muted` class: helper text, placeholders, timestamps and other secondary text. They stand apart from the six because muted text is not a surface. It has to stay readable against the page while still sitting back from the body text, and the value that does that in light mode is not the one that does it in dark mode. The library picks the right one for the current mode, so you set both and think no further about it.

**./src/app.css**

```css
:root {
  --theui-light1: #FFFFFF;   /* the page */
  --theui-light2: #F4F4F7;   /* cards, menus, panels */
  --theui-light3: #E8E8EE;   /* the layer above those */
  --theui-dark1: #0B0B10;    /* the page, in dark mode */
  --theui-dark2: #14141B;
  --theui-dark3: #1C1C26;
  --text-muted-on-light: #5A5A63;
  --text-muted-on-dark: #9B9BA3;
}
```

These are plain CSS variables rather than theme tokens, so they build no utilities of their own; they only feed the tokens above. That also makes them simpler to override than a theme token: they live on `:root`, so a `:root` block of your own in `app.css` replaces them, with no `@theme` and no separate rule for dark mode. Redefine them after the import, as with everything else on this page.

Set only the ones you want to move. Anything you leave out keeps the library's value, so changing `--text-muted-on-dark` alone is a perfectly good edit.

## Modify Existing Colors

You can override the library's default colors by assigning new values to the corresponding CSS theme variables:

**./src/app.css**

```css
@theme {
  /* Modify brand primary colors */
  --color-brand-50: #f0f9ff;
  --color-brand-100: #e0f2fe;
  --color-brand-200: #bae6fd;
  --color-brand-300: #7dd3fc;
  --color-brand-400: #38bdf8;
  --color-brand-500: #0ea5e9;
  --color-brand-600: #0284c7;
  --color-brand-700: #0369a1;
  --color-brand-800: #075985;
  --color-brand-900: #0c4a6e;
  --color-brand-950: #082f49;

  /* Modify background colors */
  --background-color-primary: #ffffff;
  --background-color-secondary: #f8fafc;

  /* Modify text colors */
  --text-color-default: #1e293b;
  --text-color-muted: #64748b;
}
```

## Add New Color

Colors of your own go in the same `@theme` block, and the name you choose decides which utilities Tailwind builds from it. Get the prefix wrong and nothing is reported: the variable is defined, the class simply never exists.

#### Add Shaded Colors

A name under `--color-*` gives you the whole family of utilities for that color: background, text, border, ring, fill, and the rest.

**./src/app.css**

```css
@theme {
  --color-accent-50: #f0f9ff;
  --color-accent-100: #e0f2fe;
  /* ... add more shades as needed */
  --color-accent-500: #0ea5e9;
  --color-accent-950: #082f49;
}
```

Use them as `bg-accent-500`, `text-accent-300`, `border-accent-700`, `ring-accent-500`.

#### Add Non-shaded Colors

A single color for one purpose belongs under the namespace of the property it serves: `--background-color-*` for backgrounds and `--text-color-*` for text, the same namespaces this library uses for its own surfaces. `--background-*` and `--text-*` are **not** color namespaces, and `--text-*` in particular belongs to font sizes, so a color defined there quietly produces nothing.

**./src/app.css**

```css
@theme {
  /* Right: these build bg-surface and text-highlight */
  --background-color-surface: #f8fafc;
  --text-color-highlight: #4338ca;

  /* Wrong: no utility comes out of either of these */
  --background-surface: #f8fafc;
  --text-highlight: #4338ca;
}
```

Then write `bg-surface` and `text-highlight` as you would any other utility. The same pattern holds for `--border-color-*`, `--fill-*` and `--ring-color-*`.

## Remove A Color

To completely remove a color from your theme, set its namespace to initial:

**./src/app.css**

```css
@theme {
  /* Remove the warning color palette */
  --color-warning-*: initial;

  /* Remove specific non-shaded colors */
  --background-color-tertiary: initial;
  --text-color-alt: initial;
}
```

This will remove all the `warning` color classes, `bg-tertiary` and `text-alt` class from the application!

## Available Color Palette

This is what `theui-svelte/style.css` defines. The brand and status scales are aliases of Tailwind's own palettes, which is why pointing one at another palette takes a single line each.

**theui-svelte/style.css**

```css
:root {
  /* The raw surface values every light and dark background is built from */
  --theui-light1: #FFFDFD;
  --theui-light2: #F5F3F3;
  --theui-light3: #EBE9E9;
  --theui-dark1: #16161D;
  --theui-dark2: #1E1E26;
  --theui-dark3: #26262F;
  --text-muted-on-light: #636369;
  --text-muted-on-dark: #A1A1AA;
}

@theme {
  /* Brand: 50 to 950, aliased to Tailwind's rose scale */
  --color-brand-50: var(--color-rose-50);
  --color-brand-100: var(--color-rose-100);
  --color-brand-200: var(--color-rose-200);
  --color-brand-300: var(--color-rose-300);
  --color-brand-400: var(--color-rose-400);
  --color-brand-500: var(--color-rose-500);
  --color-brand-600: var(--color-rose-600);
  --color-brand-700: var(--color-rose-700);
  --color-brand-800: var(--color-rose-800);
  --color-brand-900: var(--color-rose-900);
  --color-brand-950: var(--color-rose-950);

  /* What text and icons use on top of a brand background */
  --text-color-on-brand: #FFFFFF;

  /* Status colors, each aliased the same way across all 11 shades */
  --color-error-50 ... --color-error-950:   var(--color-red-*);
  --color-info-50 ... --color-info-950:     var(--color-sky-*);
  --color-success-50 ... --color-success-950: var(--color-green-*);
  --color-warning-50 ... --color-warning-950: var(--color-yellow-*);

  /* Text */
  --text-color-default: var(--theui-dark1);
  --text-color-muted: var(--text-muted-on-light);
  --text-color-alt: var(--theui-light1);

  /* Surfaces */
  --background-color-primary: var(--theui-light1);
  --background-color-secondary: var(--theui-light2);
  --background-color-tertiary: var(--theui-light3);
  --background-color-alt: var(--theui-dark1);
}

/* Dark mode swaps the same names, so every component follows */
@layer base {
  .dark {
    --text-color-default: var(--theui-light2);
    --text-color-muted: var(--text-muted-on-dark);
    --text-color-alt: var(--theui-dark1);

    --background-color-primary: var(--theui-dark1);
    --background-color-secondary: var(--theui-dark2);
    --background-color-tertiary: var(--theui-dark3);
    --background-color-alt: var(--theui-light2);
  }
}
```

The status scales are written out in full in the stylesheet; they are shortened here because every shade follows the same pattern. Read the file in the [GitHub repository](https://github.com/mbparvezme/theui-svelte) for the literal source.

---

Source: https://www.theui.dev/docs/global-defaults

# Global Defaults

Square corners everywhere, or no animation anywhere, without repeating the same prop on every component. setTheuiDefaults sets the value once and every component falls back to it.

## Setting The Defaults

Call `setTheuiDefaults` once with the values you want. Every component that has the matching prop uses it instead of its own built-in default.

**src/routes/+layout.svelte**

```html
<script module lang="ts">
  import { setTheuiDefaults } from "theui-svelte/function";

  setTheuiDefaults({
    rounded: false,
    animationSpeed: "fast"
  });
</script>

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

{@render children()}
```

Keys you leave out keep their built-in value, so you only name what you want to change. Calling it again merges the new keys into the old ones rather than replacing them.

## Where To Call It

Call it **once, at module scope**: a `<script module>` block, or a plain module your app imports. The value is a single setting shared by everything the process renders.

> **Note:** Do not call it while a page renders, so not inside a `load` function, an `$effect`, or a component's instance script. On the server one process answers many visitors at once, so a value set during one visitor's render would reach another visitor's page.

Pass plain, fixed values for the same reason. A default that depends on the request, such as a per-tenant theme, does not belong here; use the `rounded` prop on a [Form](https://www.theui.dev/docs/form), a [Fieldset](https://www.theui.dev/docs/fieldset) or the components themselves.

## What You Can Set

| Key | Values | Applies to |
| --- | --- | --- |
| `rounded` | `true`, `false` | Every component with a `rounded` prop |
| `animationSpeed` | `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"`, `"faster"` | Every component with an `animationSpeed` prop |
| `shadow` | `"none"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"` | `Button`, `Card` and `Popover` |
| `reset` | `true`, `false` | Every form component |

`rounded` is an off switch, and the one key that is not a fallback. `false` squares off every component whatever its `rounded` prop says, so `<Badge rounded="full">` and a `Form` with `rounded="lg"` both come out square. After that only a class of your own can round a corner. `true`, or leaving the key out, keeps every `rounded` prop working as usual.

There is no global radius *size*, because the right value differs per component: a Badge is a pill, a Card is not. To give a group of fields one radius, set `rounded` on the [Form](https://www.theui.dev/docs/form) or [Fieldset](https://www.theui.dev/docs/fieldset) around them.

`size` and `variant` are deliberately not here. They mean different things on different components. `size` is `"default"` on an Accordion, `"xs"` to `"xl"` on a Button and a number on an Svg, while `variant` is `"card"` on an Alert, `"rect"` on a Skeleton and `"pills"` on Tabs. One value could not mean the same thing everywhere. Set those on a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset), which cover a whole group of fields at once.

## What Wins

`animationSpeed`, `shadow` and `reset` are the last fallback, so anything you set closer to the component beats them. From strongest to weakest:

- The prop on the component itself

- The nearest [Fieldset](https://www.theui.dev/docs/fieldset)

- The [Form](https://www.theui.dev/docs/form) around it

- `setTheuiDefaults`

- The component's own built-in default

**A fallback: the nearest one wins**

```html
<!-- setTheuiDefaults({ animationSpeed: "slow" }) -->

<Modal>Slow, from the global default</Modal>
<Modal animationSpeed="fast">Fast, the prop wins</Modal>

<Form animationSpeed="normal">
  <Input name="a">Normal, from the Form</Input>

  <Fieldset animationSpeed="faster">
    <Input name="b">Faster, the Fieldset is nearer</Input>
  </Fieldset>
</Form>
```

`rounded` does not work that way. It is an off switch, so it beats every `rounded` prop rather than falling behind them:

**The switch: nothing beats it but your own class**

```html
<!-- setTheuiDefaults({ rounded: false }) -->

<Button>Square</Button>
<Button rounded="full">Square too, the switch beats the prop</Button>
<Badge rounded="2xl">Square too</Badge>

<Form rounded="lg">
  <Input name="a">Square too</Input>
</Form>

<!-- Only your own class still rounds a corner -->
<Button class="rounded-lg">Rounded</Button>
```

## Components That Keep Their Shape

A few components are built around a shape rather than merely decorated with one, so their built-in default is not `"md"`. Turning the switch off squares these as well:

| Built-in default | Components |
| --- | --- |
| `rounded="full"` | AvatarGroup, Badge, Chips, Progress, Qab, QabItem, Toggle |
| `rounded="xl"` | Popup |
| `rounded="lg"` | Tooltip |
| `rounded="sm"` | Checkbox |
| `animationSpeed="fast"` | Accordion, Collapse, Drawer, Dropdown, Modal, Navbar |

So `setTheuiDefaults({ rounded: false })` does square off a Badge and a Toggle, because you asked for it everywhere. Leaving `rounded` out keeps each of these as it is.

The switch only covers the `rounded` prop. A shape a component needs in order to read correctly stays as it is: the ring of a [Spinner](https://www.theui.dev/docs/spinner), the dot on an [Avatar](https://www.theui.dev/docs/avatar), the handle of a [Range](https://www.theui.dev/docs/range), the step markers of a [FormWizard](https://www.theui.dev/docs/form-wizard) and the panels of the date and time pickers. Restyle those with a class where you need to.

## The Type

The argument is the `CORE` type, and every key is optional.

**Type**

```ts
import type { CORE } from "theui-svelte/type";

type CORE = {
  rounded?: boolean;
  animationSpeed?: ANIMATE_SPEED;
  reset?: boolean;
  shadow?: SHADOW;
};
```

See the [Types](https://www.theui.dev/docs/types) page for `ANIMATE_SPEED` and `SHADOW`.

---

Source: https://www.theui.dev/docs/installation

# Installation

Install the **theui-svelte** component library in your project or start a new project with the boilerplate template. Install it to build fast and deliver faster.

## Installation

**Requirements:** Svelte 5.57.1 or newer, Tailwind CSS v4 and Node.js 22.12 or newer.

Follow one of the two methods to install the component library:

- Github boilerplate.

- Manual installation.

The form styles come with the package, so there is no Tailwind plugin to add by hand. The typography plugin is not included: install `@tailwindcss/typography` yourself if your own pages use its `prose` classes.

## Use Github Boilerplate

To install the starter template clone [this Github repo](https://github.com/mbparvezme/theui-svelte-starter) from your terminal using the following commands, replacing `my-app` with your desired project name.

**Clone from Github**

```bash
# Clone the project
git clone https://github.com/mbparvezme/theui-svelte-starter.git my-app
# Navigate to the project directory
cd my-app
# Install node modules
npm install
# Run the application
npm run dev
```

## Manual Installation

Easily add theui-svelte to your project via a GitHub boilerplate or manual installation. For manual setup:

- Install Sveltekit with TailwindCSS and theui-svelte

- Configure Tailwind CSS by updating the `./src/app.css` file.

2.1 Install

**Install SvelteKit**

```bash
# Create a SvelteKit project
# When prompted "What would you like to add to your project?", select tailwindcss
npx sv create my-app
cd my-app

# Add Tailwind CSS - if you didn't select tailwindcss during the project creation, run:
# npx sv add tailwindcss

# Install theui-svelte
npm install theui-svelte
```

2.2 Configuration

To integrate `theui-svelte` with your project, add the following lines to your `./src/app.css` file:

**./src/app.css**

```diff
     @import 'tailwindcss';
+    @import 'theui-svelte/style';
```

That's it! You're ready to start building your awesome project. Now, run your application with:

**Run the development server**

```bash
# Run SvelteKit project
npm run dev
```

## Turn On AI Support

If you build with a coding assistant, one command hands it the rules it cannot guess. Run it in your project root once the library is installed:

**Point your coding agent at the library**

```bash
npx theui ai
```

It looks for the instruction files your tools already use — `AGENTS.md`, `CLAUDE.md`, Copilot, Cursor, Windsurf, Gemini — writes a short block into each one naming the path to the rules that ship inside the package, and prints back which files it touched. It points rather than copies, so it cannot overwrite rules you wrote yourself, and upgrading the library upgrades what your assistant reads.

Skipping this changes nothing about how the library works, only how much your assistant gets right first time. The [CLI reference](https://www.theui.dev/docs/cli) covers every option, and [AI coding assistants](https://www.theui.dev/docs/ai-assistants) covers what the rules actually say.

## Your First Component

Components are named exports of `theui-svelte`, so you import the ones you use and nothing else. Drop this into a page to see that everything is wired up: the button raises a notification, which means the components, the styles and the store are all working.

**+page.svelte**

```svelte
<script>
  import { Button, Notification, notify } from "theui-svelte"
</script>

<Notification position="top-end" />

<Button onclick={() => notify("It works", "success")}>Say hello</Button>
```

Two more entry points come with the package: `theui-svelte/type` for the [TypeScript types](https://www.theui.dev/docs/types), and `theui-svelte/function` for helpers such as `notify` and `sanitize`.

## Dark Mode

Dark mode is driven by a `dark` class on the `<html>` element. The stylesheet you imported brings the variant with it, so there is nothing to add to your Tailwind setup, and every component already carries its dark styles.

Put the [`DarkMode`](https://www.theui.dev/docs/dark-mode) component somewhere in your layout and it does the rest: it follows the operating system until someone chooses for themselves, then remembers that choice.

## Upgrading From Version 2

Version 3 is a break with version 2. These are the changes most likely to touch your code:

- Svelte 5.57.1 or newer and Node.js 22.12 or newer are required.

- The brand colors were renamed: `brand-primary-50` ... `brand-primary-950` are now `brand-50` ... `brand-950`, and `text-on-brand-primary` is now `text-on-brand`. Rename them in your markup, and rename `--color-brand-primary-*` and `--text-color-on-brand-primary` if you overrode them.

- The second brand color is gone. `brand-secondary-*` and `text-on-brand-secondary` no longer exist; use any Tailwind color, or one of your own, in their place.

- The raw surface values are prefixed now: `--light1` ... `--dark3` are `--theui-light1` ... `--theui-dark3`. This only matters if you overrode them; `bg-primary`, `bg-secondary` and `bg-tertiary` are unchanged.

- String props such as `helperText`, a `title` or a `label` render as plain text now. Pass a snippet, or write the content inside the component, where you used to pass markup.

- `Tab` and `TabPanel` each need a `value`, and a tab opens the panel that carries the same one.

- `Toggle` uses `checked` for a checkbox and `group` for a radio; `value` is now only the value of the input.

- The `reverse` attribute of `Checkbox`, `Radio` and `Toggle` is now `labelPosition`.

- `Button`, `QabItem` and `NavBrand` no longer invent an `aria-label`, so give icon-only controls an `ariaLabel` of your own.

- The `position` setting of `notify()` moved to the `position` prop of the `Notification` component.

- `style.css` no longer loads `@tailwindcss/typography`.

The changelog in the [GitHub repository](https://github.com/mbparvezme/theui-svelte) lists every change, including the rewritten `Slider` and the new components.

---

Source: https://www.theui.dev/docs

# theui-svelte: Svelte 5 Component Library

theui-svelte is a component library for Svelte 5, built on Tailwind CSS v4. It covers the pieces most applications need, with the accessibility and the theming already done.

## Introduction

**theui-svelte** is TheUI's component library for Svelte, built on Tailwind CSS. The components carry their own ARIA wiring and keyboard behavior, read your brand colors from your CSS, and merge any class you pass with tailwind-merge, so overriding a default does not mean fighting it.

It needs Svelte 5.57.1 or newer, Tailwind CSS v4 and Node.js 22.12 or newer. The [installation guide](https://www.theui.dev/docs/installation) takes you from an empty project to your first component.

## Features

The main features of the component library are:

- **Written for Svelte 5** - components are built with runes, and take snippets wherever you need to pass markup rather than text.

- **Accessible from the start** - roles and names, keyboard support, focus handling and reduced motion are part of each component. The [accessibility guide](https://www.theui.dev/docs/accessibility) sets out what is handled and what is left to you.

- **Yours to style** - every component takes `class`, merged with [tailwind-merge](https://github.com/dcastil/tailwind-merge), so your own classes win instead of fighting the defaults.

- **Your colors, not ours** - components read the [brand palette](https://www.theui.dev/docs/colors) from your CSS, in light and dark mode alike.

- **Dark mode with nothing to configure** - the stylesheet brings its own dark variant, and the [DarkMode](https://www.theui.dev/docs/dark-mode) component remembers the choice.

- **Right to left** - layouts use logical properties, so [RTL](https://www.theui.dev/docs/rtl) works without a second stylesheet.

- **Typed throughout** - every prop has a type, listed on the [types page](https://www.theui.dev/docs/types).

- **Safe to render on the server** - nothing reaches for the browser while a page is being rendered.

## Components

 components,  form controls and  utilities, each with its own page of examples, a full list of props and an accessibility section.

###### UI COMPONENTS

-

###### FORM ELEMENTS

-

###### UTILITIES

-

## Where to Go Next

- [Installation](https://www.theui.dev/docs/installation) - the starter template, or a step by step setup of your own.

- [Colors and branding](https://www.theui.dev/docs/colors) - point the components at your palette.

- [Accessibility](https://www.theui.dev/docs/accessibility) - what the components handle, the keys they answer to, and what is left to you.

- [Types](https://www.theui.dev/docs/types) - every exported type, in alphabetical order.

- [Right to left](https://www.theui.dev/docs/rtl) and [z-index](https://www.theui.dev/docs/z-index) - two things worth knowing before you build a layout.

---

Source: https://www.theui.dev/docs/license

# License

MIT License

### Copyright  TheUI

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Source: https://www.theui.dev/docs/rtl

# RTL

Turn on right to left support for the whole site, or for single components only.

The **theui-svelte** components follow the direction of the page, so Arabic, Persian, Hebrew and Urdu layouts need no second stylesheet and no extra build. Set the direction and everything turns around with it: spacing, borders, icons that point somewhere, and the arrow keys inside the components that use them.

## RTL For The Entire Website

To enable RTL across your entire site, set the `dir` attribute on the `<html>` tag in `src/app.html`, next to the `lang` attribute for the language you are writing in. By default, **theui-svelte** components display in LTR (Left-to-Right) mode, but adding this attribute will switch all components and elements to RTL mode.

      Toggle Direction

**src/app.html**

```html
<!DOCTYPE html>
<html lang="ar" dir="rtl">
  <head>
    <!-- your head content -->
  </head>
  <body>
    <!-- your body content -->
  </body>
</html>
```

Keep `lang` and `dir` in step. Screen readers pick the voice from the language, so a page marked Arabic that is left as `dir="ltr"` reads badly even when it looks fine.

## RTL For A Component

If you want to apply RTL only to a part of the page, put `dir="rtl"` on an element around it. Components read the direction from where they sit, so anything inside that element turns around and the rest of the page is untouched. This is what you want for a quoted message, an address, or a form in another language.

```svelte
<!-- Only this part of the page is right to left -->
<div dir="rtl">
  <AnyComponent />
</div>
```

#### Accordion Example

The accordion below is currently `dir="{demoDirection}"`. Press the button to turn it around, and watch the heading, the arrow and the padding all follow.

      Toggle Direction

تتبع المكونات اتجاه الصفحة، لذلك لا تحتاج إلى ورقة أنماط ثانية.

```svelte
<div dir="rtl">
  <Accordion>
    <AccordionItem title="مرحبا بكم">
      <p>تتبع المكونات اتجاه الصفحة.</p>
    </AccordionItem>
  </Accordion>
</div>
```

## Writing Classes That Turn Around

The components are built with logical properties, the ones that talk about the start and the end of a line rather than left and right. Write your own classes the same way and they will follow the direction for free.

- Use `ms-*` and `me-*` instead of `ml-*` and `mr-*`.

- Use `ps-*` and `pe-*` instead of `pl-*` and `pr-*`.

- Use `start-*` and `end-*` instead of `left-*` and `right-*`.

- Use `text-start` and `text-end` instead of `text-left` and `text-right`.

- Use `border-s-*` and `border-e-*` instead of `border-l-*` and `border-r-*`.

**Both directions from one class**

```svelte
<!-- Turns around on its own -->
<div class="ms-4 border-s-2 ps-2 text-start">...</div>

<!-- Stays on the left, whatever the direction -->
<div class="ml-4 border-l-2 pl-2 text-left">...</div>
```

Left and right still have their uses. A logo, a chart or a video player that should never flip is better off with the physical class, and Tailwind also gives you the `rtl:` and `ltr:` prefixes when one case needs a rule of its own.

## What Turns Around By Itself

Layout follows the direction through CSS, but a few components also change how they behave, because reading right to left changes what "next" means.

- `DatePicker` and `TimePicker` swap their left and right arrow keys, so the keyboard moves with the reading order, and the month arrows of the calendar point the other way.

- `Slider` moves and swipes the other way, and its arrow keys follow.

- `Progress` fills from the right, and the track of a `Range` fills with it.

- `Drawer` slides in from the side you asked for, read as start and end rather than left and right.

- Smaller touches follow too: the dot on a `Badge`, and the way avatars overlap in an `AvatarGroup`.

These components read the direction from the element they are in, so `dir` anywhere above them is enough. A `Slider` reads it as it appears on the page, so give the element its direction before the slider renders rather than switching it afterwards.

Text you write yourself is still yours to mind. The default `Pagination` buttons read `"← Prev"` and `"Next →"`, and those arrows are characters rather than layout, so set `previousButton` and `nextButton` to the wording and the arrows your language expects.

---

Source: https://www.theui.dev/docs/types

# Types

Every type **theui-svelte** exports, in alphabetical order, with what it is for and which components use it.

## Importing Types

The types live in a subpath of their own, so you can pull in the ones you need without touching the components.

**Typescript**

```ts
import type { ANIMATE_SPEED, ROUNDED } from "theui-svelte/type"

let speed: ANIMATE_SPEED = "fast"
let corner: ROUNDED = "lg"
```

You rarely have to name them: passing a string straight to a prop is checked against these unions anyway. They earn their keep when you keep settings in a variable, take props of your own that you pass on to a component, or write a function that returns one.

Types vanish when your app is built. They are there for your editor and for `svelte-check`, and cost nothing at runtime.

## Accordion Size

Padding of an accordion heading and its body. Set on `Accordion`, where every `AccordionItem` inside picks it up.

**Typescript**

```ts
type ACCORDION_SIZE = "compact" | "default" | "large"
```

## Animation Speed Type

How long a transition takes. Nearly every component that moves takes it as `animationSpeed`, and `"none"` turns the transition off, which is the value to reach for when an element should not animate at all.

**Typescript**

```ts
type ANIMATE_SPEED = "none" | "slower" | "slow" | "normal" | "fast" | "faster"
```

## Avatar Size Type

Diameter of an `Avatar`. An `AvatarGroup` takes it too and hands it to every avatar inside, so the stack stays even.

**Typescript**

```ts
type AVATAR_SIZE = "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
```

## Avatar Status Type

The dot on an `Avatar`. Leave `status` unset for no dot at all.

**Typescript**

```ts
type AVATAR_STATUS = "online" | "offline" | "busy" | "away"
```

## Breadcrumb Data Type

One entry in the `data` array of a `Breadcrumb`. An entry without a `url` is rendered as plain text, which is what you want for the page you are already on.

**Typescript**

```ts
type BREADCRUMB_DATA = { text: string; url?: string }
```

## Button Size Type

Padding and text size of a `Button`, and of a `ButtonGroup` or `Pagination` that passes it down. `"auto"` drops the padding so the button takes the size of what you put inside it.

**Typescript**

```ts
type BUTTON_SIZE = "xs" | "sm" | "md" | "lg" | "xl" | "auto"
```

## Card Image Type

The `img` prop of a `Card`. Anything else you add to the object, such as `loading` or `width`, is passed to the `<img>` element.

**Typescript**

```ts
type CARD_IMAGE_TYPE = {
  class?: string
  src?: string
  alt?: string
  [key: string]: unknown
}
```

## Combobox Item Type

What you put in the `items` array of a `Combobox`. A bare string or number is both the value and the text; an object splits the two and can disable an entry or file it under a group heading.

**Typescript**

```ts
type COMBOBOX_ITEM = string | number | {
  value?: unknown
  text?: string
  disabled?: boolean
  // Options with the same group name are shown together under its heading
  group?: string
}
```

## Combobox Option Type

The same option once the component has filled in what you left out. This is the shape handed to the `option` snippet and to a `filter` function of your own, so every field is there to read.

**Typescript**

```ts
type COMBOBOX_OPTION = {
  value: unknown
  text: string
  disabled: boolean
  group?: string
}
```

## Core Type

The library wide defaults you pass to `setTheuiDefaults`. Every key is optional. `animationSpeed`, `shadow` and `reset` are fallbacks, so anything you set on a component, a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) beats them. `rounded` is an off switch instead: `false` squares off every component whatever its `rounded` prop says. See [Global defaults](https://www.theui.dev/docs/global-defaults).

**Typescript**

```ts
type CORE = {
  rounded?: boolean
  animationSpeed?: ANIMATE_SPEED
  reset?: boolean
  shadow?: SHADOW
}
```

## Divider Align Type

Where the label of a `Divider` sits along the line.

**Typescript**

```ts
type DIVIDER_ALIGN = "start" | "center" | "end"
```

## Divider Orientation Type

Which way a `Divider` runs. A vertical one needs a parent with a height, since it stretches to fill it.

**Typescript**

```ts
type DIVIDER_ORIENTATION = "horizontal" | "vertical"
```

## Divider Variant Type

The line style of a `Divider`.

**Typescript**

```ts
type DIVIDER_VARIANT = "solid" | "dashed" | "dotted"
```

## Dropdown Preload Type

When SvelteKit should start fetching the page behind a `DropdownItem` link: as the pointer arrives, as it is pressed, or not at all.

**Typescript**

```ts
type PRELOAD = false | "off" | "tap" | "hover"
```

## Dropzone Rejection Type

What `FileDropzone` hands to `onreject` for each file it turned away, with the reason it did. Remember that these checks run in the browser, so the server has to make them again.

**Typescript**

```ts
type DROPZONE_REJECTION = {
  file: File
  // Why the file was not accepted
  reason: "type" | "size" | "count"
}
```

A rejection is a good moment to tell people what went wrong, rather than letting the file disappear without a word.

```svelte
<FileDropzone
  accept="image/*"
  maxSize={2 * 1024 * 1024}
  onreject={(files) => files.forEach((f) => notify(`${f.file.name}: ${f.reason}`))}
/>
```

## Input Size Type

Height and text size of a form control. Set it on one field, or on the `Form` or `Fieldset` around a group of them, and every field inside follows.

**Typescript**

```ts
type INPUT_SIZE = "sm" | "md" | "lg" | "xl"
```

## Input Type

The `type` of an `Input`. `"textarea"` is in the list because the component renders a `<textarea>` for it instead of an `<input>`.

**Typescript**

```ts
type INPUT_TYPE =
  | "date" | "datetime-local" | "email" | "month" | "number"
  | "password" | "tel" | "text" | "time" | "url" | "week"
  | "search" | "textarea"
```

## Input Variant Type

How a form control is drawn: with a border around it, or flat with a line under it. A flat field floats its label by default.

**Typescript**

```ts
type INPUT_VARIANT = "bordered" | "flat"
```

## Navbar Breakpoint Type

The width at which a `Navbar` swaps its links for the mobile menu, given as the Tailwind screen it starts at. Pass `false` to `navBreakpoint` instead, and the links stay expanded at every width.

**Typescript**

```ts
type RESPONSIVE_NAV_ON = { sm: string; md: string; lg: string; xl: string }

type MOBILE_NAV_ON = keyof RESPONSIVE_NAV_ON   // "sm" | "md" | "lg" | "xl"
```

## Navbar Height Type

One of the four standard heights of a `Navbar`. The `height` prop also takes a class of your own, so this union is the shorthand rather than the limit.

**Typescript**

```ts
type NAV_HEIGHT_TYPES = "sm" | "md" | "lg" | "xl"
```

## Navbar Scroll Behavior Type

What a `Navbar` does as the page scrolls: nothing, stay pinned, shrink on the way down, hide on the way down, or shrink and then hide.

**Typescript**

```ts
type NAV_SCROLL_BEHAVIOR =
  | "default"
  | "fixed"
  | "shrinkOnScrollDown"
  | "hideOnScrollDown"
  | "shrinkAndHide"
```

## Notification Configuration

The third argument of `notify()`, which settles how that one notification behaves and looks. `removeAfter` is a number of milliseconds, or `false` to leave the notification until it is dismissed.

**Typescript**

```ts
type NOTIFY_CONFIG = {
  removeAfter?: number | false
  removeOnClick?: boolean
  rounded?: ROUNDED
  theme?: "default" | "soft" | "gradient"
  variant?: "card" | "borderTop" | "borderBottom" | "borderStart"
}
```

```svelte
notify("Saved", "success", { removeAfter: 6000, variant: "borderStart" })
```

Where the notifications appear is not set here: that is the `position` prop of the `Notification` component, which you place once in your layout.

## Notification Data Type

One notification as the library keeps it while it is on screen. You do not build this yourself, `notify()` does, but it is the shape you read if you render notifications your own way.

**Typescript**

```ts
type NOTIFICATION_DATA_TYPE = {
  msg: string
  type: NOTIFICATION_TYPE
  CONFIG: NOTIFY_CONFIG & { id: string }
  removing?: boolean
}
```

## Notification Position

Which corner or edge the `Notification` component stacks its messages in. It is set once, on the component, not per message.

**Typescript**

```ts
type NOTIFICATION_POSITION =
  | "top-end" | "top-center" | "top-start"
  | "bottom-end" | "bottom-center" | "bottom-start"
```

## Notification Types

The second argument of `notify()`, which picks the colour and the icon of the message.

**Typescript**

```ts
type NOTIFICATION_TYPE = "error" | "info" | "success" | "warning"
```

## OTP Type

What each box of an `OtpInput` accepts. `"number"` brings up the numeric keypad on a phone, and `"password"` hides the characters as they are typed.

**Typescript**

```ts
type OTP_TYPE = "text" | "number" | "password"
```

## Placement

Where a `Popover` or a `Tooltip` opens in relation to the element it belongs to. This one comes from [Floating UI](https://floating-ui.com), which does the positioning, so import it from `@floating-ui/dom` rather than from this library.

**Typescript**

```ts
import type { Placement } from "@floating-ui/dom"

type Placement =
  | "top" | "top-start" | "top-end"
  | "right" | "right-start" | "right-end"
  | "bottom" | "bottom-start" | "bottom-end"
  | "left" | "left-start" | "left-end"
```

It is a starting point, not a promise: when there is no room on that side, the element is flipped or shifted to somewhere it fits.

## Range Tick Type

One mark under a `Range`. A number puts a mark at that value; the object form labels it as well.

**Typescript**

```ts
type RANGE_TICK = number | { value: number; label?: string }
```

```svelte
<Range min={0} max={100} ticks={[0, { value: 50, label: "Half" }, 100]} />
```

## Rating Size Type

Size of the stars in a `Rating`.

**Typescript**

```ts
type RATING_SIZE = "sm" | "md" | "lg" | "xl"
```

## Rounded Type

How round the corners of a component are. `"none"` squares them off and `"full"` makes a pill, which is why a full-rounded button looks different from a full-rounded card.

**Typescript**

```ts
type ROUNDED = "sm" | "md" | "lg" | "xl" | "2xl" | "full" | "none" | undefined
```

## Select Data Type

One option in the `data` array of a `Select`. Leave `value` out and the `text` is submitted instead.

**Typescript**

```ts
type SELECT_DATA = { disabled?: boolean; text: string; value?: unknown }
```

## Shadow Types

Depth of the shadow under a `Card`, a `Button` or a `Popover`. `"inner"` puts the shadow inside the element rather than under it.

**Typescript**

```ts
type SHADOW = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "inner" | "none"
```

## Skeleton Animation Type

How a `Skeleton` shows that something is loading. Pick `"none"` for a still placeholder.

**Typescript**

```ts
type SKELETON_ANIMATION = "pulse" | "wave" | "none"
```

## Skeleton Variant Type

The shape of a `Skeleton`: a block, a circle for an avatar, or lines of text.

**Typescript**

```ts
type SKELETON_VARIANT = "rect" | "circle" | "text"
```

## Slider Direction Type

Which way a `Slider` moves. A vertical slider needs a height, and its arrow keys become up and down.

**Typescript**

```ts
type SLIDER_DIRECTION = "horizontal" | "vertical"
```

## Slider Effect Type

How one slide gives way to the next.

**Typescript**

```ts
type SLIDER_EFFECT = "slide" | "fade" | "zoom" | "flip" | "cube"
```

## Slider Responsive Type

Several `Slider` props take either one value for every screen, or a value per screen size. `perView`, `gap` and `peek` all work this way.

**Typescript**

```ts
type SLIDER_BREAKPOINT = "base" | "sm" | "md" | "lg" | "xl" | "2xl"

// A single value, or a value per screen size like { base: 1, md: 2, lg: 3 }
type SLIDER_RESPONSIVE<T> = T | Partial<Record<SLIDER_BREAKPOINT, T>>
```

```svelte
<Slider perView={{ base: 1, md: 2, lg: 3 }} gap={16} />
```

A screen size you leave out keeps the value of the size below it, so `base` is worth setting.

## Spinner Size Type

Size of a `Spinner`.

**Typescript**

```ts
type SPINNER_SIZE = "xs" | "sm" | "md" | "lg" | "xl"
```

## Spinner Variant Type

Which spinner is drawn: a turning ring, three bouncing dots, or a pinging circle.

**Typescript**

```ts
type SPINNER_VARIANT = "ring" | "dots" | "ping"
```

## Table Data Type

The `data` prop of a `Table`: either an array of rows of plain strings, or an array of objects, in which case `keys` decides which fields are shown and in what order.

**Typescript**

```ts
type TABLE_DATA = string[] | Record<string, unknown>[]
```

## Wizard Step Info Type

What a `FormStep` tells the `FormWizard` around it. A step whose `validate` returns `false` holds the wizard where it is, and one marked `optional` can be skipped.

**Typescript**

```ts
type WIZARD_STEP_INFO = {
  readonly title?: string
  readonly description?: string
  readonly optional?: boolean
  readonly validate?: () => boolean | Promise<boolean>
}
```

`validate` may return a promise, so a step can wait for a check on your server before it lets the wizard move on.

## Internal Types

These are exported because the components pass them between themselves, through Svelte context. You never set them, and nothing asks you for one, but they are listed here so nothing in the package is a mystery.

- `ACCORDION_CONTEXT` - settings an `Accordion` shares with its items.

- `AVATAR_GROUP_CTX` - how an `AvatarGroup` counts its avatars and decides which to hide behind the "+N" one.

- `BTN_QAB_CTX` - settings a `Qab` shares with its items.

- `DROPDOWN_CTX` and `LIST_GROUP_CTX` - classes a `Dropdown` or a `ListGroup` passes to its children.

- `INPUT_CONFIG` - the settings a `Form` or `Fieldset` hands down to the fields inside it, such as `size`, `variant`, `rounded` and `floatingLabel`.

- `NAV_CTX` - the configuration a `Navbar` shares with its links, groups and dropdowns.

- `SLIDE_INFO`, `SLIDE_STATE` and `SLIDER_CTX` - how a `Slide` registers itself with the `Slider` and reads back where it stands.

- `TABLE_CONTEXT` and `TABS_CONTEXT` - what a `Table` or `Tabs` shares with its rows, cells, tabs and panels.

- `WIZARD_CTX` and `WIZARD_STEP_STATE` - how a `FormStep` registers with its wizard and learns whether it is the active step.

- `ROUNDED_ITEM_TYPES` and `ROUNDED_SIDES` - used by the `roundedClass()` helper to round the right corners of a cell in a group.

---

Source: https://www.theui.dev/docs/z-index

# Z-index

Several components in this library stack above the page. This guide gives the order they use, explains why a number sometimes loses to a smaller one, and shows where to put overlays of your own.

## The Layers

Each of these components sits on its own layer, a hundred apart, in the order you would expect them to cover one another: a modal over a drawer, a tooltip over both, a notification over everything.

| Component | Class | Value (z-index) |
| --- | --- | --- |
| Navbar | `.z-100` | 100 |
| Dropdown | `.z-200` | 200 |
| Drawer | `.z-300` | 300 |
| Modal | `.z-400` | 400 |
| Popup | `.z-500` | 500 |
| Tooltip | `.z-600` | 600 |
| Notifications | `.z-700` | 700 |

Leave these alone. They are set so the components work together, and lowering one is the quickest way to lose a modal behind the page it opened from.

## Layers Inside a Component

A few parts stack only against their own component, not against the page, so their numbers are small on purpose.

| Part | Class | Value (z-index) |
| --- | --- | --- |
| Field panel of `Combobox`, `DatePicker` and `TimePicker` | `.theui-field-panel` | 50 |
| Dropdown menu | `.dropdown-content` | 11 |
| Mobile menu of the navbar | `.theui-navbar-collapse` | 1 |

> **Note:** A field panel is above the page but below the `Navbar`. A `Combobox` or `DatePicker` right at the top of a page, under a fixed navbar, opens its list behind that navbar. Leave a little room below the navbar, or open the field lower down the page.

## How Stacking Works

A `z-index` only competes with its siblings, inside what CSS calls a stacking context. That is why a dropdown menu at 11 still sits above a page full of elements at 100: it is measured against the dropdown around it, not against the page.

It also explains the problem people meet most often. An ancestor with a `transform`, a `filter`, a `backdrop-filter`, an `opacity` below 1, or `will-change` starts a stacking context of its own, and everything inside is trapped in it. A modal inside such an element cannot climb out, whatever its number, and will be covered by the next element that sits above its ancestor.

**A dropdown that goes behind the next card**

```svelte
<!-- The scale transform starts a stacking context, so the dropdown -->
<!-- inside this card cannot rise above anything outside it -->
<div class="transition hover:scale-105">
  <Card>
    <Dropdown label="Actions">...</Dropdown>
  </Card>
</div>
```

If a component of this library ends up behind something it should cover, look up the tree for one of those properties before reaching for a bigger number.

## Your Own Overlays

Three places are free for your own elements, and each keeps you out of the library's way.

- **Below 100** - anything that belongs to the page itself, such as a sticky table header or a cookie bar that the navbar may cover.

- **Between two layers** - for example 250 for a panel of your own that should sit over a dropdown but under a drawer.

- **Above 700** - a splash screen or a full-page loader, the only things that should cover a notification.

---

Source: https://www.theui.dev/docs/accordion

# Accordion

The Accordion component is used to show or hide information based on the collapse and expand state of its child elements. It has two variants with configurations provided in the Configuration section.

## Example

Import the required components `Accordion` and `AccordionItem` to use it in your project.

```html
<script>
  import { Accordion, AccordionItem } from "theui-svelte";
</script>
```

You can create an accordion in two ways, using props and using Svelte 5 snippet. The example are showing below:

### Title Using prop

You can create an accordion item with a title and content props using the following example.

```html
<AccordionItem title="Human Psychology Fact">
  <b>Cognitive dissonance</b> refers to the ...
</AccordionItem>
```

### Title Using Snippet

If you have custom content/elements in the title or content, you ca use **Svelte 5**'s `snippet` showing the following example:

```html
<AccordionItem>
  {#snippet title()}
    Human Psychology Fact
  {/snippet}
  <b>Cognitive dissonance</b> refers to the ...
</AccordionItem>
```

## Group Accordion

To create a group of accordion items, wrap multiple `AccordionItem` components within an `Accordion` component:

```html
<Accordion>
  <AccordionItem title="Human Psychology Fact: 1">
    ...
  </AccordionItem>
  <AccordionItem title="Human Psychology Fact: 2">
    ...
  </AccordionItem>
</Accordion>
```

## Flush Accordion

The flush variant drops the outer border and the rounding, leaving only the dividers between the items. Set the `flush` attribute on the `Accordion` and every `AccordionItem` inside it picks it up.

```html
<Accordion flush> ... </Accordion>
```

## Sizes

The `Accordion` and `AccordionItem` component provides a `size` prop to control the size of the accordion items. The `size` prop can take one of the following values: `'compact'`, `'default'`, or `'large'`.

Set `size` on the `Accordion` and every `AccordionItem` inside it inherits the value, so you do not have to set it on each one.

```html
<Accordion size="compact"> ... </Accordion>
```

In the example above every `AccordionItem` uses the `compact` size, because the value is set once on the `Accordion`.

You can also set the `size` prop individually on each `AccordionItem` component which will override the size specified on the `Accordion`.

```html
<Accordion size="compact">
  <AccordionItem>
    ...
  </AccordionItem>
  <AccordionItem size="large">
    ...
  </AccordionItem>
</Accordion>
```

## Accordion Open State

To have an `AccordionItem` open by default, add the `open` attribute to the `AccordionItem` you want to keep open. This is a dynamic attribute, not a prop, and will take effect when added to the component.

```html
<Accordion>
  <AccordionItem>
    ...
  </AccordionItem>
  <AccordionItem open>
    ...
  </AccordionItem>
</Accordion>
```

## Standalone Mode

The `Accordion` component comes with a `standalone` prop that controls how accordion items behave when they are opened or closed. This prop determines whether multiple items can remain open simultaneously or if only one item can stay open at a time.

- **Default Behavior (standalone: true)**: Only one accordion can remain open at a time within the group. Opening a new item will automatically close the currently open one.

- **Multiple Open (standalone: false)**: Allows multiple accordion items in the group to remain open simultaneously.

```html
<Accordion standalone={false}>
  <AccordionItem>
    ...
  </AccordionItem>
  ...
</Accordion>
```

## Rounded Corner

The `rounded` prop controls the border radius of the accordion items. Available values are `"none"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"full"`. When set on the `Accordion`, all `AccordionItem`s inherit it, and in a group only the outer corners of the first and last items are rounded. You can also set it on an individual `AccordionItem`. The `rounded` prop has no effect on a flush accordion.

```html
<Accordion rounded="xl"> ... </Accordion>
<AccordionItem rounded="none"> ... </AccordionItem>
```

## Animation Speed

The `animationSpeed` prop controls how fast the accordion opens and closes. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` (default), and `"faster"`.

```html
<AccordionItem ... animationSpeed="slower"> ... </AccordionItem>
<AccordionItem ... animationSpeed="slow"> ... </AccordionItem>
<AccordionItem ... animationSpeed="normal"> ... </AccordionItem>
<AccordionItem ... animationSpeed="fast"> ... </AccordionItem>
<AccordionItem ... animationSpeed="faster"> ... </AccordionItem>
<AccordionItem ... animationSpeed="none"> ... </AccordionItem>
```

## Customization

Several props take classes for the different parts of the accordion, so the header, the body and the wrapper can be restyled separately.

### Available Props for Customization

- `containerClasses`: Apply custom classes to the accordion's main container.

- `openContainerClasses`: Set custom classes for the container when the accordion is active (expanded).

- `contentClasses`: Define custom classes for the content section.

- `titleClasses`: Customize the classes for the title of each accordion item.

- `openTitleClasses`: Apply specific classes to the title when the accordion is active (expanded).

```html
<AccordionItem
  containerClasses="border-4"
  openContainerClasses="border-4 border-brand-600"
  titleClasses="text-brand-500"
  openTitleClasses="text-brand-700 bg-brand-200"
>
</AccordionItem>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`. The same is true of an `AccordionItem`.

## Accessibility

The Accordion ships with the ARIA wiring and the keyboard support it needs. Here is what is handled:

- **Keyboard Navigation** Use tab to navigate between headers.

- Use Space or Enter to toggle the expanded/collapsed state of an accordion item.

- **ARIA Attributes** The `aria-expanded` attribute will be managed by the component itself for a properly accessible accordion.

- The `aria-controls` links the header to its associated content.

- Each header and content has a unique `id` for ARIA attributes.

- Hidden content uses `aria-hidden="true"` when collapsed and `aria-hidden="false"` when expanded.

- **Focus Management** The focus is retained on the header when toggling the accordion.

- `tabindex="0"` ensures all headers are keyboard-navigable.

- **Screen Reader Compatibility** Descriptive labels or headings can be added for better understanding.

- Semantic roles and ARIA attributes provide full support for assistive technologies.

## Configuration

---

Source: https://www.theui.dev/docs/alert

# Alert

The Alert component displays feedback or contextual messages to your users. Using the Alert component, you can provide various types of feedback such as success, error, warning, or general information.

## Example

Import the `Alert` component to use it in your project. There are 4 types of alert you can create using the `type` prop. The default type is `error`. Other types are `'info'`, `'success'` and `'warning'`. Here are some examples:

```html
<script>
  import { Alert } from "theui-svelte";
</script>

<Alert>I'm error (default) alert!</Alert>
<Alert type="info">I'm info alert!</Alert>
<Alert type="success">I'm success alert!</Alert>
<Alert type="warning">I'm warning alert!</Alert>
```

## Icon

The `Alert` component supports predefined icons for each alert type for for better visual feedback. By default, no icon is shown. Simply add the `icon` attribute to display an icon matching the alert type (success, error, warning, or info). No value needed - it auto-selects the appropriate icon.

```html
<Alert icon>...</Alert>
<Alert icon type="info">...</Alert>
<Alert icon type="success">...</Alert>
<Alert icon type="warning">...</Alert>
```

## Theme

Use the `theme` prop to switch between two Alert styles that complement your design system.

### Available Themes

- **default**: This is the standard theme, offering a balanced look suitable for most use cases.

- **soft**: A lighter variant that provides a more subtle and softer appearance.

```html
<Alert theme="default">...</Alert>
<Alert theme="soft">...</Alert>
```

## Variant

The `Alert` component also supports different visual variants to further customize its appearance using the `variant` prop. These variants determine the structural style of the alert.

### Available Variants

- **card**: Displays the alert as a card with defined borders and padding.

- **borderTop**: Highlights the alert with a border at the top.

- **borderBottom**: Adds a border at the bottom of the alert.

- **borderStart**: Features a border on the starting side (left in LTR, right in RTL).

```html
<Alert theme="soft" variant="card">...</Alert>
<Alert theme="soft" variant="borderTop">...</Alert>
<Alert theme="soft" variant="borderBottom">...</Alert>
<Alert theme="soft" variant="borderStart">...</Alert>
```

## Dismissible Alert

You can close alerts with a click - just add the `dismissible` attribute. The component handles the rest, adding a close button automatically.

```html
<Alert dismissible>...</Alert>
```

## Rounded Corners

You can adjust the alert's corners using the `rounded` prop to tweak the border radius. Choose from preset sizes like `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"`, `"full"`, or `"none"` for a polished look.

```html
<Alert rounded="none"> ... </Alert>
<Alert rounded="sm"> ... </Alert>
<Alert rounded="md"> ... </Alert>
<Alert rounded="lg"> ... </Alert>
<Alert rounded="xl"> ... </Alert>
<Alert rounded="full"> ... </Alert>
```

## Customization

The `class` attribute goes straight onto the alert and is merged with tailwind-merge, so your own colors, spacing and layout classes win over the defaults.

```html
<Alert class="bg-gradient-to-r from-red-200 dark:from-red-800 to-yellow-400 dark:to-yellow-500 text-default">
  I'm custom styled alert message!
</Alert>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`.

## Accessibility

The Alert sets its own ARIA attributes, including `role="alert"` and `aria-label="Close alert"` on the dismiss button, so there is nothing to configure. For non-critical messages, you can change the role using the `role` prop, e.g. `role="status"`.

The only consideration required is maintaining proper color contrast for the alert's text and background to ensure readability and compliance with accessibility standards.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | 'error' \| 'info' \| 'success' \| 'warning' | `error` | Specifies the type of alert, which affects its color and icon. |
| `theme` | "default" \| "soft" | `default` | Determines the overall appearance theme of the alert. |
| `variant` | "card" \| "borderTop" \| "borderBottom" \| "borderStart" | `card` | Specifies the structural style of the alert. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border-radius of the alert, providing control over its rounded corners. |
| `role` | string | `alert` | Sets the ARIA role of the alert. Use a less urgent role such as "status" for non-critical messages. |

### Dynamic props

| Name | Description |
| --- | --- |
| `dismissible` | Makes the alert dismissible by adding a close button. |
| `icon` | Shows a predefined icon matching the alert type. |

---

Source: https://www.theui.dev/docs/avatar

# Avatar

The Avatar component shows who someone is. It takes a photo, falls back to their initials when there is no photo, and to a person icon when there is no name either. Add a status dot for presence, or group several avatars into a stack.

## Example

Import the component and pass an image with `src` and `alt`. Without an image, pass a `name` and the avatar shows the initials.

```html
<script>
  import { Avatar } from "theui-svelte";
</script>

<Avatar src="/avatar.png" alt="Ayesha Rahman" />
<Avatar name="Jane Cooper" />
<Avatar alt="Unknown person" />
```

## Sizes

The `size` prop accepts `xs`, `sm`, `md`, `lg`, `xl` and `2xl`. The default is `md`. The text of the initials scales with the avatar.

```html
<Avatar size="xs" name="Extra Small" />
<Avatar size="sm" name="Small Size" />
<Avatar size="md" name="Medium Size" />
<Avatar size="lg" name="Large Size" />
<Avatar size="xl" name="Extra Large" />
<Avatar size="2xl" name="Double Extra" />
```

## Rounded Corner

Avatars are circles by default. The `rounded` prop takes `none`, `sm`, `md`, `lg`, `xl`, `2xl` and `full`, so a square avatar is one prop away.

```html
<Avatar rounded="full" src="/avatar.png" alt="Full" />
<Avatar rounded="2xl" src="/avatar.png" alt="2xl" />
<Avatar rounded="lg" src="/avatar.png" alt="lg" />
<Avatar rounded="md" src="/avatar.png" alt="md" />
<Avatar rounded="none" src="/avatar.png" alt="none" />
```

## Fallback

When the image fails to load, the avatar falls back on its own: first to the `name` initials, then to a person icon. You can also pass your own content as the child of the component, such as an icon or an emoji.

```html
<!-- A broken image falls back to the initials -->
<Avatar src="https://example.com/missing.png" name="Broken Image" />

<!-- No image: the initials are shown -->
<Avatar name="Rafiq Islam" rounded="lg" />

<!-- Your own content -->
<Avatar class="bg-brand-500 text-on-brand">
  <span class="text-lg">🐧</span>
</Avatar>
```

## Status

The `status` prop adds a presence dot: `online`, `offline`, `busy` or `away`. Use `statusPosition` to move it to the `top`, the default is `bottom`. The status is read out by screen readers, so the dot is never colour alone.

```html
<Avatar src="/a.png" alt="Ayesha" status="online" />
<Avatar src="/b.png" alt="Bilal" status="away" />
<Avatar src="/c.png" alt="Chandra" status="busy" />
<Avatar name="Dina Haque" status="offline" />
<Avatar size="xl" src="/e.png" alt="Elias" status="online" statusPosition="top" />
```

## Link Avatar

Give the component an `href` and the whole avatar becomes a link. Any other attribute, such as `target` or `title`, is passed to the element as well.

```html
<Avatar href="/profile/ayesha" src="/avatar.png" alt="Ayesha Rahman, view profile" />
<Avatar href="/profile/jane" name="Jane Cooper" />
```

## Avatar Group

Wrap avatars in an `AvatarGroup` to stack them. The group sets `size` and `rounded` for every avatar inside, so you set them once.

```html
<script>
  import { Avatar, AvatarGroup } from "theui-svelte";
</script>

<AvatarGroup ariaLabel="Project members">
  <Avatar src="/a.png" alt="Ayesha" />
  <Avatar src="/b.png" alt="Bilal" />
  <Avatar name="Chandra Das" />
</AvatarGroup>
```

## Group Limit

Set `max` to show only the first few avatars. The rest are counted in a final avatar, such as **+3**, which screen readers announce as "3 more".

```html
<AvatarGroup max={3} ariaLabel="Team">
  <Avatar src="/a.png" alt="Ayesha" />
  <Avatar src="/b.png" alt="Bilal" />
  <Avatar src="/c.png" alt="Chandra" />
  <Avatar src="/d.png" alt="Dina" />
  <Avatar src="/e.png" alt="Elias" />
</AvatarGroup>

<AvatarGroup max={2} size="lg" rounded="lg" ariaLabel="Editors">
  ...
</AvatarGroup>
```

## Customization

Pass your own classes with `class` to change the colour of the fallback, and use `imgClasses` and `statusClasses` for the image and the status dot. On a group, `moreClasses` styles the "+N" avatar.

```html
<Avatar name="Brand Colour" class="bg-brand-500 text-on-brand" />
<Avatar name="Soft Look" class="bg-info-100 text-info-900" />
<Avatar src="/r.png" alt="Ring" class="ring-2 ring-brand-500 ring-offset-2" />
<Avatar src="/s.png" alt="Big status" status="online" statusClasses="size-1/3 bg-success-400" />

<AvatarGroup max={1} moreClasses="bg-brand-500 text-on-brand">
  ...
</AvatarGroup>
```

## Accessibility

An avatar with an image needs an `alt`. Use the person's name, or an empty string when the avatar sits next to their name already, so it is not read twice. An avatar showing initials or an icon is marked as an image and named by `alt` or `name`, so a screen reader says the full name instead of the two letters. The status dot carries its own text, such as "Online", and the overflow avatar of a group announces how many people are left. Give the group itself an `ariaLabel` that says what the people have in common.

## Configuration

### Avatar

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | string | `undefined` | Image of the avatar. When it is missing or fails to load, the initials or the icon are shown instead. |
| `alt` | string | `undefined` | Alternative text of the image, and the accessible name of a fallback avatar. Use an empty string when the name is already written next to the avatar. |
| `name` | string | `undefined` | Full name of the person. Its initials are shown when there is no image, and screen readers read the full name. |
| `size` | [AVATAR_SIZE](https://www.theui.dev/docs/types#avatar-size-type) | `md` | Size of the avatar: "xs", "sm", "md", "lg", "xl" or "2xl". Inside an AvatarGroup the group decides. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Defines the border radius of the component. Inside an AvatarGroup the group decides. |
| `status` | [AVATAR_STATUS](https://www.theui.dev/docs/types#avatar-status-type) | `undefined` | Shows a presence dot: "online", "offline", "busy" or "away". |
| `statusPosition` | "top" \| "bottom" | `bottom` | Corner the status dot sits in. |
| `href` | string | `undefined` | Turns the whole avatar into a link. |
| `imgClasses` | string | `` | Custom classes for the image. |
| `statusClasses` | string | `` | Custom classes for the status dot. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the avatar itself, merged with the default classes. Use it to change the fallback colours. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | Custom content of the avatar, such as an icon. Used when there is no image. |

### AvatarGroup

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | number | `undefined` | Number of avatars to show. The rest are counted in a final "+N" avatar. |
| `size` | [AVATAR_SIZE](https://www.theui.dev/docs/types#avatar-size-type) | `md` | Size of every avatar in the group. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Border radius of every avatar in the group. |
| `ariaLabel` | string | `undefined` | Accessible name of the group, such as "Project members". |
| `moreClasses` | string | `` | Custom classes for the "+N" avatar. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the group element, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The Avatar components of the group. |

---

Source: https://www.theui.dev/docs/badge

# Badge

The Badge component shows a small count or a short label next to something else. It suits unread counts, status labels and new item markers.

## Example

To use the Badge component in your project, import the required component first. You can create **dot-badges** just using the `Badge` component or add text inside the `Badge` element to create a text badge. Here are some examples:

```html
<script>
  import { Badge } from "theui-svelte";
</script>

<Badge ariaTitle="Demo badge" />
<Badge>New</Badge>
```

## Grow Badge

By default, the font size of the Badge component is fixed, 0.8em, making it slightly smaller than regular text. However, you can make the font size inherit from te parent element by adding the `grow` attribute to the `Badge` component.

```html
<!-- Indicator badge -->
<Badge ariaTitle="Demo badge" />
<!-- Text badge -->
<Badge grow>...</Badge>
```

## Fixed Top Badge

You can position badges at fixed locations relative to their parent elements using the `fixed` attribute.

```html
<p class="relative p-2 bg-secondary">
  Notifications <Badge ariaTitle="3 unread" fixed />
</p>
<p class="relative p-2 bg-secondary">
  Notifications <Badge fixed>New</Badge>
</p>
```

## Rounded Corner

The `rounded` prop in the `Badge` component controls its border radius. Values: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`. Default is `full`.

```html
<Badge ... rounded="xl">New</Badge>
<Badge ... rounded="lg">New</Badge>
<Badge ... rounded="md">New</Badge>
<Badge ... rounded="sm">New</Badge>
<Badge ... rounded="none">New</Badge>
```

## Customization

To change the background color, add your own classes to the Badge. They are merged with the defaults, so a background class of yours replaces the built in one. Here's an example:

```html
<Badge ariaTitle="Demo badge" class="bg-green-500"/>

<Badge class="bg-yellow-400 text-black">New</Badge>

<p class="relative font-semibold text-white p-2 bg-gradient-to-r from-red-400 to-yellow-500">
  Notifications <Badge class="border-white dark:border-black" fixed>New</Badge>
</p>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<span>`.

## Accessibility

Every badge carries `role="status"`, so a screen reader announces it when it appears or its text changes, which is what a count or a "New" marker is for.

A badge with text is read as that text, so **leave `ariaTitle` off a badge that says something**. A label would replace the content, and `<Badge>New</Badge>` with an `ariaTitle` is read as the label, never as "New".

A dot badge shows no text, so it has nothing to be read as. Give that one an `ariaTitle` that says what it stands for, such as `ariaTitle="3 unread"`. The remaining thing to watch is contrast: a custom background needs a text color to match.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaTitle` | string \| undefined | `undefined` | Names a badge that shows no text, such as a dot badge. Leave it off a badge with text: the label would replace that text for a screen reader. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Defines the border radius of the component. |

### Dynamic props

| Name | Description |
| --- | --- |
| `grow` | Determines if the component should grow to match the parent element's font size. |
| `fixed` | Fixes the component to the top of its container. |
| `class` | Classes for the badge element, merged with the default classes. |

---

Source: https://www.theui.dev/docs/breadcrumb

# Breadcrumb

The Breadcrumb component displays the location of the current page within a navigational hierarchy. It helps users understand the structure of your site and navigate back to previous pages easily.

## Example

Start by importing the `Breadcrumb` component into your Svelte file, then pass it an array of breadcrumb items (like [BREADCRUMB_DATA](https://www.theui.dev/docs/types#breadcrumb-data-type)) containing each item's text and URL. Each item's `text` must be unique, and the item without a `url` is treated as the current page. Here's a basic example:

```html
<script>
  import { Breadcrumb } from "theui-svelte";

  let breadcrumbData: Array<BREADCRUMB_DATA> = [
    { text: "Home", url: "/" },
    { text: "Docs", url: "/docs" },
    { text: "Breadcrumb" }
  ]
</script>

<Breadcrumb data={breadcrumbData} />
```

## Change Link Separator

You can customize the separator between breadcrumb links using the `separator` prop. The default separator is `/` and it can be overridden as shown below:

```html
<Breadcrumb data={breadcrumbData} separator=">" />
```

## Rounded Corner

The `rounded` prop sets the border radius of the breadcrumb container and its items. Available values are `"none"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"full"`. The corners are visible when the breadcrumb has a background or border, for example added with the `class` attribute.

```html
<Breadcrumb data={breadcrumbData} rounded="full" class="bg-gray-100 px-4 py-2" />
```

## Customization

The `Breadcrumb` component offers flexibility for styling, allowing you to easily adapt it to match your design requirements.

To customize the breadcrumb container itself, you can use the standard `class` attribute to apply custom styles. For further customization, there are two props designed to style the breadcrumb links:

- `linkClasses`: This prop updates the appearance of the links within the breadcrumb.

- `activeLinkClasses`: This prop specifically targets the active link, enabling you to style it differently from the rest of the links.

```html
<Breadcrumb
  data={breadcrumbData}
  activeLinkClasses="text-pink-500"
  linkClasses="text-green-500"
/>

```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<nav>`.

## Accessibility

    The `Breadcrumb` component is fully accessible, with `aria-label="breadcrumb"` applied to the navigation container to identify it as a breadcrumb trail for assistive technologies. Each link is keyboard-navigable, and the current page is marked with `aria-current="page"`. You only need to provide meaningful link labels and ensure proper color contrast for readability.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | Array<[BREADCRUMB_DATA](https://www.theui.dev/docs/types#breadcrumb-data-type)> | `[]` | An array of breadcrumb items to display. Each item's text must be unique. |
| `activeLinkClasses` | string | `text-gray-400` | CSS classes applied to the active breadcrumb link. |
| `linkClasses` | string | `text-brand-500` | CSS classes applied to the non-active breadcrumb links. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the breadcrumb container and its items. |
| `separator` | string | `/` | The character or element used to separate breadcrumb items. |

---

Source: https://www.theui.dev/docs/button

# Button

The Button component covers the sizes, colors and themes the library uses. Give it an href and it renders an anchor instead of a button.

## About

Give it an `href` and it renders an `<a>`; leave it out and you get a `<button>`. The look comes from two axes, `theme` and `color`, with `outline` as a third option that overrides `theme`. Anything you pass in `class` is merged last, so your own styling wins.

## Example

Import the `Button` component into your Svelte file. The following example shows how to use the button component!

```html
<script>
  import { Button } from "theui-svelte";
</script>

<Button>Button</Button>
```

## Link Button

You can turn the `Button` into a link by adding the href prop. This makes the button behave like a regular link. This will navigate to the home page when clicked.

```html
<Button href="/">Link button</Button>
```

### New Tab Icon

Sometimes, you may want to show an arrow icon to indicate that a link opens in a new tab. This is controlled by the `newTabIcon` prop. By default, it's `true`, so the icon is shown. Set it to `false` to hide the icon.

**Important:** The link must have a `target` attribute (like `target="_blank"`) for the icon to appear. If there's no `target`, the icon won't show - even if `newTabIcon` is `true`.

```html
<Button href="/" target="_blank" newTabIcon={true}>...</Button>
```

## Button Content

The `Button` component offers `beforeLabel` and `afterLabel` snippet blocks that let you add custom content before or after the button's label. This is useful for icons, badges, or other elements, giving you more control over the button's look and behavior. Although you can add elements manually with HTML and CSS, using these snippets keeps the structure cleaner and easier to maintain. It also simplifies layout and styling.

For better structure, flexibility, and consistency, `beforeLabel` and `afterLabel` are great options.

### Example Using Snippets

```html
<Button>
  {#snippet beforeLabel()}
    <Svg size={1.5}>
      <path d="M8 8a3 3 0 ... />
    </Svg>
  {/snippet}

  Button Text

  {#snippet afterLabel()}
    <Svg size={1.5}>
      <path fill-rule="evenodd" d="M1 8a.5.5 0 0 ... />
    </Svg>
  {/snippet}
</Button>
```

### Example Without Snippets

```html
<Button>
  <div class="CUSTOM CLASSES">
    <Svg size={1.5}>
      <path d="M8 8a3 3 0 ... />
    </Svg>

    Button Text

    <Svg size={1.5}>
      <path fill-rule="evenodd" d="M1 8a.5.5 0 0 ... />
    </Svg>
  </div>
</Button>
```

## Button Color

The `color` prop lets you style the button using predefined themes like `"brand"`, `"error"`, `"info"`, `"success"`, and `"warning"`. These match common statuses or actions to keep your app's design consistent. The default is `"brand"`.

```html
<Button color="brand">Brand</Button>
<Button color="error">Error</Button>
<Button color="info">Info</Button>
<Button color="success">Success</Button>
<Button color="warning">Warning</Button>
```

Each color carries a meaning, so a reader can tell a destructive action from a safe one. You can still pass your own classes, but the `color` prop keeps the whole app on one palette.

## Theme

The `theme` prop controls the button's overall style and background. It supports three values: `'default'`, `'soft'`, and `'gradient'`. The default theme gives the standard button look, the soft theme uses softer colors, and the gradient theme adds a vibrant background with gradient styling.

### Soft Theme

The soft theme is a softer variation of the default button colors, making it suitable for more subtle designs.

```html
<Button theme="soft" color="brand">Brand</Button>
<Button theme="soft" color="error">Error</Button>
<Button theme="soft" color="info">Info</Button>
<Button theme="soft" color="success">Success</Button>
<Button theme="soft" color="warning">Warning</Button>
```

### Gradient Theme

The gradient theme fills the button background with a two color gradient.

```html
<Button theme="gradient" gradientColor="brand">Brand</Button>
<Button theme="gradient" gradientColor="error">Error</Button>
<Button theme="gradient" gradientColor="info">Info</Button>
<Button theme="gradient" gradientColor="success">Success</Button>
<Button theme="gradient" gradientColor="warning">Warning</Button>
```

> **Note:** The color prop can still be used with each theme to specify the button's color, allowing flexibility while maintaining consistency across different button themes.

## Outline

The `outline` prop lets you create a button with a modern outline style. It gives the button a transparent background and a border, making it great for secondary actions or a minimalist look.

To use an outline button, set the `outline` prop to `true` like this: `outline={"{true}"}`

```html
<Button color="brand" outline={true}>Brand</Button>
<Button color="error" outline={true}>Error</Button>
<Button color="info" outline={true}>Info</Button>
<Button color="success" outline={true}>Success</Button>
<Button color="warning" outline={true}>Warning</Button>
```

## Size

The `size` prop sets the padding and the font size of the button. It takes one of the preset values below.

Available values are `"xs"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, and `"auto"`, allowing flexibility while maintaining consistency.

```html
<Button size="xs">Extra small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra large</Button>
<Button size="auto">Auto</Button>
```

Each size option adjusts the button's padding and font size, providing a cohesive look across different screen sizes and use cases. The `auto` size adapts to the content, has no padding, making it flexible for various layouts.

## Square Button

The `square` prop makes the button's height and width equal, which is what you want for an icon button.

```html
<Button square={true}>m</Button>
```

You can combine the `square` prop with the `size` prop to create square buttons of varying dimensions. This flexibility lets you choose the appropriate size for different UI elements while maintaining the square shape.

```html
<Button square={true} size="xs"> ... </Button>
<Button square={true} size="sm"> ... </Button>
<Button square={true} size="md"> ... </Button>
<Button square={true} size="lg"> ... </Button>
<Button square={true} size="xl"> ... </Button>
```

Square buttons follow the same size scale, so an icon button lines up with the text buttons beside it.

## Rounded Corner Button

The `rounded` prop sets the corner radius of the button. Available values are: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, and `full`. Default value `md`.

```html
<Button rounded="none">None</Button>
<Button rounded="sm">Small</Button>
<Button rounded="md">Medium</Button>
<Button rounded="lg">Large</Button>
<Button rounded="xl">Extra large</Button>
<Button rounded="full">Full</Button>
```

## Button Shadow

The `shadow` prop controls the button's shadow. Available values are `"none"`, `"xs"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"inner"`. Buttons inside a `ButtonGroup` don't use it.

```html
<Button shadow="none">No shadow</Button>
<Button shadow="sm">Small</Button>
<Button shadow="lg">Large</Button>
<Button shadow="2xl">2xl</Button>
```

## Button Animation Speed

The `animationSpeed` determines the speed of the button's animation, with options including `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"`, and `"faster"`.

```html
<Button animationSpeed="slower">Slower animation</Button>
<Button animationSpeed="slow">Slow animation</Button>
<Button animationSpeed="normal">Normal animation</Button>
<Button animationSpeed="fast">Fast animation</Button>
<Button animationSpeed="faster">Faster animation</Button>
<Button animationSpeed="none">No Animation animation</Button>
```

Each value sets a different transition duration.

## Loading State

Set the `loading` prop to `true` to show a spinner in the button, for example while a form is being submitted. While loading, the button can't be clicked. The `loadingText` prop sets the text shown after the button label; the default is `"Loading..."`. Set it to an empty string to show only the spinner.

```html
<script>
  let saving = $state(false);
</script>

<Button loading={saving} onclick={() => saving = true}>Save</Button>

<!-- Spinner only -->
<Button loading={true} loadingText="">Save</Button>
```

## Active State

Use the `isActive` prop to show a button in its pressed style, for example the selected option in a group of buttons or a toggle that is on. The default is `false`. On a button (not a link), `isActive` also sets `aria-pressed="true"` so screen readers announce it as pressed.

```html
<Button>Inactive</Button>
<Button isActive={true}>Active</Button>
<Button outline={true} isActive={true}>Active outline</Button>
```

## Disabled Button

Add the `disabled` attribute to disable a button. A disabled button is dimmed, can't be clicked and gets `aria-disabled="true"`. On a link button, the link is also removed, so it can't be opened with the mouse or the keyboard.

```html
<Button disabled>Disabled button</Button>
<Button href="/" disabled>Disabled link</Button>
```

## Actions

The `actions` prop lets you apply [Svelte actions](https://svelte.dev/docs/svelte/use) to the button element. Pass an array of `[action, params]` pairs; `params` is optional. Each action runs when the button is mounted, and its `destroy` function runs when the button is removed.

```html
<script>
  const tooltip = (node, text) => {
    node.title = text;
    return { destroy: () => node.removeAttribute("title") };
  };
</script>

<Button actions={[[tooltip, "Save your changes"]]}>Save</Button>
```

## Accessibility

The Button carries the ARIA attributes it needs and answers to the keyboard out of the box.

- **Keyboard Navigation**: Use tab to navigate between buttons, and Enter or Space to activate a button.

- **ARIA Attributes**: By default, screen readers use the button's visible text as its name. The `ariaLabel` prop sets `aria-label`, which replaces that text, so use it when the button's text or icon alone may not be clear (e.g., icon-only buttons).

```html
<Button square={true} ariaLabel="Open profile">
  <Svg>...</Svg>
</Button>
```

A disabled button gets `aria-disabled="true"`, and an active button (`isActive`) gets `aria-pressed="true"`.

- **Focus Management**: focus styles use `focus-visible` or `focus-within`, so the ring shows for keyboard users without appearing on every mouse click.

- **State Indications**: Visual cues (hover, focus, active, and disabled states) are provided to communicate the button's interactive state clearly.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `beforeLabel` | Snippet | `undefined` | Custom content to display before the button label. |
| `afterLabel` | Snippet | `undefined` | Custom content to display after the button label. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed of the button. Inherited from ButtonGroup if available. |
| `actions` | [action, params?][] | `undefined` | A list of Svelte actions applied to the button element, each as an `[action, params]` pair. |
| `ariaLabel` | string | `undefined` | Accessible label for the button. When not set, screen readers use the visible button text. Use it for buttons without visible text, like icon-only buttons. |
| `newTabIcon` | boolean | `true` | Display an arrow that indicates the link will open a new tab. It will only be visible if the button has an href with a "target" attribute. |
| `href` | string \| undefined | `undefined` | URL to navigate to when the button is clicked, converting the button into a link. |
| `isActive` | boolean | `false` | Shows the button in its active (pressed) style. On a button (not a link) it also sets `aria-pressed="true"`. |
| `loading` | boolean | `false` | Shows a spinner and the `loadingText`, and blocks clicks while loading. |
| `loadingText` | string | `Loading...` | Text shown next to the spinner when `loading` is true. Set it to an empty string to show only the spinner. |
| `outline` | boolean | `false` | Whether the button should have an outline style. Inherited from ButtonGroup if available. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Specifies the rounded corners of the button. Inherited from ButtonGroup if available. |
| `shadow` | [SHADOW](https://www.theui.dev/docs/types#shadow-types) | `md` | Controls the shadow of the button. |
| `size` | [BUTTON_SIZE](https://www.theui.dev/docs/types#button-size-type) | `md` | Specifies the size of the button. Inherited from ButtonGroup if available. |
| `square` | boolean | `false` | Whether the button should be a square. Inherited from ButtonGroup if available. |
| `theme` | 'default' \| 'soft' \| 'gradient' | `default` | Theme of the button, determining its overall style. Inherited from ButtonGroup if available. |
| `gradientColor` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | Defines the base color of the gradient theme. Inherited from ButtonGroup if available. |
| `color` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | The color of the button, indicating its purpose. Inherited from ButtonGroup if available. |
| `type` | 'button' \| 'submit' \| 'reset' | `button` | Specifies the type of button, such as button, submit, or reset. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the button: dims it, blocks clicks and sets `aria-disabled="true"`. On a button the native `disabled` attribute is set too; on a link the `href` is removed. |

### Snippets

| Name | Description |
| --- | --- |
| `beforeLabel` | Custom content to display before the button label. |
| `afterLabel` | Custom content to display after the button label. |

---

Source: https://www.theui.dev/docs/button-group

# Button Group

Helps you group multiple buttons together for a cohesive and organized layout. Ideal for presenting related actions or options side by side or vertically

## About

The `ButtonGroup` component joins several `Button` components into one block. It takes care of the alignment, the spacing and the rounding of the outer edges, which is what you want for a toolbar, a set of view switches or a row of related actions.

## Example

Import the Button component into your Svelte file. The following example shows how to use the button component!

```html
<script>
  import { ButtonGroup, Button } from 'theui-svelte';
</script>

<ButtonGroup>
  <Button>Save</Button>
  <Button>Edit</Button>
  <Button>Delete</Button>
</ButtonGroup>
```

In this example, the `ButtonGroup` wraps multiple `Button` components, aligning them neatly in a single row. This structure is useful for presenting related actions in a visually consistent manner.

## Stacked Button

The `ButtonGroup` component supports a stacked layout that arranges buttons vertically instead of side by side. This is helpful for mobile or narrow screens where space is limited. To use it, set the `stacked` prop to `true`.

```html
<ButtonGroup stacked={true}> ... </ButtonGroup>
```

In this example the buttons stack one below the other.

## Outlined Button

The `outline` prop in the `ButtonGroup` component gives all buttons a bordered look with a transparent background. It's useful when you want a lighter, less prominent style while keeping a consistent design.

```html
<ButtonGroup outline={true}> ... </ButtonGroup>
```

In this example, all buttons within the `ButtonGroup` have an outlined style, making them stand out with borders while keeping the background clear.

## Group Button Sizing

The `size` prop in the `ButtonGroup` component sets the size of all buttons in the group, keeping them consistent. You can use predefined values like `'xs'`, `'sm'`, `'md'` (default), `'lg'`, `'xl'`, or `'auto'` to control the button dimensions.

```html
<ButtonGroup size="auto"> ... </ButtonGroup>
<ButtonGroup size="xs"> ... </ButtonGroup>
<ButtonGroup size="sm"> ... </ButtonGroup>
<ButtonGroup size="md"> ... </ButtonGroup>
<ButtonGroup size="lg"> ... </ButtonGroup>
<ButtonGroup size="xl"> ... </ButtonGroup>
```

In this example the buttons are outlined, which is a lighter look than the filled default.

## Square Group Button

The `ButtonGroup` component can stack buttons vertically instead of placing them side by side. This is useful for mobile or narrow screens. To enable it, set the `stacked` prop to `true`.

```html
<ButtonGroup square={true}> ... </ButtonGroup>
```

In this example the buttons stack one below the other.

## Rounded Button Control

The `rounded` prop controls the border-radius of the buttons within the `ButtonGroup`, allowing you to adjust the roundness of the button corners. You can choose from several options, such as `"sm"` for small rounded corners, `"md"` (default) for medium, `"lg"` for large, `"xl"` for extra-large, `"2xl"` for double extra-large, `"full"` for fully rounded corners, or `"none"` for no rounding at all.

```html
<ButtonGroup rounded="none"> ... </ButtonGroup>
<ButtonGroup rounded="sm"> ... </ButtonGroup>
<ButtonGroup rounded="md"> ... </ButtonGroup>
<ButtonGroup rounded="lg"> ... </ButtonGroup>
<ButtonGroup rounded="xl"> ... </ButtonGroup>
<ButtonGroup rounded="full"> ... </ButtonGroup>
```

In this example, the buttons in the `ButtonGroup` have large rounded corners. The default value for the `rounded` prop is `"md"`, but you can customize it as per your design needs.

## Button Group Variants

The `variant` prop in the `ButtonGroup` component allows you to choose between two button styles: `bordered` and `flat`. This prop customizes the visual separation between buttons in the group.

- `flat` (default): the buttons sit flush against each other with no gap between them.

- `bordered`: Adds borders between the buttons, giving each button a distinct outline.

```html
<ButtonGroup variant="flat"> ... </ButtonGroup>
<ButtonGroup variant="bordered"> ... </ButtonGroup>
```

In the first example, the `bordered` variant adds visible borders between the buttons, while the second example uses the default `flat` variant for a smooth, border-less look.

## Button Group Color

The `color` prop on the `ButtonGroup` sets the color for every button in the group. A single button can still override it with its own `color` prop.

```html
<ButtonGroup color="warning">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
  <Button color="error">Button 3</Button>
  <Button>Button 4</Button>
  <Button>Button 5</Button>
</ButtonGroup>
```

In this example `size="lg"` applies to every button in the group.

## Button Group Theme

The `theme` prop controls the overall theme of the buttons within the `ButtonGroup`. It allows you to choose from three options: `"default"`, `"soft"`, or `"gradient"`. Each theme applies a different visual style to the buttons to match your design preferences.

### Soft Theme

The **soft theme** gives the buttons a softer and lighter appearance, making them more subtle and minimal. You can also use the color prop with the soft theme to further customize the button colors.

```html
<ButtonGroup theme="soft"> ... </ButtonGroup>
<ButtonGroup theme="soft" color="info"> ... </ButtonGroup>
```

### Gradient Theme

The **gradient theme** applies a gradient background to the buttons, giving them a vibrant and dynamic look. To customize the gradient's color scheme, use the `gradientColor` prop in combination with the gradient theme.

```html
<ButtonGroup theme="gradient"> ... </ButtonGroup>
<ButtonGroup theme="gradient" gradientColor="success"> ... </ButtonGroup>
```

## Animation Speed

The `animationSpeed` prop sets the transition speed (like the hover effect) for all buttons in the group. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"` (default), `"fast"` and `"faster"`. A button can override it with its own `animationSpeed` prop.

```html
<ButtonGroup animationSpeed="slower">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
  <Button animationSpeed="none">Button 3</Button>
</ButtonGroup>
```

## Customization

Use the `class` attribute to style the group container. To apply the same classes to every button in the group, use the `buttonClasses` prop. A button's own `class` attribute is applied after `buttonClasses`, so it can override them.

```html
<ButtonGroup buttonClasses="uppercase tracking-wider">
  <Button>Save</Button>
  <Button>Edit</Button>
  <Button class="normal-case">Delete</Button>
</ButtonGroup>
```

## Accessibility

The `ButtonGroup` carries the roles and labels a screen reader needs, and every button inside it stays reachable by keyboard.

### ARIA Label

The `ariaLabel` prop allows you to provide a custom label for the button group, enhancing its accessibility. The default value is "Button group". You can specify a more descriptive label depending on the context or functionality of the button group.

```html
<ButtonGroup ariaLabel="ARIA label"> ... </ButtonGroup>
```

The `role="group"` attribute is automatically included in the ButtonGroup component. This role helps assistive technologies understand that the buttons are part of a grouped set, improving the navigation and comprehension for users.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `stacked` | boolean | `false` | Determines if the buttons are stacked vertically. |
| `outline` | boolean | `false` | Applies an outlined style to the button group. |
| `size` | [BUTTON_SIZE](https://www.theui.dev/docs/types#button-size-type) | `md` | Specifies the size of the buttons in the group. |
| `square` | boolean | `false` | Determines if the buttons in the group are square. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Controls the rounded corners of the buttons in the group. |
| `variant` | 'bordered' \| 'flat' | `flat` | Defines the visual style of the button group, either with borders between buttons or flat with no borders. |
| `color` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | Defines the color scheme of the button group. |
| `theme` | 'default' \| 'soft' \| 'gradient' | `default` | Sets the overall theme of the button group, affecting colors and styles. |
| `gradientColor` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | Defines the base color of the gradient theme for the buttons in the group. |
| `buttonClasses` | string | `` | Custom classes applied to every button in the group. A button's own `class` can override them. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed for the button group. |
| `ariaLabel` | string | `Button group` | Custom ARIA label for accessibility, describing the button group. |

---

Source: https://www.theui.dev/docs/card

# Card

The Card component wraps content in a surface with an optional title, an image above or below it, and a side by side layout.

## About

The `Card` component groups a title, an image and some body content into one block. The layout, the images and the classes are all set through props. The image can sit above the content, below it, or behind it with a scrim over the top.

## Example

Start by importing the Card component from the theui-svelte library:

```html
<script>
  import { Card } from "theui-svelte";
</script>
```

Here is the `Card` with a title, an image and some body content. The layout and the styling are adjusted with the props listed further down.

```html
<script>
  const imgData = {src: "https://placehold.co/800x400/6A00F5/white", alt: "A demo image"}
</script>

<Card title="Card Title" topImage={imgData}>
  <p>A short line of body content, so the card has something to wrap around.</p>
  <div>
    <Button>Submit</Button>
  </div>
</Card>
```

Alternatively you can use related **snippet** for the card item like title and images.

```html
<Card>

  <p>A short line of body content, so the card has something to wrap around.</p>
  <div>
    <Button>Submit</Button>
  </div>
</Card>
```

## Card Elements

There are some prefix elements in the `Card` component. The example are showing below.

### Card Title

You can use either `title prop` or `title snippet` to add card title.

```html
<Card title="Card Title">
  ...
</Card>
```

You can use the `title` snippet also:

```html
<Card>
  {#snippet title()}
    <h4 class="text-xl font-semibold">Card Title</h4>
  {/snippet}
</Card>
```

### Card's Top Image

Use either the `topImage prop` or `topImage snippet` to add image at the top in the `Card` component.

```html
<script>
  const imgData = {src: "https://placehold.co/800x400/6A00F5/white", alt: "A demo image"}
</script>

<Card title="Card Title" topImage={imgData}>
  ...
</Card>
```

### Card's Bottom Image

Use either the `bottomImage prop` or `bottomImage snippet` to add image at the bottom in the `Card` component.

```html
<script>
  const imgData = {src: "https://placehold.co/800x400/6A00F5/white", alt: "A demo image"}
</script>

<Card title="Card Title" bottomImage={imgData}>
  ...
</Card>
```

Or, use `bottomImage` snippet:

```html
<Card>
  {#snippet title()}
    <h4 class="text-xl font-semibold">Card Title</h4>
  {/snippet}

  {#snippet bottomImage()}
    <img class="block w-full rounded-b-md" src="..." alt="...">
  {/snippet}

  <p>This is card content..</p>
</Card>
```

### Card Content

Any element the `Card` component will be the card content.

```html
<Card>
  <p>This is card content..</p>
</Card>
```

### Image Overlay

Use the `imageOverlay` prop to place the card title and content over the image, with a backdrop behind the text for readability. Set it to `true` for the default backdrop, or pass a string of classes to style the backdrop. The default value is `false`.

```html
<Card title="Card Title" topImage={imgData} imageOverlay={true}>
  ...
</Card>

<!-- Custom backdrop classes -->
<Card title="Card Title" topImage={imgData} imageOverlay="bg-black/70">
  ...
</Card>
```

## Horizontal Card

The `Card` component supports a flexible layout option that allows you to switch between vertical and horizontal orientations, depending on your design needs. To adopt a horizontal layout for the `Card` component, simply add the `horizontal` attribute. When this attribute is present, the card's content will be arranged side by side, making it ideal for designs where a wide layout is preferred.

```html
<Card horizontal>
  <p>This is card content..</p>
</Card>
```

## Rounded Corner

Control the corner of the card using the `rounded` prop. Available values are: `sm`, `md`, `lg`, `xl`, `2xl`, `full` and `none`, Default value is `md`

```html
<Card ... rounded="none"> ... </Card>
<Card ... rounded="xl"> ... </Card>
```

## Customization

The `Card` component is easy to customize, letting you style it to match your needs. You can change how any part of the card looks. Whether it's the content, title, shadow, or shape, you have full control.

You can either use snippets for custom components or utilize these props directly for more straightforward customization. Here are the key props available for customization:

- **class**: Apply custom styles to the card's container.

- **contentClasses**: Apply custom styles to the card's content.

- **titleClasses**: Style the title with your preferred classes.

- **shadow**: Adjust the card's shadow for a more or less prominent effect.

- **rounded**: Control the card's border-radius to achieve the desired shape.

```html
<Card
  class="border-2 border-green-500 bg-green-100"
  titleClasses="bg-green-500 p-2 rounded-md text-green-50"
  contentClasses="text-green-500"
  shadow="none"
  rounded="xl"
  title="Card Title"
>
  <p>This is card content..</p>
</Card>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`.

## Accessibility

The `Card` component is a plain container, so screen readers read its content in order without announcing the card itself. A string `title` is rendered as an `<h4>` heading, letting users jump to each card with heading navigation. If you use the `title` snippet, use a heading element there too. Give image props a meaningful `alt` text (or an empty one for decorative images), and when using `imageOverlay`, make sure the text keeps enough contrast against the image.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | Snippet \| string | `undefined` | The title of the component, which can be a string or a Snippet. A string renders as plain text; use a Snippet for markup. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the component. |
| `shadow` | [SHADOW](https://www.theui.dev/docs/types#shadow-types) | `md` | Specifies the shadow depth for the component. |
| `topImage` | Snippet \| [CARD_IMAGE_TYPE](https://www.theui.dev/docs/types#card-image-type) | `undefined` | An optional top image, which can be a Snippet or an object with image properties. |
| `bottomImage` | Snippet \| [CARD_IMAGE_TYPE](https://www.theui.dev/docs/types#card-image-type) | `undefined` | An optional bottom image, which can be a Snippet or an object with image properties. |
| `contentClasses` | string | `` | CSS classes for styling the content area. |
| `titleClasses` | string | `` | CSS classes for styling the title. |
| `imageOverlay` | boolean \| string | `false` | Places the card content over the image with a backdrop. Pass a string to add custom classes to the backdrop. |

### Dynamic props

| Name | Description |
| --- | --- |
| `horizontal` | If added, displays the component in a horizontal layout. |

---

Source: https://www.theui.dev/docs/checkbox

# Checkbox

The Checkbox component wraps the native checkbox input in the library's styling. It takes sizes, animation speeds and label classes, and inherits them from a Form or Fieldset.

## About

It is still a native `<input type="checkbox">` underneath, so it submits with the form and behaves the way a browser checkbox does. What the component adds is the styling, the linked label, and the settings it picks up from its parent.

## Example

Here is a basic usage example of the Checkbox component:

```html
<script>
  import { Checkbox } from "theui-svelte";
</script>

<Checkbox name="terms">I agree to the terms and conditions</Checkbox>
```

## Name and Value

The `name` and `value` props are what the form submission uses. The `name` prop groups checkboxes, allowing multiple selections under the same category. The `value` prop is the value sent with the form when the checkbox is checked. To control whether it is checked, use the `checked` prop.

```html
<Checkbox name="myCheckbox" value="dark-mode">Enable Dark Mode</Checkbox>
<Checkbox name="myCheckbox" value="notifications">Enable Notifications</Checkbox>
```

## Checked State

The `checked` prop sets whether the checkbox is checked. It is `false` by default. The prop is bindable, so use `bind:checked` to read the state when the user toggles the checkbox, or to change it from your code.

```html
<script>
  let subscribed = $state(true);
</script>

<Checkbox name="newsletter" bind:checked={subscribed}>Subscribe to the newsletter</Checkbox>
<p>Subscribed: {subscribed}</p>
```

## Checkbox Sizes

The `size` prop controls the overall size of the checkbox, making it adaptable to different layouts and UI designs. The available sizes are `"sm"`, `"md"` (default), `"lg"` and `"xl"`.

```html
<Checkbox name="myCheckbox" size="sm">Small (sm) checkbox</Checkbox>
<Checkbox name="myCheckbox" size="md">Medium (md) checkbox</Checkbox>
<Checkbox name="myCheckbox" size="lg">Large (lg) checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl">Extra Large (xl) checkbox</Checkbox>
```

## Animation

The `animationSpeed` prop determines the speed of the checkbox's interaction effects, such as transitions when toggling states. It helps improve user experience by making interactions feel smoother. The available animation speeds are `"none"`, `"slower"`, `"slow"` `"normal"` (default), `"fast"` and `"faster"`.

Setting it to `"none"`disables animations, while other values can be used to adjust the transition speed based on preference.

```html
<Checkbox name="myCheckbox" animationSpeed="slower">Slower animation</Checkbox>
<Checkbox name="myCheckbox" animationSpeed="slow">Slow animation</Checkbox>
<Checkbox name="myCheckbox" animationSpeed="normal">Normal animation</Checkbox>
<Checkbox name="myCheckbox" animationSpeed="fast">Fast animation</Checkbox>
<Checkbox name="myCheckbox" animationSpeed="faster">Faster animation</Checkbox>
<Checkbox name="myCheckbox" animationSpeed="none">No animation</Checkbox>
```

## Rounded Checkbox

The `rounded` prop defines the border-radius of the checkbox, allowing customization of its shape. The available values are `"none"`, `"sm"` (default), `"md"`, `"lg"`, `"xl"`, `"2xl"` and `"full"`.

Inside a `Form` or `Fieldset`, the checkbox uses their `rounded` value instead, unless you set the prop on the checkbox.

```html
<Checkbox name="myCheckbox" size="xl" rounded="none">Rounded none checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl" rounded="sm">Rounded small checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl" rounded="md">Rounded medium checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl" rounded="lg">Rounded large checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl" rounded="xl">Rounded extra large checkbox</Checkbox>
<Checkbox name="myCheckbox" size="xl" rounded="full">Rounded full checkbox</Checkbox>
```

## Resetting Style

The `reset` prop removes all default styles from the Checkbox component, allowing only custom styles to be applied. This is useful when you want full control over the design. Just set `reset` to `true` to apply reset.

```html
<Checkbox name="myCheckbox" reset={true} class="border border-green-500 bg-green-200 checked:bg-green-500 focus:ring-0">Enable Dark Mode</Checkbox>
```

## Label Position

The `labelPosition` prop controls where the label sits. It accepts `"end"` (default), which places the label after the checkbox, and `"start"`, which places it before. The position follows the writing direction, so in a right-to-left layout `"start"` puts the label on the right.

```html
<Checkbox name="myCheckbox">Label after the checkbox</Checkbox>
<Checkbox name="myCheckbox" labelPosition="start">Label before the checkbox</Checkbox>
```

## Disabled Checkbox

Add the native `disabled` or `readonly` attribute to prevent changes. The checkbox and its label are dimmed and can't be clicked.

```html
<Checkbox name="myCheckbox" disabled>Disabled checkbox</Checkbox>
```

## Customization

The Checkbox component provides multiple ways to customize its appearance:

- `labelClasses` - Custom styles for the label. If used within a Fieldset or Form component, it inherits their `labelClasses`. The `size`, `animationSpeed`, `rounded` and `reset` props are inherited the same way.

- `wrapperClasses` - Additional classes for the wrapper , useful for layout adjustments.

- `class` - Apply custom styles to the checkbox itself.

```html
<Checkbox
  name="myCheckbox"
  wrapperClasses="flex flex-col relative gap-0"
  labelClasses="font-bold z-[1]"
  class="checked:bg-green-500 focus:ring-green-200 focus:border-green-200 w-full h-8"
>
  CUSTOM CHECKBOX
</Checkbox>
```

## Accessibility

The `Checkbox` component uses the native `<input type="checkbox">`, so screen readers announce whether it is checked without extra attributes. It also supports `aria-required` and `aria-disabled` attributes through `props`, making it more accessible for users with assistive technologies. Each checkbox has an associated `<Label>` component to provide a clear description, and the label can be placed before the checkbox for right-aligned designs.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | unknown | `undefined` | Defines the value sent with the form when the checkbox is checked. |
| `checked` | boolean | `false` | Whether the checkbox is checked. Bindable: use `bind:checked` to read or control the state. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Controls the size of the checkbox. Available options: "sm", "md", "lg", "xl". |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Determines the animation speed for state changes. Options: "none", "slower", "slow", "normal", "fast", "faster". |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `Inherited from Fieldset or Form, or "sm` | Defines the border-radius of the checkbox. Options: "none", "sm", "md", "lg", "xl", "2xl", "full". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | If set to true, removes all default styles, allowing full customization. |
| `labelClasses` | string | `Inherited from Fieldset or Form, or "` | Custom classes for styling the label. |
| `wrapperClasses` | string | `` | Additional classes for styling the main wrapper of the checkbox. |
| `labelPosition` | 'start' \| 'end' | `end` | Places the label before ("start") or after ("end") the checkbox, following the writing direction. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the checkbox and dims it together with its label. |
| `readonly` | Prevents changes and dims the checkbox together with its label. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The label content of the checkbox. |

---

Source: https://www.theui.dev/docs/chips

# Chips

The `Chips` component shows a short piece of information as a pill, such as a tag, a category or a selected person. It takes text, an optional image and an optional close button.

## Example

First, import the `Chips` component from the library. Below is a simple example demonstrating how to use the Chips component. This example shows how to create a chip with a basic text label:

```html
<script>
  import { Chips } from "theui-svelte";
</script>

<Chips>Example Chips</Chips>
```

In this example the text placed inside the `Chips` component creates a chip displaying the text "Example Chips".

## Chips With Image

You can put an image next to the text. Below is a basic example demonstrating how to use the Chips component with an image:

```html
<Chips imgSrc="/path/to/image.png" altText="Photo of Jasmine Kira">...</Chips>
```

The `imgSrc` prop specifies the path to the image ("/path/to/image.png"), adding an image to the chip. Use the `altText` prop to set the image's alternative text for screen readers. It is an empty string by default, which marks the image as decorative, so set it when the image carries meaning.

## Close Button

The `Chips` component can display a close button, allowing users to dismiss the chip. This is controlled by the `close` prop, which is set to `false` by default. To display the close button, set the `close` prop to `true`.

```html
<Chips close={true}>...</Chips>
```

Clicking the close button hides the chip.

## Sizes

The `Chips` component allows you to adjust its size using the `size` prop. This prop controls the dimensions of the chip's image. The available size options are: - **sm** (small) - **md** (medium) - *default* - **lg** (large)

Pick the size that matches the text around the chip.

```html
<Chips size="sm">...</Chips>
<Chips size="md">...</Chips>
<Chips size="lg">...</Chips>
```

The `size` prop only takes effect when an image is added using the `imgSrc` prop.

## Rounded Corner

The `rounded` prop in the `Chips` component controls its border radius. Values: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`. Default is `full`.

```html
<Chips rounded="none">...</Chips>
<Chips rounded="md">...</Chips>
<Chips rounded="lg">...</Chips>
<Chips rounded="xl">...</Chips>
<Chips rounded="full">...</Chips>
```

## Customization

The `Chips` component offers extensive customization options using Tailwind CSS classes. You can easily style both the chip and the accompanying image by applying custom classes through the `class` and `imgClasses` props.

### Chip Customization

To customize the chip's appearance, use the `class` prop to add your own Tailwind CSS classes. This allows you to control the border, background, padding, and more.

```html
<Chips class="border border-red-500 bg-yellow-200">Custom Chip</Chips>
```

### Image Customization

Similarly, you can style the image within the chip using the `imgClasses` prop. This lets you apply specific styles like borders, padding, and background to the image.

```html
<Chips imgClasses="border border-brand-500">...</Chips>
```

## Accessibility

The `Chips` component supports accessibility best practices. When an image is used, it includes proper `alt` text for screen readers. If the `close` prop is enabled, the close button includes an `aria-label` to describe its action, allowing users to remove chips with assistive technologies. When the `href` prop is set, the chip renders as a link; otherwise it gets `role="button"`. The component maintains proper semantics and structure for clear navigation and interaction.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `close` | boolean | `false` | Determines whether a close button is displayed on the chip. Set to true to show the close button. |
| `size` | 'sm' \| 'md' \| 'lg' | `md` | Sets the size of the chip's image. Only applies when imgSrc is set. 'md' is the default size. |
| `imgSrc` | string \| undefined | `undefined` | The URL of the image to display within the chip. Leave undefined if no image is used. |
| `imgClasses` | string | - | Custom CSS classes to apply to the chip's image for additional styling. |
| `altText` | string | - | The alternative text for the chip's image, enhancing accessibility. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Determines the border-radius style of the chip for rounded corners. |
| `href` | string \| undefined | `undefined` | If set, the chip is rendered as a link (`<a>`) pointing to this URL instead of a `<span>`. |

---

Source: https://www.theui.dev/docs/close

# Close Button

A close button to dismiss any component/element in your application.

This is a functional and accessible close button for your Svelte app. It is highly customizable and easy to use. You can use it to close or dismiss modals, popups, or any other elements.

## Example

Start by importing the Close button from the component library. It is the same dismiss button used inside `Alert`, `Chips`, `Modal` and `Drawer`, and you can use it anywhere you need that control.

```html
<script>
  import { Close } from "theui-svelte";
</script>

<Close />
```

## Close Icon

To use your own icon, put it inside the Close component and it replaces the default one.

You can use `svg` icon or **theui-svelte's** `Svg` component.

```html
<!-- Using HTML svg icon -->
<Close>
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
    <path d="M16 8A8 ... 0-.708-.708L8 7.293z"/>
  </svg>
</Close>

<!-- Using theui-svelte's Svg component -->
<Close>
  <Svg>
    <path d="M16 8A8 ... 0-.708-.708L8 7.293z"/>
  </Svg>
</Close>
```

## Icon Size

The `size` prop controls the size of the default close icon. It accepts a number, and the default value is `1.5`. It has no effect when you use your own icon; set the size on your icon instead.

```html
<Close size={1} />
<Close size={2.5} />
```

## Rounded Corner

The `rounded` prop sets the border radius of the close button. Available values are `"none"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"full"`. The corners are visible when the button has a background, focus ring or border.

```html
<Close rounded="none" class="bg-gray-200" />
<Close rounded="full" class="bg-gray-200" />
```

## Click Handler

Use the `onclick` prop to run a function when the close button is clicked, for example to hide the element it belongs to. The function receives the `MouseEvent`.

```html
<script>
  let visible = $state(true);
</script>

{#if visible}
  <div>
    Dismissible content
    <Close onclick={() => visible = false} />
  </div>
{/if}
```

## Customize Style

You can customize the button style simply writing the style classes just like as a native HTML element. Other attributes you add, like `id` or `data-*`, are passed to the button too.

```html
<Close class="bg-green-300 text-green-700" />
```

## Accessibility

`Close` renders a real `<button type="button">`, so it is reachable with `Tab` and pressed with `Enter` or `Space`. Its name comes from the `ariaLabel` prop, written as visually hidden text inside the button, which means the name survives even when you replace the icon with your own.

The default is `"Close"`. Say what is being closed whenever the page holds more than one thing that can be dismissed, because a screen reader user hears the name without the surrounding context you can see.

```svelte
<Close ariaLabel="Dismiss the newsletter popup" />
```

Closing something is only half the job: focus has to go somewhere sensible afterwards. `Modal` and `Drawer` hand focus back to whatever opened them, but in a panel of your own, move focus yourself to the control that opened it, or the keyboard lands back at the top of the page.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | number | `1.5` | Controls the size of the default close icon within the button. |
| `ariaLabel` | string | `Close` | Provides an accessible label for the close button, improving accessibility for screen readers. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the close button. |

### Functions

| Name | Description |
| --- | --- |
| `onclick` | Optional. Triggers when the close button is clicked. Type: `(e: MouseEvent) => void`. |

---

Source: https://www.theui.dev/docs/collapse

# Collapse

The Collapse component shows and hides a block of content. It comes unstyled, so the trigger and the body are yours to design.

## Example

Ensure you have the `Collapse` component available. Below is a simple example demonstrating how to use the Collapse component. This example shows how to toggle content using a button as the trigger:

```html
<script>
  import { Collapse } from "theui-svelte";
</script>

<Collapse ariaLabel="COLLAPSE">
  {#snippet trigger()}
    <Button>Flush collapse trigger</Button>
  {/snippet}
  <p> ..... </p>
</Collapse>
```

The `trigger` snippet `{"{" + "#snippet trigger()" + "}"}` defines the trigger for the collapse. In this case, a button labeled "Flush Collapse Trigger" acts as the clickable element to toggle the collapse.

Any component outside the trigger snippet will be considered as the content of the collapse and will be revealed or hidden based on the collapse state.

## Open State

The `isOpen` prop controls whether the collapse is open. It is `false` by default, so set it to `true` to open the collapse on page load. The prop is bindable: use `bind:isOpen` to read the current state or to open and close the collapse from outside the component.

```html
<script>
  let open = $state(true);
</script>

<Button onclick={() => open = !open}>Toggle from outside</Button>

<Collapse bind:isOpen={open}>
  {#snippet trigger()}
    <Button>Collapse trigger</Button>
  {/snippet}
  <p> ..... </p>
</Collapse>
```

## Animation Speed

The `animationSpeed` prop controls how fast the collapse opens and closes. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` (default), and `"faster"`. Set it to `"none"` to show and hide the content without animation.

```html
<Collapse animationSpeed="slower"> ... </Collapse>
<Collapse animationSpeed="none"> ... </Collapse>
```

## Accessibility

The `Collapse` component is fully accessible and keyboard-friendly. The toggle element uses `role="button"` and is focusable with `tabindex="0"`, allowing users to control it using the Enter or Space keys, and to close it using the Escape key. It includes `aria-expanded`, `aria-controls`, and `aria-labelledby` to communicate state and relationships clearly to assistive technologies. The content area is hidden from screen readers when collapsed using `aria-hidden`. You can also use the `ariaLabel` prop to provide a custom accessible label for better context.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | Snippet | `undefined` | The header or trigger content for the collapse. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `fast` | Controls the speed of the collapse animation. |
| `ariaLabel` | string | - | Accessible label for the collapse component. |
| `isOpen` | boolean | `false` | Defines if the collapse is open. Bindable: use bind:isOpen to read or control the open state from outside. |

### Snippets

| Name | Description |
| --- | --- |
| `trigger` | The trigger content for the collapse. |

---

Source: https://www.theui.dev/docs/container

# Container

The Container component is a flexible block element designed to control the spacing and structure of a web page. It provides a default padding setup but can be customized easily with your own classes.

## Setup & Example

Start by importing the Container component from the theui-svelte library. To use the Container component with its default settings, simply include it in your Svelte template:

```html
<script>
  import { Container } from "theui-svelte";
</script>

<Container>
  <!-- Content -->
</Container>
```

## Customization

For customization, you can add your own classes to adjust the spacing, alignment, or other styles:

```html
<Container class="bg-gray-100 py-8 px-0">
  <!-- Content -->
</Container>
```

The Container renders a `<section>` element. Any other attributes you add, like `id` or `aria-label`, are passed to it directly.

## Page Width

A `Container` grows to the width of its parent and stops at `--max-width`, which is `1280px` out of the box. The [`Navbar`](https://www.theui.dev/docs/navbar) reads the same variable for its inner row, so the brand and the links line up with the content below them. Change the one variable and both follow.

It is a plain CSS custom property on `:root`, not a Tailwind theme value, so you set it in your own CSS with no `@theme` block. Your stylesheet comes after `theui-svelte/style`, so your value is the one that applies.

**./src/app.css**

```css
@import 'tailwindcss';
@import 'theui-svelte/style';

:root {
  --max-width: 1400px;
}
```

Because it is inherited, you can also set it on one part of the page. Anything inside picks up the new width, and the rest of the site keeps the old one, which is how you give a single section room to breathe:

**A wider section**

```svelte
<div style="--max-width: 1600px">
  <Container>
    <!-- This one is wider than the rest of the page -->
  </Container>
</div>
```

For a one-off, a class is simpler than the variable: `<Container class="max-w-4xl">` overrides the width for that container alone, since the class comes last.

## Accessibility

`Container` renders a `<section>`. Left unnamed, that is treated as an ordinary block and changes nothing for assistive technology, which is what you want for a container that only sets width and spacing.

Add `aria-label` or `aria-labelledby` and it becomes a region landmark, listed alongside the banner, navigation and main areas of the page. Do that for an area people may want to jump straight to, and leave the rest unnamed: a page where everything is a landmark is as hard to move around as one with none.

**A container worth naming**

```svelte
<Container aria-labelledby="pricing-heading">
  <h2 id="pricing-heading">Pricing</h2>
  <!-- Content -->
</Container>
```

A `Container` is not a replacement for the landmarks a page needs anyway. Keep your `<header>`, `<nav>`, `<main>` and `<footer>`, and put containers inside them.

---

Source: https://www.theui.dev/docs/dark-mode

# DarkMode

The DarkMode component is a button that switches the page between light and dark mode. It stores the choice in local storage, so the next visit opens in the same theme.

## About

It toggles the `dark` class on the `<html>` element, which is what the library's dark variant keys off, so every component follows without any extra work.

## Example

Start by importing the DarkMode component from the theui-svelte library. Here's how to use the DarkMode component in your application:

```html
<script>
  import { DarkMode } from "theui-svelte";
</script>

<DarkMode />
```

This will render a theme switcher that toggles between light and dark themes.

## System Default Theme

The `systemDefault` prop decides where the first theme comes from. It is `true` by default, so the page opens in the device's color scheme until the visitor picks a theme themselves. Once they do, the stored choice wins.

If `systemDefault` is set to `false`, the app will load with the light theme by default. Users can still switch to their preferred theme manually after the initial load.

Once the user switches the theme, the choice is saved in `localStorage` under the `theui-theme` key and is used on the next visit instead of the system or default theme.

Set it to `false` and the page always opens in light mode until the visitor switches.

```html
<DarkMode systemDefault={false} />
```

## Theme Switch Icon

The `DarkMode` component comes with a default icon for the dark mode toggle button. However, you can easily replace this icon with your custom design. Simply add your custom SVG or other icon code inside the `DarkMode` component and the default icon will be replaced. You can use `svg` icon or **theui-svelte's** `Svg` component for this.

```html
<DarkMode>
   <svg class="dark:fill-yellow-200" ... >
      <path d="M6 .278a.77.77 0 0 ... 0-1.167.242-2.278.681-3.286"/>
   </svg>
</DarkMode>
<!-- or use the Svg component -->
<DarkMode>
   <Svg class="dark:fill-yellow-200">
      <path d="M6 .278a.77.77 0 0 ... 0-1.167.242-2.278.681-3.286"/>
   </Svg>
</DarkMode>
```

## Style Customization

For customization, you can add your own classes to adjust the spacing, alignment, or other styles:

      Here's how to use the DarkMode component in your application:

```html
<DarkMode class="bg-brand-500/20 text-brand-500 rounded-md p-2" />
```

## Accessibility

The `DarkMode` Button component toggles between light and dark themes, designed for accessibility.

- `aria-label="Toggle light or dark mode"`: Provides a clear description for screen readers about the button's function.

- `aria-pressed`: Indicates the button's current state (`true` for dark mode, `false` for light mode), giving feedback on whether the button is active.

- **Keyboard Accessibility**: the button is focusable and responds to `Enter` and `Space`.

**Best Practices**: Use the `aria-label` attribute for clear message to the screen readers. By default, the value is **"Toggle light or dark mode"**.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `systemDefault` | boolean | `true` | Determines how dark mode is handled. When true, the app initially adopts the system's preferred color scheme. A theme saved by the user takes priority. |

---

Source: https://www.theui.dev/docs/divider

# Divider

The Divider component draws a line between two pieces of content. It can run across or down, carry a label such as 'OR', and use a solid, dashed or dotted line.

## Example

Import the component and drop it between two blocks. On its own it renders a real `<hr>`, so it means something to a screen reader as well as to the eye.

```html
<script>
  import { Divider } from "theui-svelte";
</script>

<p>Everything above the line.</p>
<Divider />
<p>Everything below the line.</p>
```

## Variants

The `variant` prop sets the line style: `solid` (default), `dashed` or `dotted`.

```html
<Divider />
<Divider variant="dashed" />
<Divider variant="dotted" />
```

## Label

Put content inside the component and it is placed in the middle of the line. This is the usual way to write an **OR** between two sign-in options.

```html
<Divider>OR</Divider>
<Divider variant="dashed">Continue below</Divider>
```

## Label Alignment

With a label, the `align` prop decides where it sits: `center` (default), `start` or `end`. The alignment follows the text direction, so it flips on a right to left page.

```html
<Divider align="start">Start</Divider>
<Divider align="center">Center</Divider>
<Divider align="end">End</Divider>
```

## Vertical Divider

Set `orientation="vertical"` to separate items that sit side by side. The divider takes the height of its parent, so place it in a flex row with a height.

```html
<div class="flex h-16 items-center gap-4">
  <span>Profile</span>
  <Divider orientation="vertical" />
  <span>Settings</span>
  <Divider orientation="vertical" variant="dashed" />
  <span>Sign out</span>
</div>
```

## Vertical Label

A vertical divider takes a label too. The line is drawn above and below the text.

```html
<div class="flex h-40 items-center gap-4">
  <span>Sign in</span>
  <Divider orientation="vertical">OR</Divider>
  <span>Create account</span>
</div>
```

## Customization

Use `lineClasses` for the line and `labelClasses` for the text. The `class` prop goes on the element itself, which is where spacing belongs.

```html
<Divider lineClasses="border-brand-500" />
<Divider lineClasses="border-2 border-info-500" variant="dashed" />
<Divider class="my-8" labelClasses="rounded-full bg-brand-500 px-3 py-1 text-xs font-semibold text-on-brand">
  NEW
</Divider>
```

## Accessibility

Without a label the component renders an `<hr>`, or a vertical separator with `aria-orientation="vertical"`, both of which assistive technology understands as a break between sections. With a label, the lines are hidden from screen readers and only the text is read, because a separator cannot hold a name of its own. Decoration alone does not need a divider: if the parts are already separate landmarks or headings, the line adds nothing.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | [DIVIDER_ORIENTATION](https://www.theui.dev/docs/types#divider-orientation-type) | `horizontal` | Direction of the line: "horizontal" or "vertical". A vertical divider takes the height of its parent. |
| `variant` | [DIVIDER_VARIANT](https://www.theui.dev/docs/types#divider-variant-type) | `solid` | Line style: "solid", "dashed" or "dotted". |
| `align` | [DIVIDER_ALIGN](https://www.theui.dev/docs/types#divider-align-type) | `center` | Where the label sits along the line: "start", "center" or "end". Only used when there is a label. |
| `lineClasses` | string | `` | Custom classes for the line, such as its colour or thickness. |
| `labelClasses` | string | `` | Custom classes for the label. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the divider element, merged with the default classes. Spacing belongs here. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label placed in the middle of the line. Without it the component renders a plain rule. |

---

Source: https://www.theui.dev/docs/drawer

# Drawer

The Drawer component slides a panel in from the edge of the screen. Use it for navigation, filters, or any content that does not need to take over the page.

## Example

Import the `Drawer` component first to use it in your application. Here's a basic example demonstrating how to use the Drawer component:

```html
<script>
  import { Drawer } from "theui-svelte";
</script>

<Drawer label="Open Drawer">
  <div class="p-8">
    Drawer content
  </div>
</Drawer>
```

In this example, the `Drawer` slides in from the left side of the screen which is the default behavior. The `label` prop creates the button that toggles the visibility of the Drawer. You can replace the content inside the Drawer with any elements you need.

## Position

The `position` prop allows you to control where the Drawer appears on the screen. You can choose from four positions: `top`, `end`, `bottom`, or `start`. This flexibility lets you tailor the Drawer's placement to fit the layout and design of your application.

Set the `position` prop to change which edge the Drawer opens from.

```html
<Drawer ... position="start">...</Drawer> <!-- Default position -->
<Drawer ... position="top">...</Drawer>
<Drawer ... position="end">...</Drawer>
<Drawer ... position="bottom">...</Drawer>
```

## Fullscreen Drawer

Add the `fullscreen` attribute to make the Drawer cover the entire screen. It still slides in from the side set by the `position` prop. A fullscreen Drawer has no backdrop; use the close button or Escape to close it.

```html
<Drawer label="Fullscreen" fullscreen>...</Drawer>
```

## Trigger Customization

Use the `buttonClasses` prop to style the trigger created from the `label` prop. The classes are applied to the trigger button, or to the trigger wrapper when `label` is a snippet.

```html
<Drawer label="Custom trigger" buttonClasses="bg-emerald-600 text-white rounded-full">...</Drawer>
```

Anything else you pass reaches the element itself, so a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`. The `id` is the exception: the component sets its own so the trigger button can point at the panel with `aria-controls`.

## Outlying Trigger

You can open or close the `Drawer` from outside by binding a reactive variable to its `open` prop. This is useful when the trigger button is placed elsewhere in your layout.

```html
<script>
  let openDrawer: boolean = $state(false)
</script>

<!-- Outlaying button -->
<Button onclick={()=>openDrawer=!openDrawer}>Trigger drawer</Button>

<Drawer bind:open={openDrawer}>
  <!-- Drawer content -->
</Drawer>
```

The `Button` updates the `openDrawer` state, and the `Drawer` reacts to it. This allows full control from any part of your component.

## Backdrop

### Custom Backdrop Style

The Drawer includes a backdrop which is enabled by default. It can be toggled or styled using the backdrop prop. Set it to `false` to disable it, `true` for a default backdrop or provide a custom classes for styling.

```html
<Drawer ... backdrop="bg-red-500">...</Drawer>
```

### Preventing Backdrop Click

By default, the Drawer closes when the user clicks on the backdrop. This behavior helps users easily dismiss the Drawer by clicking outside of it, enhancing usability in most scenarios.

Set `staticBackdrop` to `true` and a click on the backdrop no longer closes it, which is what you want when the visitor is part way through something.

```html
<Drawer ... staticBackdrop={true}>...</Drawer>
```

### Disable Backdrop

If you prefer not to use a backdrop, you can easily disable it by setting the `backdrop` prop to `false`. This will remove the backdrop entirely from the Drawer component

```html
<Drawer ... backdrop={false}>...</Drawer>
```

## Animation Speed

The animationSpeed prop controls how quickly the Drawer appears or disappears. It supports the following values: `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` (default), and `"faster"`.

Use it to set how fast the panel slides in and out.

```html
<Drawer animationSpeed="slower" ...> ... </Drawer>
<Drawer animationSpeed="slow" ...> ... </Drawer>
<Drawer animationSpeed="normal" ...> ... </Drawer>
<Drawer animationSpeed="fast" ...> ... </Drawer>
<Drawer animationSpeed="faster" ...> ... </Drawer>
<Drawer animationSpeed="none" ...> ... </Drawer>
```

## Accessibility

The `Drawer` component follows accessibility best practices:

- The trigger element uses `aria-controls` and `aria-expanded` to describe its relationship with the **Drawer**. A string `label` is announced by its text; a snippet trigger uses `aria-label` from the `ariaLabel` prop.

- Supports both text labels and custom elements, with keyboard interactions (Enter/Space key) for non-button triggers.

- The Drawer container uses `role="complementary"` and references the trigger using `aria-labelledby`. Without a `label`, the Drawer panel gets `aria-label` from the `ariaLabel` prop instead.

- `aria-hidden` is used to hide the Drawer from assistive technologies when it's not active.

- When closed, the Drawer is marked `inert`, so its content can't be focused or reached with the keyboard.

- The backdrop uses `role="presentation"` to avoid it being announced by screen readers.

- Pressing Escape closes the open Drawer.

- A visible and accessible Close button is included for easy dismissal.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string \| Snippet | `undefined` | The label or trigger content for the Drawer component. A string renders as plain text; use a Snippet for markup. |
| `position` | 'top' \| 'end' \| 'bottom' \| 'start' | `start` | Drawer position relative to screen. |
| `open` | boolean | `false` | Controls the visibility of the Drawer. Bindable: use bind:open to programmatically open or close the Drawer. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `fast` | Speed of the animation when the component is shown or hidden. |
| `backdrop` | boolean \| string | `true` | Toggle or style the Drawer backdrop. |
| `staticBackdrop` | boolean | `false` | Prevent Drawer from closing on backdrop click. |
| `buttonClasses` | string | - | Classes for the drawer trigger button. |
| `ariaLabel` | string | `Drawer` | Accessible name used when the trigger is a snippet (set on the trigger), or when there is no `label` (set on the Drawer panel). A string `label` uses its own text as the name. |

### Dynamic props

| Name | Description |
| --- | --- |
| `fullscreen` | Use the fullscreen prop to make the Drawer component take up the entire screen. |
| `class` | Any CSS classes used in the class prop will be applied to the Drawer body directly. It will override the default classes. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Main content of the component. |
| `label` | The element that triggers the opening of the component. |

---

Source: https://www.theui.dev/docs/dropdown

# Dropdown

The Dropdown component shows a list of links or actions in a menu that opens from a trigger. Use it for account menus, settings, and any place where a row of buttons would take too much room.

## About

The menu opens on click or on hover, depending on `triggerEvent`. Alignment, animation style and animation speed are all props. Each item can be a link, a button, a header or a divider.

## Example

To use the Dropdown component in your project, you first need to import it along with the DropdownItem component. Here's how you can set up the Dropdown in your Svelte component.

Here's a simple example of how to implement the Dropdown component. It includes a label and multiple DropdownItem components, which represent the individual links or actions within the dropdown.

```html
<script>
  import { Dropdown, DropdownItem } from "theui-svelte";
</script>

<Dropdown label="Dropdown">
  <DropdownItem href="/">Link 1</DropdownItem>
  <DropdownItem href="/">Link 2</DropdownItem>
  <DropdownItem href="/">Link 3</DropdownItem>
</Dropdown>
```

In this example, the Dropdown is triggered by a label ("Dropdown"), and it contains three items, each with a URL and text.

## Dropdown Sizing

The width of the Dropdown component can be customized using the `width` prop. You can choose from predefined sizes or set a custom width to suit your design needs. Here's a breakdown of the available options:

- **auto**: The Dropdown will automatically adjust its size based on its content.

- **sm**: A small size for compact dropdowns.

- **md**: The default medium size for a standard dropdown.

- **lg**: A large size for more prominent dropdowns.

- **full**: The dropdown will take up the full width of its container.

- **Any width class**: Pass a Tailwind width class, such as `width="w-[300px]"`, to size the dropdown yourself.

```html
<!-- Automatically adjusts the size based on content -->
<Dropdown width="auto"> ... </Dropdown>

<!-- Small dropdown -->
<Dropdown width="sm"> ... </Dropdown>

<!-- Default medium size dropdown -->
<Dropdown width="md"> ... </Dropdown>

<!-- Large dropdown -->
<Dropdown width="lg"> ... </Dropdown>

<!-- Full-width dropdown -->
<Dropdown width="full"> ... </Dropdown>

<!-- Custom width - pass any TailwindCSS width class -->
<Dropdown width="w-[300px]"> ... </Dropdown>

```

In these examples, the `width` prop allows you to quickly adjust the appearance of the dropdown to fit different design needs. The default is `"md"`.

## Alignment

The `align` prop in the Dropdown component controls the alignment of the dropdown menu relative to its trigger. You can choose between two options:

- **start**: Aligns the dropdown to the start (left) of the trigger element.

- **end**: Aligns the dropdown to the end (right) of the trigger element. This is the default alignment.

```html
<!-- Align dropdown to the start (left) of the trigger -->
<Dropdown align="start"> ... </Dropdown>

<!-- Default alignment (align to the right of the trigger) -->
<Dropdown align="end"> ... </Dropdown>
```

## Dropdown Trigger Event

The `triggerEvent` prop defines how the dropdown is triggered. By default, the dropdown opens when clicked, but you can change this behavior to trigger on hover by setting it to `"hover"`.

```html
<Dropdown triggerEvent="click"> ... </Dropdown> <!-- Default -->
<Dropdown triggerEvent="hover"> ... </Dropdown>
```

## Custom Dropdown Trigger

The `label` prop allows you to set a custom label for the dropdown trigger. You can either use a plain text string or define a custom trigger element using the `snippet` block.

- **label as props**: Directly set the trigger label as a prop.

- **label as snippet**: Define a custom trigger with any HTML or component structure.

The trigger is named by its own content, so a trigger with visible text needs nothing else. If your trigger is only an icon or an image, give the dropdown an `ariaLabel`, for example `ariaLabel="Account menu"`, so screen reader users know what it opens.

```html
<!-- Dropdown label by prop -->
<Dropdown label="Dropdown text label"> ... </Dropdown>

<!-- Custom dropdown label by Snippet -->
<Dropdown>
  {#snippet label()}
    <span class="...">Dropdown snippet label</span>
  {/snippet}
</Dropdown>
```

## Animation

Based on your design requirements, you can customize the animation type and the speed of the `Dropdown` using the `animation` and `animationSpeed` props.

### Animation Type

The `animation` prop controls how the menu appears when it opens. The default is `slide-up`.

- **slide-left**: The dropdown slides in from the left.

- **slide-up**: The default animation, sliding in from the bottom.

- **slide-right**: Slides in from the right.

- **slide-down**: Slides in from the top.

- **fade**: A smooth fade-in animation.

- **zoom-in**: The dropdown zooms in from a smaller size.

- **zoom-out**: The dropdown zooms out from a larger size.

```html
<Dropdown animation="slide-left"> ... </Dropdown>
<Dropdown animation="slide-up"> ... </Dropdown>  <!-- Default -->
<Dropdown animation="slide-right"> ... </Dropdown>
<Dropdown animation="slide-down"> ... </Dropdown>
<Dropdown animation="fade"> ... </Dropdown>
<Dropdown animation="zoom-in"> ... </Dropdown>
<Dropdown animation="zoom-out"> ... </Dropdown>
```

### Animation Speed

The `animationSpeed` prop controls the speed of the dropdown animation, allowing for smooth transitions at different paces. It accepts the following values `none`, `slower`, `slow`, `normal`, `fast` and `faster`

```html
<Dropdown animationSpeed="slower"> ... </Dropdown>
<Dropdown animationSpeed="slow"> ... </Dropdown>
<Dropdown animationSpeed="medium"> ... </Dropdown>
<Dropdown animationSpeed="fast"> ... </Dropdown>
<Dropdown animationSpeed="faster"> ... </Dropdown>
<Dropdown animationSpeed="none"> ... </Dropdown>
```

## Arrow Icon

The trigger shows a chevron that rotates when the dropdown opens. Set `arrowIcon={false}` to hide it, or pass a snippet to replace it with your own icon. The snippet is rendered in place of the chevron, so any rotation or transition is up to you.

```html

<!-- Default chevron -->

<Dropdown label="With arrow"> ... </Dropdown>

<!-- No icon -->

<Dropdown label="No arrow" arrowIcon={false}> ... </Dropdown>

<!-- Your own icon -->

<Dropdown label="Custom arrow">

  {#snippet arrowIcon()}

    <span class="ms-1">+</span>

  {/snippet}

  ...

</Dropdown>

```

## Dropdown Backdrop

The `backdrop` prop determines whether a backdrop is shown behind the dropdown. When set to `true`, a backdrop is displayed; by default, it is set to `false`, meaning no backdrop is shown.

```html
<!-- With backdrop -->
<Dropdown backdrop={true}> ... </Dropdown>

<!-- Without backdrop -->
<Dropdown backdrop={false}> ... </Dropdown>
```

## Close on Outside Click

An open dropdown closes by itself when you click anywhere outside it, when you choose an item, and when you press `Escape`. There is no prop to turn this off. Clicking a header, a divider or empty space inside the menu keeps it open.

In **hover** mode the dropdown also closes shortly after the pointer leaves it, so a small move off the menu does not close it instantly.

## Dropdown Item

### Item Types

The `DropdownItem` component supports four native types for consistent UI: link, button, header, and divider. The type of each item is controlled by the `type` prop, which defaults to `link`. The `type` prop can be set to `'link' | 'divider' | 'header' | 'button'`.

- **link**: The default type, renders a standard hyperlink.

- **button**: Renders a clickable button within the dropdown.

- **header**: Creates a non-clickable header to separate sections.

- **divider**: Adds a visual divider to separate items.

You can also add custom items, but these four types are provided natively for a consistent UI experience.

A **link** item needs an `href`; without one it renders as a button. The item content is what you write inside the component, or you can pass it as the `text` prop, which renders as plain text. For markup, write the content inside the component.

```html
<Dropdown label="Dropdown">
  <!-- Header item -->
  <DropdownItem type="header">Section Header</DropdownItem>
  <!-- Link item (default) -->
  <DropdownItem href="/">Link 1</DropdownItem>
  <DropdownItem href="/">Link 2</DropdownItem>
  <!-- Divider item -->
  <DropdownItem type="divider" />
  <!-- Button item -->
  <DropdownItem type="button">Button 1</DropdownItem>
</Dropdown>
```

This setup ensures your dropdown maintains a uniform appearance and functionality across different types of items.

### Before and After Items

The `DropdownItem` component provides two snippet blocks, `startItem` and `endItem`, for adding custom content before or after the dropdown text.

- **startItem**: Displays content before the dropdown text, ideal for icons, images, or similar elements.

- **endItem**: shows content after the item text, such as a badge, a shortcut hint or a second icon.

```html
<Dropdown label="Dropdown" width="md">
  <DropdownItem href="/">
    {#snippet startItem()}
      <Svg>
        <path d="M8 16a2 2 0 0 ... 13 6c0 .88.32 4.2 1.22 6"/>
      </Svg>
    {/snippet}
    Notification
  </DropdownItem>
  <DropdownItem href="/">
    Notification
    {#snippet endItem()}
      <Badge>New</Badge>
    {/snippet}
  </DropdownItem>
  <DropdownItem href="/">
    {#snippet startItem()}
      <Svg>
        <path d="M8 16a2 2 0 0 ... 13 6c0 .88.32 4.2 1.22 6"/>
      </Svg>
    {/snippet}
    Notification
    {#snippet endItem()}
      <Badge>New</Badge>
    {/snippet}
  </DropdownItem>
</Dropdown>
```

The two snippets let you put content on either side of the item text without changing its layout.

### Custom Item

The `DropdownItem` component also supports fully custom content, allowing you to create items beyond the predefined types. By using custom markup within `DropdownItem`, you can design complex or unique dropdown items to fit your specific needs.

```html
<Dropdown label="Custom Dropdown" width="md">
  <DropdownItem href="/" class="hover:bg-brand-500 ... flex-wrap">
    <div class="w-full text-start">
      <p class="font-bold">Svelte 5 Component</p>
      Kickstart your ... ecosystem.
    </div>
  </DropdownItem>
</Dropdown>
```

This way you write the item markup yourself, so the content and the styling are entirely yours.

## Active State

The `active` prop in the `DropdownItem` component is used to indicate whether the item is currently active. This prop accepts a boolean value and defaults to `false`. When set to `true`, the item will appear highlighted to show it is active.

```html
<Dropdown label="Dropdown">
  <DropdownItem href="/">Link</DropdownItem>
  <DropdownItem href="/" active={true}>Active Link</DropdownItem>
  <DropdownItem href="/">Link</DropdownItem>
</Dropdown>
```

Using the active prop helps visually distinguish the selected or currently active item within the dropdown.

## Customization

The `Dropdown` component provides several props to customize the appearance of the dropdown items and container. These props allow you to apply custom classes for different elements, giving you full control over the styling.

- **containerClasses**: Custom classes for the outer dropdown container.

- **dropdownClasses**: Customizes the dropdown content area.

- **itemClasses**: Sets custom classes for regular dropdown items.

- **activeItemClasses**: Applies custom classes to the active dropdown item.

- **dividerClasses**: Customizes the appearance of divider items.

- **headerClasses**: Adds custom styling to header items within the dropdown.

- **buttonClasses**: Styles the trigger itself, for example `buttonClasses="w-full"` to make it fill its container.

```html
<Dropdown
  label="Customized Dropdown"
  containerClasses="border-4 rounded-xl"
  dropdownClasses="shadow-lg bg-green-50"
  itemClasses="text-green-500 hover:bg-green-100"
  activeItemClasses="text-white bg-green-500"
  dividerClasses="border-b-2 border-green-200"
  headerClasses="text-green-600 text-xs"
>
  <DropdownItem href="/">Link 1</DropdownItem>
  <DropdownItem type="header">Section Header</DropdownItem>
  <DropdownItem type="divider" />
  <DropdownItem href="/" active={true}>Link 2</DropdownItem>
</Dropdown>
```

These props cover the trigger, the menu and the items, so each part can be styled on its own.

## Accessibility

The Dropdown component follows WAI-ARIA best practices.

- The trigger button uses `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` to describe the dropdown behavior. Its name comes from the trigger content; set `ariaLabel` when the trigger has no visible text.

- The dropdown list uses `role="menu"` with each item using appropriate roles: `menuitem` on the link or button of each item

- a heading element for group labels

- `separator` for dividers

- On the trigger, `ArrowDown` opens the menu, `ArrowUp` and `Escape` close it, and `Enter` or `Space` toggles it. Keys pressed on an item are left to that item, so `Enter` follows a link, and `Escape` still closes the menu and moves focus back to the trigger.

## Configuration

---

Source: https://www.theui.dev/docs/fieldset

# Fieldset

The Fieldset component is a wrapper for input groups, providing better structure and styling control. It helps in grouping related inputs together while maintaining a consistent design.

## About

The `Fieldset` component allows you to manage input styles and behaviors, but at a more granular level. While the `Form` component ensures uniform styling across all form elements, the Fieldset component lets you separate a section of inputs from others, giving you more control over a specific input group.

This is particularly useful when you want to style or configure a subset of inputs differently from the rest of the form. It supports floating labels, different variants, animations, and more.

## Example

The Fieldset component is useful when you need to group related inputs under a common title while maintaining a structured layout. Below are some examples of how you can use it.

```html
<script>
  import { Fieldset } from "theui-svelte";
</script>

<Fieldset title="User Information">
  <!-- Add your form inputs here -->
</Fieldset>
```

## Group Input Settings

A `Fieldset` passes the `variant`, `size`, `floatingLabel`, `rounded`, `animationSpeed`, `labelClasses` and `reset` props down to the inputs inside it. When the Fieldset is inside a `Form`, any of these props you don't set are taken from the Form, so you only override what should differ for this group. Each input can still override the settings with its own props.

```html
<Form>
  <Input name="name">Your name</Input>
  <Fieldset title="Address Details" variant="flat" size="sm">
    <Input name="street">Street</Input>
    <Input name="city">City</Input>
  </Fieldset>
</Form>
```

In this example, the name input uses the Form's default style, while the address inputs use the flat variant and small size set on the Fieldset.

## Accessibility

Use `Fieldset` to semantically group related inputs like checkboxes or radios. When you set the `title` prop, it adds a visually hidden `legend` so screen readers can announce the purpose of the group. The markup stays clean and the group is announced properly.

## Configuration

Some of the `Fieldset` props are not used by the fieldset itself. They are handed down to the inputs inside it, so you can set them once instead of on every field.

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string | `undefined` | Legend or title of the fieldset for the assertive technology. Only visible to the screen readers. No legend is rendered when it is not set. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `Inherited from Form or "bordered` | Defines the visual style of the inputs. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Form or "md` | Defines the size of the inputs: "sm", "md", "lg" or "xl". |
| `floatingLabel` | boolean | `true if the Fieldset sets its own "flat" variant; otherwise inherited from Form, or true if variant is "flat` | Enables or disables floating labels for inputs. If variant is set to "flat", this defaults to true and false otherwise. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Form or "normal` | Controls the animation speed for inputs. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `Inherited from Form or "md` | Controls the border radius of inputs. |
| `labelClasses` | string | `Inherited from Form or "` | Allows custom CSS classes to be applied to input labels for additional styling. |
| `reset` | boolean | `Inherited from Form or false` | Resets all the defaults styles and apply only the custom styles. |

---

Source: https://www.theui.dev/docs/file-input

# FileInput

The FileInput component is a customizable wrapper for file selection, providing a more flexible and consistent way to handle file uploads in forms.

## About

The `FileInput` component styles the native file input and reads its settings from the Form or Fieldset around it, so it matches the other fields. Size, shape and classes are all props.

## Example

Put the `FileInput` inside a form or a fieldset and it picks up their settings. Here's a basic example:

```html
<script>
  import { FileInput } from "theui-svelte";
</script>

<FileInput name="document">Upload</FileInput>
```

The `name` prop is mandatory for the FileInput component. It ensures the input field is properly recognized when submitting a form. Without a name, the uploaded file data will not be sent. The content inside the `FileInput` component will be display as a label.

## Selected Files

The `files` prop holds the selected files as a `FileList`. It is bindable, so use `bind:files` to read what the user picked, for example to show the file names or upload them yourself. Add the native `multiple` attribute to allow more than one file, and `accept` to limit the file types.

```html
<script>
  let files = $state();
</script>

<FileInput name="documents" bind:files multiple accept=".pdf,.docx">Upload</FileInput>

{#if files?.length}
  <ul>
    {#each Array.from(files) as file}
      <li>{file.name}</li>
    {/each}
  </ul>
{/if}
```

## Size

The `size` prop sets the padding and the height of the field, on the same scale as the other form components. Available sizes: `"sm"`, `"md"` (default), `"lg"` and `"xl"`.

By default, the `FileInput` inherits the `size` from the nearest Fieldset or Form component. However, you can override it manually if needed.

```html
<FileInput name="document" size="sm">Upload</FileInput>
<FileInput name="document" size="md">Upload</FileInput>
<FileInput name="document" size="lg">Upload</FileInput>
<FileInput name="document" size="xl">Upload</FileInput>
```

## Variant

The `variant` prop controls the visual style of the FileInput, allowing you to adjust its appearance based on form design preferences. Available values: `"bordered"` (default) and `"flat"`.

If the `FileInput` is inside a **Fieldset** or **Form** , it inherits the `variant` automatically unless explicitly set.

```html
<FileInput name="document" variant="bordered">Upload</FileInput>
<FileInput name="document" variant="flat">Upload</FileInput>
```

## Rounded

The `rounded` prop defines the border-radius of the FileInput, giving it different levels of rounded corners. Available values: `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"`, `"full"`, `"none"`. It applies to the input and its file button.

By default the `FileInput` takes its `rounded` value from the **Fieldset** or **Form** around it.

```html
<FileInput name="document" rounded="none">Upload</FileInput>
<FileInput name="document" rounded="sm">Upload</FileInput>
<FileInput name="document" rounded="md">Upload</FileInput>
<FileInput name="document" rounded="lg">Upload</FileInput>
<FileInput name="document" rounded="xl">Upload</FileInput>
<FileInput name="document" rounded="full">Upload</FileInput>
```

## Helper Text

The `helperText` prop allows you to add additional guidance or information below the file input field. This can be useful for providing instructions, specifying accepted file formats, or any other relevant details for the user. You can pass either a **string** or a **Snippet** as the helper text.

```html
<FileInput name="document" helperText="Accepted formats: PDF, DOCX. Max size: 5MB.">Upload</FileInput>
```

Or using a Snippet for more flexibility:

```html
<FileInput name="document">
  Upload
  {#snippet helperText()}
    Accepted formats: PDF, DOCX. Max size: 5MB.
  {/snippet}
</FileInput>
```

## Customization

The `FileInput` component provides several ways to customize its appearance to match your design requirements. The `size`, `variant`, `rounded` and `reset` props are inherited from the nearest **Fieldset** or **Form**. You can modify the container, label, and input field styles using the following props:

- `labelClasses` - Custom styles for the label of the FileInput. If used within a Fieldset or Form component, it inherits their `labelClasses`.

- `wrapperClasses` - Additional classes for the wrapper , useful for layout adjustments.

- `class` - Apply custom styles to the file input itself.

```html
<FileInput
  name="document"
  wrapperClasses="flex-row items-center justify-between gap-8"
  labelClasses="text-xl font-semibold uppercase"
  class="focus:ring-2 focus-within:ring-purple-500 focus:ring-purple-500 bg-purple-100 file:bg-purple-300"
  variant="flat"
>
  Upload
</FileInput>
```

## Accessibility

Uploading files should be simple - and accessible. Our File component pairs each file input with a clear, connected `<label>`, and uses `aria-describedby` to guide screen readers to any helpful hints or messages. It's a smooth, informative experience for all users, whether navigating with a mouse or a screen reader.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `files` | FileList \| undefined | `undefined` | The selected file(s). Bindable: use `bind:files` to read what the user picked. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Controls the size of the file input, affecting its padding and overall dimensions. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `Inherited from Fieldset or Form, or "bordered` | Defines the visual style of the input field: "bordered" or "flat". |
| `helperText` | Snippet \| string | `undefined` | Displays additional information below the file input, linked with `aria-describedby`. A string renders as plain text; use the snippet for markup. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `Inherited from Fieldset or Form, or "md` | Defines the border-radius of the input and its file button. Options: "none", "sm", "md", "lg", "xl", "2xl", "full". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | If true, resets all default library styles, allowing for full custom styling. |
| `labelClasses` | string | `Inherited from Fieldset or Form, or "` | Applies custom CSS classes to style the label of the file input. |
| `wrapperClasses` | string | `undefined` | Allows custom styling for the main wrapper container of the file input. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the file input, dims it and sets `aria-disabled="true"`. |
| `multiple` | Allows selecting more than one file. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The label content of the file input. |
| `helperText` | Helper text shown below the input, as an alternative to the string prop. |

---

Source: https://www.theui.dev/docs/form

# Form

A reusable wrapper for the HTML form element, simplifying form creation, submission handling, event management and controlling all the inputs from a single place.

## About

The `Form` component is a wrapper around the native `<form>` element. You do not have to use it, but it is where the shared input settings live: set `variant`, `size`, `rounded` or `floatingLabel` once on the form and every field inside picks them up.

## Example

To use the **Form** component, simply import it from the library and wrap your form inputs inside it. Here's a basic example:

```html
<script>
  import { Form } from "theui-svelte";
</script>

<Form>
  <!-- Add your form inputs here -->
</Form>
```

Every input inside it picks up those settings, so a change in one place reaches the whole form.

## Form Method

The `method` prop specifies the HTTP method to be used when the form is submitted. It corresponds to the native HTML `method` attribute of the **** element. Available values are `GET` and `POST`. Default `POST`.

```html
<Form method="GET">
  <!-- Form inputs go here -->
</Form>
```

In this example, the form will use the `GET` method when submitted, appending the form data to the URL. If no `method` is specified, it defaults to `POST`.

## Shared Input Settings

The `Form` component passes these props down to all the inputs inside it, so you can style every input from one place:

- `variant`: `"bordered"` (default) or `"flat"`.

- `size`: `"sm"`, `"md"` (default), `"lg"` or `"xl"`.

- `floatingLabel`: shows the label inside the input and moves it up on focus. It is `true` by default for the `"flat"` variant and `false` otherwise.

- `rounded`: the border radius of the inputs. The default is `"md"`.

- `animationSpeed`: the transition speed of the inputs and floating labels. The default is `"normal"`.

- `labelClasses`: custom classes for all the input labels.

- `reset`: removes the default input styles so only your own classes apply. The default is `false`.

A `Fieldset` inside the form can override these settings for its own inputs, and each input can override them with its own props.

```html
<Form variant="flat" size="lg">
  <Input name="name">Your name</Input>
  <Input name="email" type="email">Email address</Input>
  <Button type="submit">Submit</Button>
</Form>
```

## Progressive Enhancement

The `enhance` prop accepts a Svelte action that is applied to the `<form>` element. Pass SvelteKit's `enhance` action to submit the form without a full page reload, while keeping it working when JavaScript is unavailable.

```html
<script>
  import { enhance } from "$app/forms";
  import { Form } from "theui-svelte";
</script>

<Form action="?/login" {enhance}>
  <!-- Form inputs go here -->
</Form>
```

## Accessibility

The `Form` component renders a native `<form>` element, which browsers and screen readers already understand. Any **ARIA** role, label or attribute you pass is spread onto it, so you can add whatever a particular page needs.

## Configuration

Some of the `Form` props are not used by the form element itself. They are handed down to the inputs inside it, so you set them once instead of on every field.

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `method` | 'GET' \| 'POST' | `POST` | Defines the form submit method. |
| `enhance` | Action<HTMLFormElement> | `undefined` | A Svelte action applied to the form element, like SvelteKit's `enhance` from `$app/forms`. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Defines the visual style of the inputs. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Defines the size of the inputs: "sm", "md", "lg" or "xl". |
| `floatingLabel` | boolean | `true (if variant == "flat")` | Enables or disables floating labels for inputs. If variant is set to "flat", this defaults to true and false otherwise. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed for inputs. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Controls the border radius of inputs. |
| `labelClasses` | string | `undefined` | Allows custom CSS classes to be applied to input labels for additional styling. |
| `reset` | boolean | `false` | Resets all the defaults styles and apply only the custom styles. |

---

Source: https://www.theui.dev/docs/helper-text

# Helper Text

The text under a form field: a description, a hint or an error message. It takes plain text or any markup you put inside it.

## About

The `HelperText` component shows a hint, an instruction or a validation message under a form input. Everything you place inside it becomes the helper text, so it can hold plain text or any elements and components.

The `Input`, `Select` and `FileInput` components use it internally through their `helperText` prop, which also links it to the input with `aria-describedby`. Use `HelperText` directly when you build a field yourself.

## Example

To use the **HelperText** component, place the text inside it. Here's a basic example:

```html
<script>
  import { HelperText } from "theui-svelte";
</script>

<HelperText>Please enter your full name.</HelperText>
```

## Helper Text Content

The content can be plain text or any mix of elements and components, which makes it flexible for hints, messages, or interactive content. A `HelperText` without content renders nothing.

```html
<!-- Plain text -->
<HelperText>Passwords must be at least 8 characters long.</HelperText>

<!-- With elements -->
<HelperText><strong>Note:</strong> This field is required.</HelperText>
```

## Use With an Input

With `Input`, `Select` and `FileInput`, pass the helper text through the `helperText` prop instead of using the component directly. Those components render a `HelperText` for you, give it an `id` and link it to the input with `aria-describedby`, so screen readers read it together with the label.

```html
<Input name="password" type="password" helperText="Must be at least 8 characters long">Password</Input>
```

## Customization

The `HelperText` component can be customized using the `class` attribute to apply additional styles or override default ones. Any other attributes you add, like `id` or `data-*`, are passed to the element.

```html
<HelperText class="text-blue-600 italic">Please enter your full name.</HelperText>
```

## Accessibility

`HelperText` gives users additional guidance without distraction, and is styled to stay secondary in the visual hierarchy. When you use it through the `helperText` prop of an input, it is connected to that input with `aria-describedby` automatically. When you use the component directly, give it an `id` and add `aria-describedby` with that id to your input, so screen readers announce the two together.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | `<RANDOM STRING>` | The id of the helper text element. Use it with `aria-describedby` on your input. |
| `class` | string | `undefined` | Custom classes merged with the default helper text styles. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The helper text content. It is required; a HelperText without content renders nothing. |

---

Source: https://www.theui.dev/docs/input

# Input

The Input component covers the standard HTML input types, plus textarea. It takes its size, variant and shape from the Form or Fieldset around it.

## About

There is no separate textarea component: pass `type="textarea"` and the `Input` renders one. The label, the helper text and the `aria-describedby` link between them are wired up for you, and the styling comes from the Form or Fieldset around the field.

## Example

Here's a basic example of the Input component in action:

```html
<script>
  import { Input } from "theui-svelte";
</script>

<Input placeholder="Type your full name">Name</Input>
```

## Input Type

The **Input** component supports various input types, making it a flexible solution for different use cases. Whether you need a standard text field, a password input, or a date picker, this component adapts to your needs. To specify the type of input, use the `type` prop. Here's an example:

```html
<Input type="text" name="username" placeholder="Enter your username">Username</Input>
<Input type="email" name="email" placeholder="Enter your email">Email</Input>
<Input type="password" name="password" placeholder="Enter your password">Password</Input>
<Input type="date" name="dob">Date of birth</Input>
<Input type="url" name="url" placeholder="Enter your profile URL">URL</Input>
<Input type="number" name="days" placeholder="Enter numbers">Number of days</Input>
```

Other available input types are: `datetime-local`, `month`, `tel`, `time`, `week`, `search`, `textarea`.

## Textarea

When the `type` prop is set to `"textarea"`, the Input component renders a **** instead of a standard input field. By default, the textarea has 3 rows, but you can customize it using the rows attribute.

```html
<Input ... type="textarea">Your message</Input>
```

## Default Value

The `value` prop allows you to set a default value for the input field or textarea. This is useful when you want the input to start with a predefined value, such as prefilled user data, placeholders for editing forms, or default selections.

The `value` prop work for all the input types including **textarea**. It is bindable, so use `bind:value` to read what the user types.

```html
<Input ... type="text" value="john_doe">Username</Input>
<Input ... type="textarea" value="A passionate developer who loves coding.">About you</Input>

<!-- Two-way binding -->
<script>
  let username = $state("john_doe");
</script>
<Input ... bind:value={username}>Username</Input>
```

## Input Variant

The `variant` prop allows you to control the visual style of the input field. There are two available variants:

- `bordered`(default): Displays the input with a visible border, making it distinct and clearly separated from the background.

- `flat`: drops the border and keeps only the bottom rule.

This prop helps you match the input style with your overall UI theme.

```html
<Input ... variant="bordered">Username</Input>
<Input ... variant="flat">Email</Input>
```

Using `flat` is great for modern, clean designs, while `bordered` ensures clear separation and visibility.

## Label

Labels help users understand the purpose of an input field. The Input component allows you to define labels in two ways: by passing plain text or using a mix of elements inside the component.

### Adding a Label

To add a label, simply place text or elements inside the Input component. This can be a simple text label or a combination of icons, tooltips, or other elements. By default, the label appears above the input field.

```html
<!-- Simple text label -->
<Input name="username">Username</Input>

<!-- Label with multiple items -->
<Input name="password" type="password">
  🔒 Password
  <HelperText>Password must be 10 characters long</HelperText>
</Input>
```

### Helper Text

Use the `helperText` prop to show extra information below the input, like a hint or a format requirement. It accepts a string or a snippet. The helper text is linked to the input with `aria-describedby`, so screen readers read it along with the label. A string renders as plain text, so use the snippet for markup.

```html
<!-- String -->
<Input name="password" type="password" helperText="Password must be 10 characters long">Password</Input>

<!-- Snippet -->
<Input name="password" type="password">
  Password
  {#snippet helperText()}
    Must be <b>10 characters</b> long
  {/snippet}
</Input>
```

### Floating Labels

With `floatingLabel` the label starts inside the field and moves up to the top edge once the field has focus or content.

The floating label works with both the `"bordered"` and `"flat"` input variants. However, it is enabled by default when the variant is set to "flat", unless explicitly disabled (this also applies to a flat Input inside a bordered Form or Fieldset). For the "bordered" variant, you must enable it manually by adding the `floatingLabel` prop.

```html
<Input ... variant="bordered" floatingLabel>Name</Input>
<Input ... variant="flat" floatingLabel>Name</Input>
```

## Sizing

The `size` prop controls the input field's size and supports `"sm"`, `"md"`, `"lg"`, and `"xl"`. The default is `"md"`. Adjusting this prop allows you to customize the input's appearance to fit different design needs.

```html
<Input ... size="sm">Small</Input>
<Input ... size="md">Medium (Default)</Input>
<Input ... size="lg">Large</Input>
<Input ... size="xl">Extra Large</Input>
```

## Rounded Input

The `rounded` prop controls the roundness of the input's corners, allowing for different visual styles. Available values are `"none"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"`, and `"full"`, with `"md"` as the default. The `"flat"` variant has no rounded corners. Use this prop to adjust the input's appearance, from sharp edges to fully rounded corners, depending on your design needs.

```html
<Input ... rounded="none">Rounded none</Input>
<Input ... rounded="sm">Rounded small</Input>
<Input ... rounded="md">Rounded medium</Input>
<Input ... rounded="lg">Rounded large</Input>
<Input ... rounded="xl">Rounded extra large</Input>
<Input ... rounded="full">Rounded full</Input>
```

## Animation Speed

The `animationSpeed` prop controls the speed of input animations, allowing for smooth transitions and interactions. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"`, and `"faster"`, with `"normal"` as the default.

```html
<Input ... animationSpeed="slower">Animation slower</Input>
<Input ... animationSpeed="slow">Animation slow</Input>
<Input ... animationSpeed="normal">Animation normal</Input>
<Input ... animationSpeed="fast">Animation fast</Input>
<Input ... animationSpeed="faster">Animation faster</Input>
<Input ... animationSpeed="none">Animation none</Input>
```

## Customization

These props cover the different parts of the field:

- `wrapperClasses`: Applied to the outermost wrapper ****, allowing full control over the container's styling.

- `labelClasses`: Applied directly to the `label`, making it easy to adjust typography, spacing, or colors.

- `class` attribute: This is the standard HTML class attribute applied to the input element itself, giving you direct control over its styling.

By combining these options, you can fully customize the input's layout and appearance while keeping its functionality intact.

```html
<Input
  name="myInput"
  placeholder="Enter username"
  wrapperClasses="flex-row items-center gap-16"
  labelClasses="text-xl text-blue-500"
  class="text-blue-500 focus:ring-blue-500 focus:border-blue-500"
>USERNAME</Input>
```

## Reset Styles

Set the `reset` prop to `true` to remove the default styles of the input and its label, so only your own classes apply. This is useful when the input must follow a completely different design. The default is `false`.

```html
<Input name="myInput" reset={true} class="w-full border-2 border-dashed border-gray-400 p-2" wrapperClasses="flex flex-col gap-1">
  Custom input
</Input>
```

## Inherited Settings

When an `Input` is placed inside a `Form` or `Fieldset`, it takes `variant`, `floatingLabel`, `size`, `rounded`, `animationSpeed`, `labelClasses` and `reset` from the closest one (the Fieldset first, then the Form). Any of these props set on the Input itself override the inherited value.

## Accessibility

The `<label>` is tied to the field with `for` and `id`, so a screen reader reads the label together with the field. When there is helper text, `aria-describedby` links it as well, so it is read out too. The same wiring applies whether the field is a text input or a textarea.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | [INPUT_TYPE](https://www.theui.dev/docs/types#input-type-type) | `text` | Defines the input type. |
| `value` | string | `undefined` | Sets the value of the input. Bindable: use `bind:value` to read or update it. |
| `helperText` | Snippet \| string | `undefined` | Displays additional information below the input, linked with `aria-describedby`. A string renders as plain text; use the snippet for markup. |
| `variant` | "bordered" \| "flat" | `Inherited from Fieldset or Form, or "bordered` | Controls the input's visual style. Available options: "bordered", "flat". |
| `floatingLabel` | boolean | `true if the Input sets its own "flat" variant; otherwise inherited from Fieldset or Form, or true if variant is "flat` | Enables a floating label effect. Automatically enabled for the "flat" variant unless explicitly disabled. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Defines the input size. Available options: "sm", "md", "lg", "xl". |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `Inherited from Fieldset or Form, or "md` | Controls the border-radius of the input. Available options: "sm", "md", "lg", "xl", "2xl", "full", "none". Not applied to the "flat" variant. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `labelClasses` | string | `Inherited from Fieldset or Form, or "` | Applies custom styles to the label. |
| `wrapperClasses` | string | `` | Applies custom styles to the input wrapper. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |

---

Source: https://www.theui.dev/docs/label

# Label

A form label that matches the other form components and takes its classes from the Form or Fieldset around it. It accepts any content.

## About

The `Label` component is designed to simplify the creation of form labels while maintaining consistency in styling and functionality. It renders a native `<label>` element with the library's label styles. The form inputs, like `Input`, `Checkbox` and `Toggle`, use it internally, and you can use it directly when you build a custom field.

## Example

To use the **Label** component, import it, place the label text inside it, and set the `for` attribute to the `id` of the input it describes. Here's a basic example:

```html
<script>
  import { Label } from "theui-svelte";
</script>

<Label for="username">Username</Label>
<input id="username" />
```

In this example, a label with the text "Username" is rendered and associated with the input through the `for` attribute. Inside a `Fieldset` or `Form`, the label uses their shared settings, like `size` and `reset`. Floating labels are only used by the `Input` and `Select` components, so a standalone `Label` never floats, even in a form with floating labels.

## Label Content

Everything placed inside the `Label` component becomes its content. It can be plain text or any mix of elements and components, like icons or badges. A `Label` without content renders nothing.

```html
<!-- Text label -->
<Label for="username">Username</Label>

<!-- Label with elements -->
<Label for="email"><strong>Email</strong> Address</Label>
```

## Customization

The `Label` component can be easily customized using the native `class` attribute. By adding your own CSS classes or the **TailwindCSS**, you can override or extend the default styles of the label to match your design requirements. Any other attributes you add are passed to the `<label>` element.

```html
<Label for="username" class="text-brand-500 font-bold text-lg">Username</Label>
```

## Accessibility

The `Label` component is based on the native `<label>` element, which improves accessibility by providing an associated label for form elements. Connect it to the input by setting its `for` attribute to the input's `id` (the form inputs of this library do this for you). This makes it easier for users, especially those using screen readers, to understand what each input is for. The label also increases the clickable area, improving the user experience.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `for` | string | `undefined` | The `id` of the input the label belongs to. It is a native attribute passed to the <label> element. |
| `class` | string | `undefined` | Custom classes merged with the default label styles. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The content of the label. It is required; a Label without content renders nothing. |

---

Source: https://www.theui.dev/docs/list-group

# List Group

A `&lt;ul&gt;` of rows, where each row is either a link or plain content. Bordered and flat variants are available.

## Example

To use the List Group component, import it from the `theui-svelte` library. Below is a simple example demonstrating how to use the List Group:

```html
<script>
  import { ListGroup, ListItem } from "theui-svelte";
</script>

<ListGroup>
  <ListItem>First Item</ListItem>
  <ListItem>Second Item</ListItem>
  <ListItem>Third Item</ListItem>
</ListGroup>
```

## List Style Variant

The `variant` prop in the List Group component allows you to control the overall style of the list. It provides two options:

- **bordered**: This style adds borders around each list item, giving a defined and structured look to the list. It is useful when you want to visually separate items clearly.

- **flat**: This style removes borders, resulting in a clean, minimalist design. It's ideal for cases where a simple and unobtrusive list presentation is preferred.

By default, the `variant` is set to `"bordered"`. You can easily switch between these styles to match the design needs of your application.

```html
<ListGroup variant="flat">
  <ListItem>First Item</ListItem>
  <ListItem>Second Item</ListItem>
  <ListItem>Third Item</ListItem>
</ListGroup>
```

## List Item Link

The List Group always renders as an unordered list `<ul>`, and each `ListItem` is a `<li>`. Add the `href` prop to a `ListItem` to render its content as a link `<a>` inside the `<li>`. Any other attributes you add to a link item, like `target`, are passed to the link. Items without `href` stay as plain list items, so you can mix static and clickable content.

```html
<ListGroup>
  <ListItem>Non-clickable item</ListItem>
  <ListItem href="/link">Clickable link item</ListItem>
</ListGroup>
```

## Sizes

The `size` prop controls the padding of the list items. Available values are `"sm"`, `"md"` (default), `"lg"` and `"xl"`. When set on the `ListGroup`, all the items inherit it. You can also set `size` on an individual `ListItem` to override the group's size.

```html
<ListGroup size="sm">
  <ListItem>Small item</ListItem>
  <ListItem>Small item</ListItem>
  <ListItem size="xl">Extra large item</ListItem>
</ListGroup>
```

## Rounded Corner

The `rounded` prop sets the border radius of the List Group. Available values are `"none"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"full"`. It applies to the `bordered` variant only; a `flat` List Group has no rounded corners.

```html
<ListGroup rounded="xl"> ... </ListGroup>
```

## Animation Speed

The `animationSpeed` prop controls the transition speed of the item hover effect. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"` (default), `"fast"` and `"faster"`. Set it on the `ListGroup` to apply it to all items, or on a `ListItem` to override it for that item.

```html
<ListGroup animationSpeed="slower">
  <ListItem>Slower hover transition</ListItem>
  <ListItem>Slower hover transition</ListItem>
  <ListItem animationSpeed="none">No transition</ListItem>
</ListGroup>
```

## Customization

Use the `class` attribute on the `ListGroup` to style the list container. To style every item at once, use the `itemClasses` prop on the `ListGroup`. To style a single item, add the `class` attribute to that `ListItem`; it overrides `itemClasses`.

```html
<ListGroup class="border-brand-300" itemClasses="text-brand-600 hover:bg-brand-50">
  <ListItem>First Item</ListItem>
  <ListItem class="font-bold">Second Item</ListItem>
  <ListItem>Third Item</ListItem>
</ListGroup>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<ul>`.

## Accessibility

The List Group component uses semantic HTML and ARIA roles:

- The parent container `<ul>` includes `role="list"`

- Each `<li>` element has `role="listitem"` to provide proper structure for assistive technologies.

## Configuration

---

Source: https://www.theui.dev/docs/modal

# Modal

The Modal component shows content in an overlay above the page, with focus trapped inside it and the page behind it locked from scrolling.

## About

Escape closes the topmost modal only, so stacked modals close one at a time. The size, the animation and the backdrop are props, and you can drive the whole thing from your own state with `bind:open` instead of passing a trigger.

## Example

To use the Modal component, you need to import it into your Svelte file. This setup allows you to easily integrate the Modal component into your project.

```html
<script>
  import { Modal } from "theui-svelte";
</script>

<Modal label="Modal Button">
  Hello Modal!
</Modal>
```

## Modal Trigger

The Modal trigger is the element that opens the Modal when clicked. You can create this trigger using either the `label` prop or the `label` snippet. The label prop generates a default button with the provided text, making it simple to open the Modal. Alternatively, the label snippet lets you customize the trigger with any element or component, giving you more flexibility.

### Trigger with the label prop

```html
<Modal label="Modal Trigger"> ... </Modal>
```

### Trigger with the label snippet

```html
<Modal>
  {#snippet label()}
    <Button>Modal Trigger</Button>
  {/snippet}
  ...
</Modal>
```

### Trigger From Outside

To control the `Modal` from outside, bind a reactive variable to its `open` prop. This is helpful when the open button is not placed inside the Modal.

```html
<script>
    let openModal: boolean = $state(false)
</script>

<Button onclick={() => openModal = true}>Open Modal</Button>

<Modal bind:open={openModal}>
    <!-- Modal content -->
</Modal>
```

## Modal Content

The content placed directly inside the `<Modal>` tag will be displayed as the main body of the Modal. The Modal also takes two snippets, for the header and the footer: `header` and `footer`.

- The `header` snippet is used to define the header section of the Modal.

- The `footer` snippet is used to define the footer section of the Modal.

```html
<Modal label="Modal Content">
  {#snippet header()}
    <h4 class="font-bold text-lg">THIS IS HEADER!</h4>
  {/snippet}

  Modal content!

  {#snippet footer()}
    <p class="text-muted">This is footer</p>
  {/snippet}
</Modal>
```

## Positioning

The `position` prop in the Modal component determines where the modal is displayed vertically on the screen. It can be set to `'top'`, `'center'`, or `'bottom'`, with the default being `'center'`. This allows you to align the modal according to your design needs, whether you want it at the top for quick alerts, in the center for standard dialogs, or at the bottom for additional content.

```html
<!-- Top-aligned Modal -->
<Modal position="top"> ... </Modal>

<!-- Centered Modal (Default) -->
<Modal position="center"> ... </Modal>

<!-- Bottom-aligned Modal -->
<Modal position="bottom"> ... </Modal>
```

## Sizing

The `size` prop controls the width of the Modal. Options include `'sm'` for small, `'md'` for medium (default), `'lg'` for large, and `'full'` for full-screen. This allows you to adjust the modal size based on your content needs.

```html
<!-- Small Modal -->
<Modal size="sm"> ... </Modal>

<!-- Medium-sized Modal (default) -->
<Modal size="md"> ... </Modal>

<!-- Large Modal -->
<Modal size="lg"> ... </Modal>

<!-- Full-width Modal -->
<Modal size="full"> ... </Modal>
```

## Animation

### Animation Type

The `animation` prop defines the type of animation used when the Modal opens or closes. Available options include `'slide-down'`, `'slide-up'`, `'fade'`, `'zoom-in'`, and `'zoom-out'`. Each option provides a different visual effect for how the Modal appears or disappears.

```html
<!-- Modal with slide-down animation -->
<Modal animation="slide-down"> ... </Modal>

<!-- Modal with slide-up animation -->
<Modal animation="slide-up"> ... </Modal>

<!-- Modal with fade (default) animation -->
<Modal animation="fade"> ... </Modal>

<!-- Modal with zoom-in animation -->
<Modal animation="zoom-in"> ... </Modal>

<!-- Modal with zoom-out animation -->
<Modal animation="zoom-out"> ... </Modal>
```

### Animation Speed

The `animationSpeed` prop controls the speed of the Modal's animation. It accepts the following values: `'none'`, `'slower'`, `'slow'`, `'normal'`, `'fast'`, and `'faster'`. The default is `'fast'`. Setting this prop to `'none'` will disable the animation, while the other values adjust the animation speed accordingly.

```html
<Modal animationSpeed="slower"> ... </Modal>
<Modal animationSpeed="slow"> ... </Modal>
<Modal animationSpeed="normal"> ... </Modal>
<Modal animationSpeed="fast"> ... </Modal>
<Modal animationSpeed="faster"> ... </Modal>
<Modal animationSpeed="none"> ... </Modal>
```

## Modal Backdrop

### Static Backdrop

The `staticBackdrop` prop controls whether the Modal closes when clicking on the backdrop. By default, the backdrop is clickable, and clicking it will close the Modal. Setting `staticBackdrop` to `true` makes the backdrop static, meaning the Modal will remain open even when the backdrop is clicked.

```html
<Modal staticBackdrop={true}> ... </Modal>
```

### Backdrop Customization

The `backdrop` prop manages the visibility and style of the Modal's backdrop. When set to `true` (default), the backdrop is visible. If set to `false`, the backdrop will be hidden. You can also customize the backdrop by passing custom CSS classes, which will apply directly to the backdrop.

```html
<!-- Modal with no backdrop -->
<Modal  backdrop={false}> ... </Modal>

<!-- Modal with custom styled backdrop -->
<Modal backdrop="bg-brand-500/30"> ... </Modal>
```

## Disable Close Button

The `closeButton` prop allows you to control the visibility of the close button in the Modal. By default, the close button is visible (`true`). Set this prop to `false` to hide the close button. You can also pass a string of custom classes to style the close button.

```html
<Modal closeButton={false}> ... </Modal>
```

## Modal Open State

The `open` prop controls whether the Modal is visible when the page loads. By default, `open` is set to `false`, meaning the Modal is hidden initially. If you set `open` to `true`, the Modal will be open and visible as soon as the page loads.

```html
<Modal open={true}> ... </Modal>
```

## Customization

To create a custom-styled modal, you can use the following props to apply custom classes to the modal's header, body, footer, and outer container:

- `headerClasses`: Customize the header section of the modal.

- `bodyClasses`: Customize the body section of the modal.

- `footerClasses`: Customize the footer section of the modal.

- `containerClasses`: Customize the outer container of the modal.

- `buttonClasses`: Customize the modal trigger created by the `label` prop.

These props allow you to apply your own styles or use TailwindCSS classes to control the layout and appearance of different parts of the modal.

```html
<Modal
  bodyClasses="bg-blue-100 dark:bg-blue-950 text-blue-800 dark:text-blue-300 border-blue-500/50 border-4 py-8"
  headerClasses="bg-blue-400/50 text-blue-600 dark:text-blue-100 shadow-blue-500/50 rounded-md p-4 border-0 shadow-md text-lg font-bold"
  footerClasses="border-blue-300/50 border rounded-xl p-2"
>
  {#snippet label()}
    <Button>Modal Button</Button>
  {/snippet}

  {#snippet header()}
    <h4>Custom Modal Header</h4>
  {/snippet}

  .....

  {#snippet footer()}
    <Button class="bg-warning-500 hover:bg-warning-600 text-warning-900" size="sm">Close</Button>
  {/snippet}
</Modal>
```

## Accessibility

The Modal carries the ARIA attributes it needs and answers to the keyboard out of the box.

- **ARIA Attributes**: The Modal uses `role="dialog"` and `aria-modal="true"` to indicate its purpose to assistive technologies. `aria-labelledby` and `aria-describedby` are added automatically to associate the header and content with the Modal. If the Modal has no header, it is labelled by the `ariaLabel` prop instead, which also labels a custom `label` snippet trigger.

- **Keyboard Navigation** Focus is automatically moved to the Modal when it opens.

- Users can navigate through focusable elements using the tab key.

- Pressing the Esc key closes the Modal. When modals are stacked, only the topmost one closes.

- A custom `label` snippet trigger can be activated with the Enter or Space key.

- **Focus Management**: focus is trapped inside the Modal while it is open, so nothing behind it can be reached. On close, focus returns to the element that opened it. Page scrolling is locked while the Modal is open, and the closed Modal is marked `inert`.

- **Screen Reader Announcements**: The Modal is announced as a dialog to screen readers, helping users understand its purpose.

- **Color Contrast**: Ensure that text and background colors inside the Modal meet WCAG contrast ratio standards.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string \| Snippet | `undefined` | Content or element that triggers the modal. |
| `header` | string \| Snippet | `undefined` | Content for the modal header. A string renders as plain text; use a snippet for markup. |
| `footer` | Snippet | `undefined` | Content for the modal footer. |
| `position` | 'top' \| 'center' \| 'bottom' | `center` | Position of the modal on the screen. |
| `size` | 'sm' \| 'md' \| 'lg' \| 'full' | `md` | Size of the modal. |
| `animation` | 'slide-down' \| 'slide-up' \| 'fade' \| 'zoom-in' \| 'zoom-out' | `fade` | Type of animation for the modal. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `fast` | Speed of the animation. |
| `backdrop` | boolean\|string | `true` | Controls the modal backdrop. Can be boolean or a string for custom backdrop. |
| `staticBackdrop` | boolean | `false` | Disables closing the modal by clicking on the backdrop. |
| `closeButton` | boolean \| string | `true` | Shows or hides the close button. Pass a string to add custom classes to the close button. |
| `ariaLabel` | string | `Modal` | Accessible label for the modal dialog when no header is set, and for a custom label snippet trigger. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Border-radius of the modal. |
| `open` | boolean | `false` | Tracks the visibility status of the modal. Bindable: use bind:open to open or close the modal from outside. |
| `buttonClasses` | string | `undefined` | Classes for the modal trigger button. |
| `containerClasses` | string | `undefined` | Classes for the modal container. |
| `bodyClasses` | string | `undefined` | CSS classes for the modal body. |
| `headerClasses` | string | `undefined` | CSS classes for the modal header. |
| `footerClasses` | string | `undefined` | CSS classes for the modal footer. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Main content of the component. |
| `label` | Content or element that triggers the modal. |
| `header` | Content for the modal header. |
| `footer` | Content for the modal footer. |

---

Source: https://www.theui.dev/docs/navbar

# Navbar

A responsive navigation bar with support for dropdown menus, keyboard navigation, and customizable styling. It's ideal for building primary site navigation or complex menu systems.

## About

The `Navbar` component is the navigation bar: a brand, one or more link groups, and dropdown menus. It collapses into a toggle menu below the breakpoint you set, and every link answers to the keyboard.

## Example

The `Navbar` component is built using multiple elements, each serving a specific role:

- `NavBrand`Displays the brand name or logo and links to the homepage or any specified URL.

- `NavCollapse`Wraps the links that should fold into a toggle menu on small screens.

- `NavLinkGroup`A wrapper for organizing multiple navigation links in a structured manner.

- `NavLink`Represents an individual navigation link with customizable text and URL.

- `NavDropdown`A dropdown menu inside the Navbar that contains additional navigation links.

```html
<script>
  import {Navbar, NavBrand, NavLinkGroup, NavDropdown, NavLink} from "theui-svelte";
</script>

<Navbar>
  <NavBrand href="#">BRAND</NavBrand>
  <NavLinkGroup>
    <NavLink href="#" text="Link 1" />
    <NavLink href="#" text="Link 2" />
    <NavLink href="#" text="Link 3" />
    <NavDropdown label="Dropdown">
      <NavLink href="#" text="Dropdown Link 1" />
      <NavLink href="#" text="Dropdown Link 2" />
      <NavLink href="#" text="Dropdown Link 3" />
    </NavDropdown>
  </NavLinkGroup>
</Navbar>
```

## Scroll Behavior

The `scrollBehavior` prop controls how the Navbar behaves when the user scrolls. It provides flexibility in handling visibility and size adjustments based on scrolling direction.

### Navbar Scrolling Effects

- `default` - The Navbar remains static and does not react to scrolling.

- `fixed` - The Navbar stays fixed at the top of the page, even when scrolling.

- `shrinkOnScrollDown` - The Navbar reduces in height when scrolling down and restores its size when scrolling up. You can control the scroll amount with the `scrollAmountToShrink` prop to shrink the **Navbar**. Follow [this for more](#hide/shrink-scroll-amount).

- `hideOnScrollDown` - The Navbar disappears when scrolling down and reappears when scrolling up. Use the `scrollAmountToHide` prop to change the scroll amount to hide the **Navbar**. Follow [this for more](#hide/shrink-scroll-amount).

- `shrinkAndHide` - The Navbar first shrinks on scroll down and then hides completely, reappearing at full size when scrolling up.

```html
<Navbar scrollBehavior="default"> ... </Navbar>
<Navbar scrollBehavior="fixed"> ... </Navbar>
<Navbar scrollBehavior="shrinkOnScrollDown"> ... </Navbar>
<Navbar scrollBehavior="hideOnScrollDown"> ... </Navbar>
<Navbar scrollBehavior="shrinkAndHide"> ... </Navbar>
```

The Navbar also checks the scroll position when the page loads, so a page reloaded halfway down starts shrunk or hidden as it should.

Every behavior except `default` makes the Navbar `fixed`, so it no longer takes up space in the page. Add top padding to your page content, about the height of the Navbar, so nothing is hidden behind it.

### Hide/Shrink Scroll Amount

The `scrollAmountToShrink` and `scrollAmountToHide` props allow fine-tuned control over how the Navbar reacts to scrolling. These values determine the scroll distance (in pixels) required to trigger shrinking or hiding effects, making the Navbar more adaptive to different layouts.

By default, `scrollAmountToShrink` is set to **32px**, meaning the Navbar will shrink after scrolling this distance when `shrinkOnScrollDown` or `shrinkAndHide` is enabled. Similarly, `scrollAmountToHide` is **128px**, which controls when the Navbar fully disappears when `hideOnScrollDown` or `shrinkAndHide` is used. Change them to suit how tall your navbar is.

## Navbar Height

The `height` prop allows you to control the height of the Navbar. It helps in maintaining a consistent design while adjusting for different UI requirements. Available heights are: `sm`, `md`, `lg` and `xl`. Default is `md`. The presets set the vertical padding of the Navbar; any other value is used as classes, for example `height="py-5"`. Dropdown menus open right below the Navbar in both cases.

```html
<Navbar height="sm"> ... </Navbar>
<Navbar height="md"> ... </Navbar> <!-- Default -->
<Navbar height="lg"> ... </Navbar>
<Navbar height="xl"> ... </Navbar>
```

## Brand and Links

### NavBrand

The `NavBrand` component shows your logo or site name as a link. Its `href` prop defaults to `"/"`. Put text or an image inside it. Screen readers read its content, so give a logo image an `alt` text. If the brand has no readable content, such as an SVG logo, set the `ariaLabel` prop.

```html
<Navbar>
  <NavBrand href="/">BRAND</NavBrand>
</Navbar>
```

### NavLink

A `NavLink` renders a link when it has an `href`, a button when it has an `onclick` instead, and a plain text element otherwise. Write the content inside the component, or pass it as the `text` prop, which renders as plain text. Set `active` on the link of the current page: it gets the active styles and `aria-current="page"`. Clicking a link also closes the mobile menu.

```html
<NavLinkGroup>
  <NavLink href="/" active>Home</NavLink>
  <NavLink href="/about" text="About" />
  <NavLink href="/contact" text="Contact" />
</NavLinkGroup>
```

## Responsive Navbar

Anything you put inside `NavCollapse` moves into a toggle menu below the navbar's breakpoint. `NavCollapse` owns the hamburger button and the open and close behavior, so a link group placed outside it stays visible at every width.

### NavCollapse

The `NavCollapse` component acts as a wrapper for collapsible navigation items. When used inside the **Navbar**, it ensures that the contained elements are hidden on smaller screens and can be revealed through a toggle button. Without `NavCollapse`, all navigation items will remain visible, even on small screens, potentially affecting layout and usability.

### navBreakpoint

The `navBreakpoint` prop in the **Navbar** component determines at which screen size the navigation should collapse. Available values are `'sm'`, `'md'`, `'lg'` (default), and `'xl'`. When the screen width is smaller than the defined breakpoint, `NavCollapse` will activate, hiding its content until toggled. Adjusting this value allows you to fine-tune when the menu should collapse based on your design needs. Set it to `false` to keep the links expanded at every screen size.

```html
<Navbar navBreakpoint="md">
  <NavBrand href="#">BRAND</NavBrand>
  <NavCollapse>
    <NavLinkGroup>
      ...
    </NavLinkGroup>
  </NavCollapse>
</Navbar>
```

In this example, the navigation items inside `NavCollapse` will collapse into a toggleable menu when the screen width is smaller than the `md` breakpoint.

## Link Alignment

The `align` prop in the `NavLinkGroup` component controls how navigation links are positioned within the group. By default, links are aligned to the `"start"`, keeping them on the left. If you want the links to be centered, set align to `"center"`. To push the links to the right, use `"end"`. In the example below, different `NavLinkGroup` elements demonstrate these alignments inside `NavCollapse`.

```html
<Navbar>
  <NavBrand href="#">BRAND</NavBrand>
  <NavCollapse>
    <NavLinkGroup align="start"> ... </NavLinkGroup> <!-- Default -->
    <NavLinkGroup align="center"> ... </NavLinkGroup>
    <NavLinkGroup align="end"> ... </NavLinkGroup>
  </NavCollapse>
</Navbar>
```

## Navbar Dropdown

The `NavDropdown` component allows you to create dropdown menus within the `Navbar`, making it easy to organize navigation links under expandable sections. It supports various customizations, including event triggers, alignment, width, animations, and arrow icon control.

```html
<Navbar>
  <NavBrand href="#">BRAND</NavBrand>
  <NavCollapse>
    <NavLinkGroup>
      ...
      <NavDropdown label="Dropdown">
        <NavLink href="#" text="Dropdown Link 1" />
        <NavLink href="#" text="Dropdown Link 2" />
        <NavLink href="#" text="Dropdown Link 3" />
      </NavDropdown>
    </NavLinkGroup>
  </NavCollapse>
</Navbar>
```

### Dropdown Label

The `label` prop/snippet in the `NavDropdown` defines the dropdown's visible label. You can pass it as a simple string or use a Snippet for more complex elements. For simple text or other simple content use it as a prop. For complex element, use `label` as a snippet.

```html
<NavDropdown label="Simple text label"> ... </NavDropdown>
```

### Dropdown Width

The width of the dropdown menu can be controlled using the `width` prop. Available values are `"sm"`, `"md"`, `"lg"`, `"xl"`, and `"full"`. The `"full"` width setting is particularly useful for creating a mega menu.

```html
<NavDropdown ... width="sm"> ... </NavDropdown>
<NavDropdown ... width="md"> ... </NavDropdown> <!-- Default -->
<NavDropdown ... width="lg"> ... </NavDropdown>
<NavDropdown ... width="xl"> ... </NavDropdown>
```

### Dropdown Alignment

The dropdown menu can be aligned to either `"start"` (default) or `"end"`. Setting `align="end"` pushes the dropdown content to the right.

```html
<NavDropdown ... align="start"> ... </NavDropdown> <!-- Default -->
<NavDropdown ... align="end"> ... </NavDropdown>
```

### Dropdown Event

By default, the dropdown opens when clicked. To open it on hover, set `dropdownTriggerEvent="hover"` on the **Navbar**, which applies to all its dropdowns, or `triggerEvent="hover"` on a single **NavDropdown**, which overrides the Navbar value for that dropdown. Both accept `"click"` and `"hover"`.

```html
<!-- All dropdowns of this navbar open on hover -->
<Navbar dropdownTriggerEvent="hover"> ... </Navbar>

<!-- Only this dropdown -->
<NavDropdown ... triggerEvent="click"> ... </NavDropdown> <!-- Default -->
<NavDropdown ... triggerEvent="hover"> ... </NavDropdown>
```

### Dropdown Animation

The dropdown takes one of three animation styles: `"fade"`, `"slide"` and `"zoom"`. The default is `"fade"`. To control the speed, [follow this](#animation-speed).

```html
<NavDropdown ... animation="fade"> ... </NavDropdown> <!-- Default -->
<NavDropdown ... animation="slide"> ... </NavDropdown>
<NavDropdown ... animation="zoom"> ... </NavDropdown>
```

### Dropdown Arrow

The dropdown includes an arrow icon by default. You can hide it by setting the `arrowIcon` prop to false. If you wish to add your custom icon, use the `arrowIcon` as a snippet and place your icon inside it.

```html
<!-- No arrow icon -->
<NavDropdown label="No arrow" arrowIcon={false}> ... </NavDropdown>

<!-- Custom arrow icon -->
<NavDropdown label="Custom arrow">
  {#snippet arrowIcon()}
    <Svg> <path d="...."/> </Svg>
  {/snippet}
  ...
</NavDropdown>
```

## Mega Menu

For more advanced layouts, the Navbar includes a Mega Menu option. When the `width` prop of a `NavDropdown` is set to `"full"`, the dropdown expands to take the full width of the Navbar, creating a spacious layout for organizing multiple links, sections, or even embedded content. This makes the Mega Menu ideal for websites that require a detailed navigation structure, such as e-commerce platforms, dashboards, and content-heavy websites.

```html
<NavDropdown label="Mega menu" width="full">
  <div class="...">
    ...
  </div>
</NavDropdown>
```

## Animation Speed

The `animationSpeed` prop of the **Navbar** sets the transition speed of the Navbar and everything inside it: the shrink and hide effects, the links and the dropdowns. Available values are `"slower"`, `"slow"`, `"normal"`, `"fast"` (default), `"faster"` and `"none"`.

```html
<Navbar animationSpeed="slower"> ... </Navbar>
```

## Rounded

The `rounded` prop of the **Navbar** sets the corner radius of its links, its dropdown menus and the bottom corners of the mobile menu. Available values are `"none"`, `"sm"`, `"md"` (default), `"lg"`, `"xl"`, `"2xl"` and `"full"`.

```html
<Navbar rounded="none"> ... </Navbar>
```

## Customization

The Navbar is styled from the **Navbar** component, so one set of props styles every part of it:

- `class` - classes for the `<nav>` element, merged with the defaults.

- `navInnerClasses` - classes for the inner container that holds the brand and the links.

- `navCollapseClasses` - classes for the mobile menu created by `NavCollapse`.

- `scrollShrinkClasses` - classes added while the Navbar is shrunk by the `shrinkOnScrollDown` or `shrinkAndHide` behavior.

- `linkClasses` - classes for every `NavLink` and dropdown trigger.

- `activeLinkClasses` - classes added to an `active` NavLink.

- `dropdownLinkClasses` - classes for the NavLinks inside a `NavDropdown`.

Each part also takes a `class` of its own. On a `NavDropdown`, `class` styles the menu panel, and `linkClasses` styles its trigger.

The inner row stops at the same width as a [`Container`](https://www.theui.dev/docs/container), so the brand and the links line up with the content below them. Both read the [`--max-width`](https://www.theui.dev/docs/container#page-width) variable, and changing it moves them together.

```html
<Navbar
  class="bg-blue-50 dark:bg-blue-950"
  linkClasses="text-blue-700 dark:text-blue-300"
  activeLinkClasses="font-bold"
  dropdownLinkClasses="text-sm"
>
  ...
</Navbar>
```

## Accessibility

The Navbar ships with the roles and the keyboard behavior a navigation region needs.

Use the `ariaLabel` prop on the `Navbar` to set an `aria-label`. It tells a screen reader which navigation region this is, which matters as soon as a page has more than one.

All interactive elements, including links and dropdowns, are fully keyboard-accessible. Users can open dropdowns with `Enter` or `Space`, navigate through links and move between dropdown items using the `Tab` key. The `Escape` key closes open dropdowns and moves focus back to the dropdown button. The mobile toggle button and each dropdown button point to the content they open with `aria-controls`.

For better accessibility, ensure that all links have clear, descriptive text. If using a `NavDropdown`, the `aria-expanded` attribute updates dynamically to reflect its open or closed state, improving the experience for screen reader users.

## Configuration

### Navbar

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollBehavior` | [NAV_SCROLL_BEHAVIOR](https://www.theui.dev/docs/types#navbar-scroll-behavior-type) | `default` | Behavior when scrolling: "default", "fixed", "shrinkOnScrollDown", "hideOnScrollDown" or "shrinkAndHide". Every value except "default" makes the navbar fixed. |
| `scrollAmountToShrink` | number | `32` | Scroll distance (px) before the navbar shrinks. |
| `scrollAmountToHide` | number | `128` | Scroll distance (px) before the navbar hides. |
| `height` | 'sm' \| 'md' \| 'lg' \| 'xl' \| string | `md` | Height of the navbar. The presets set its vertical padding; any other value is used as classes. |
| `navBreakpoint` | 'sm' \| 'md' \| 'lg' \| 'xl' \| false | `lg` | Screen size below which the content of `NavCollapse` folds into the toggle menu. Set it to false to never fold. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `fast` | Transition speed of the navbar and all the components inside it. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Corner radius of the links, the dropdown menus and the mobile menu. |
| `ariaLabel` | string | `Navigation bar` | Accessible name of the `<nav>` element. |
| `dropdownTriggerEvent` | 'hover' \| 'click' | `click` | How every `NavDropdown` of this navbar opens. A dropdown can override it with its own `triggerEvent`. |
| `navInnerClasses` | string | `undefined` | Custom classes for the inner container that holds the brand and the links. |
| `navCollapseClasses` | string | `undefined` | Custom classes for the mobile menu created by `NavCollapse`. |
| `scrollShrinkClasses` | string | `undefined` | Custom classes added while the navbar is shrunk. |
| `linkClasses` | string | `undefined` | Custom classes for every `NavLink` and dropdown trigger. |
| `activeLinkClasses` | string | `undefined` | Custom classes added to an active `NavLink`. |
| `dropdownLinkClasses` | string | `undefined` | Custom classes for the `NavLink`s inside a `NavDropdown`. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the `<nav>` element, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The content of the navbar: NavBrand, NavCollapse, NavLinkGroup and so on. |

### Navbar Brand

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | string | `/` | URL of the brand link, usually the homepage. |
| `ariaLabel` | string | `undefined` | Accessible name of the brand link. Only needed when the brand has no readable content, such as an SVG logo. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the brand link, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The logo or site name. |

### Navbar Collapse

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The links and groups that fold into the toggle menu on small screens. |
| `toggleIcon` | Custom icon for the toggle button. If provided, the default icon is replaced. |

### Navbar Dropdown

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string \| Snippet | `undefined` | Trigger label. A string renders as plain text; a Snippet is rendered as it is. |
| `align` | 'start' \| 'end' | `start` | Aligns the menu to the start or end of its trigger. |
| `width` | 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' | `sm` | Width of the menu. "full" spans the whole navbar, for a mega menu. |
| `triggerEvent` | 'hover' \| 'click' | `Inherited from the Navbar's dropdownTriggerEvent, or "click` | How this dropdown opens. |
| `animation` | 'fade' \| 'slide' \| 'zoom' | `fade` | Open and close animation of the menu. |
| `arrowIcon` | Snippet \| boolean | `true` | Shows the arrow next to the label. Set it to false to hide it, or pass a Snippet to use your own icon. |
| `linkClasses` | string | `undefined` | Custom classes for the dropdown trigger, merged with the Navbar's `linkClasses`. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the menu panel, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The content of the menu, usually NavLinks or custom mega menu content. |
| `label` | Custom trigger content, as an alternative to the string prop. |
| `arrowIcon` | Replaces the default arrow icon. |

### Navbar Link

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | string | `undefined` | Link content as a string, instead of writing it inside the component. It renders as plain text. |
| `active` | string \| boolean | `false` | Marks the link of the current page. It adds the Navbar's `activeLinkClasses` and `aria-current="page"`. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `href` | URL of the link. Without it, the NavLink renders as a button when it has an onclick, and as plain text otherwise. |
| `class` | Classes for the link, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The link content, used when the text prop is not set. |

### Navbar Link Group

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | 'start' \| 'center' \| 'end' | `start` | Horizontal alignment of the link group. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the group container, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The NavLinks and NavDropdowns of the group. |

---

Source: https://www.theui.dev/docs/notification

# Notification

A lightweight way to display temporary messages without interrupting the user experience. It appears briefly, disappears automatically, and is fully customizable.

## About

This component is ideal for showing temporary messages such as success alerts, error messages, or status updates. It supports customization options, including different colors, positions, icons, and auto-dismiss settings. Whether you need to notify users about form submissions, system errors, or background processes, the Notification (Toast) component offers a flexible and efficient solution.

## Example

To use the `Notification` component, you need to add it once in your application. The recommended place is `+layout.svelte` to ensure it is available throughout your app, but you can place it anywhere suitable.

```html

<script>
  import { Notification } from "theui-svelte";
</script>

<!-- Add Notification component once, ideally in +layout.svelte -->
<Notification />
```

Once added, you can trigger notifications anywhere in your app using the `notify` function.

```html
<script>
  import { notify } from "theui-svelte";
</script>

<!-- Trigger the notifications -->
<Button
  onclick={
    () => notify("Hello world!")
  }
>Notify</Button>
```

This will display a simple notification with the message **"Hello world!"**.

## Notification Position

By default the notification will appears at the top-end corner of the display. But you can change it using the `position` prop in the `Notification` component. The available value of the position prop are `"top-end"`, `"top-center"`, `"top-start"`, `"bottom-end"`, `"bottom-center"`, and `"bottom-start"`. Default value is `"top-end"`.

```html
<Notification position="bottom-end" />
```

## Notification Animation

By default, notifications slide in when they appear and fade out when they are removed. Use the `animationSpeed` prop on the `Notification` component to control this. Unlike other components, it is a boolean: `true` (default) enables the animation, and `false` turns it off.

```html
<Notification animationSpeed={false} />
```

## Notification Type

The `notify` function accept some parameters along with the message. You have to pass the message as the first parameter. The second parameter defines the type of the notification. Basically it changes the color based on the type. The available types are `"error"`, `"info"`, `"success"`, and `"warning"`. The default value is `"error"`.

```js
notify("Hello world!", "success") // You can replace "success" with any message type!
```

## Notification Theme

You can control the background color of the notifications with the `theme` prop. It supports three options: `'default'`, `'soft'`, and `'gradient'`. The `'default'` theme follows the standard notification styling, the `'soft'` theme provides a softer color palette for a more subtle look, and the `'gradient'` theme uses a two color gradient.

### Soft Theme

The `'soft'` theme uses a tinted background instead of a solid one.

```js
notify( "Hello world!", "success", {theme: "soft"} )
```

### Gradient Theme

The `'gradient'` theme fills the background with a two color gradient.

```js
notify( "Hello world!", "success", {theme: "gradient"} )
```

## Notification Variant

The `'variant'` property allows you to change the visual style of the notification while keeping it minimal. There are four available variants: `'card'`, `'borderTop'`, `'borderBottom'`, and `'borderStart'`.

The default variant, `'card'`, follows a standard notification style without extra elements. The other three variants, `'borderTop'`, `'borderBottom'` and `'borderStart'`, add a thin line to that side of the notification. It is a small change, but it tells one notification from another at a glance.

For example, using `borderTop` will place a small line at the top of the notification, while `borderBottom` and `borderStart` will do the same for the bottom and start (left in LTR layouts, right in RTL layouts).

```js
notify("Hello world!", "success", {theme: "soft", variant: "borderTop"})
```

## Notification Duration

The `removeAfter` property controls how long a notification remains visible before closing automatically. It accepts an integer value in milliseconds, or `false`.

- The **default duration is 4000ms** (4 seconds), meaning notifications disappear after this time.

- Setting it to **false** keeps the notification open indefinitely until manually closed.

```js
notify("Hello world!", "error", {removeAfter: 3000})
```

## Remove On Click

By default, notifications close when clicked. You can change this behavior using the `removeOnClick` property in the options object. When set to `true` (default), clicking the notification will dismiss it. If set to `false`, the notification will remain visible even when clicked.

```js
notify("Hello world!", "error", {removeOnClick: false})
```

## notify() Function

The `notify` function displays notifications with customizable options. It accepts three parameters:

- **msg** (type string) - The message displayed in the notification. HTML in the message is sanitized before rendering.

- **type** (type [NOTIFICATION_TYPE](https://www.theui.dev/docs/types#notification-types)) - Defines the notification style. Options: `'error'`, `'info'`, `'success'`, and `'warning'`. - Default is `'error'`.

- **config** (type [NOTIFY_CONFIG](https://www.theui.dev/docs/types#notification-configuration)) - An optional object to configure the notification's behavior and appearance.

Call `notify` in the browser, such as from an event handler, `$effect` or `onMount`. A call during server rendering does nothing, so one visitor's message never reaches another.

#### Configuration Options

- **removeAfter** (type number | false) - Duration in milliseconds before the notification disappears. Set to `false` for persistent notifications. - Default is `4000`.

- **removeOnClick** (type boolean) - Determines if the notification should close when clicked. - Default is `true`.

- **rounded** (type [ROUNDED](https://www.theui.dev/docs/types#rounded-type)) - Controls the border radius. - Default is `'md'`.

- **theme** (type string) - Sets the notification theme. Options: `'default'`, `'soft'`, `'gradient'`. - Default is `'default'`.

- **variant** (type string) - Defines the notification style. Options: `'card'`, `'borderTop'`, `'borderBottom'`, `'borderStart'`. - Default is `'card'`.

## Accessibility

The Notification component is built with accessibility in mind, handling all necessary ARIA attributes, including `role="alert"`, `aria-live="assertive"` and `aria-atomic="true"`, so screen readers announce each notification as soon as it appears. These attributes are automatically applied, so you don't need to configure them manually.

The only consideration required is maintaining proper color contrast for the notification's text and background to ensure readability and compliance with accessibility standards.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | [NOTIFICATION_POSITION](https://www.theui.dev/docs/types#notification-position) | `top-end` | Position of the notifications on the screen. |
| `animationSpeed` | boolean | `true` | Enables or disables the show and hide animation of the notifications. |

### Functions

| Name | Description |
| --- | --- |
| `notify` | Triggers the notifications with customizable options. For more details, read the [notify() Function doc.](#notify-function) |

---

Source: https://www.theui.dev/docs/pagination

# Pagination

Renders the page links for a list that is split across pages, with previous and next controls.

## About

It builds the page numbers from the `data` array you pass, adds previous and next buttons, and marks the current page. The numbers come from the position in the array, not from the data itself.

## Example

The `Pagination` component accepts a `data` prop, which is an array of objects. Each object represents a page link with a `url` and an optional `active` property to indicate the current page. Each `url` must be unique.

Below is a simple example of how to use the `Pagination` component with static data:

```html
<script>
  let data = [
    { url: "?page=1" },
    { url: "?page=2", active: true },  // Current page
    { url: "?page=3" },
    { url: "?page=4" }
  ];
</script>

<Pagination {data} />
```

## Alignment

The `align` prop controls the horizontal position of the pagination. The accepted values are: `'start'`, `'center'`, and `'end'`. The default value is `center`.

```html
<Pagination {data} align="start" />
<Pagination {data} align="center" />
<Pagination {data} align="end" />
```

## Sizing

You can control the button size of the pagination with the `size` prop. Available values are: `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'auto'`. Default value `md`.

```html
<Pagination {data} size="xs" />
<Pagination {data} size="sm" />
<Pagination {data} size="md" />
<Pagination {data} size="lg" />
<Pagination {data} size="xl" />
```

## Flat Pagination

Add `flat` attribute to the `Pagination` component to make the pagination flat/border-less.

```html
<Pagination {data} flat />
```

## Prev/Next Button

You can use the `hidePrevious`, `hideNext`, and `hidePreviousNext` attributes to control the visibility of navigation buttons in the Pagination component. The `hidePrevious` hides the previous button, `hideNext` hides the next button, and `hidePreviousNext` hides both.

### Hide Prev/Next Button

The example below demonstrates how to hide the previous button, next button, or both using attributes. The first example hides the previous button, the second hides the next button, and the third hides both.

```html
<Pagination {data} hidePrevious />
<Pagination {data} hideNext />
<Pagination {data} hidePreviousNext />
```

### Custom Previous/Next Button Content

The `previousButton` and `nextButton` props allow you to customize the content of the previous and next buttons in the Pagination component. These props render as plain text, so you can use any character you like, such as an arrow or an angle quote.

By default, `previousButton` is set to `"← Prev"`, and `nextButton` is set to `"Next →"`. You can modify these values to fit your needs, such as other words, arrows or symbols.

```html
<Pagination {data} previousButton="‹" nextButton="›" />
```

### Onclick Function

In some cases, you may need custom functionality when clicking the previous or next button. You can achieve this using the `onPreviousClick` and `onNextClick` props by passing your custom functions to them. Each function receives the click `MouseEvent`.

```html
<script>
  let prevFunction = () => {
    alert("Hello from previous function!")
  }

  let nextFunction = () => {
    alert("Hello from next function!")
  }
</script>

<Pagination {data} onPreviousClick={prevFunction} onNextClick={nextFunction} />
```

## Hide Page Number Buttons

In some cases, you may only need the previous and next buttons without page numbers. The Pagination component supports this by default - simply leave the `data` prop empty, and it will display only the previous and next buttons.

```html
<Pagination />
```

## Rounded Corner

The `rounded` prop sets the corner radius of the page links. Available values are: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, and `full`. Default value `md`.

```html
<Pagination {data} rounded="none" />
<Pagination {data} rounded="sm" />
<Pagination {data} rounded="md" />
<Pagination {data} rounded="lg" />
<Pagination {data} rounded="xl" />
<Pagination {data} rounded="full" />
```

## Animation Speed

The `animationSpeed` prop controls the animation (hover animation in this case) speed of `Pagination`. Options include `'none'` for no animation, `'slower'` or `slow` for a gradual effect, `normal` (default) for standard speed, and `fast` or `faster` for quicker animations.

```html
<Pagination {data} animationSpeed="slower" />
<Pagination {data} animationSpeed="slow" />
<Pagination {data} animationSpeed="normal" />
<Pagination {data} animationSpeed="fast" />
<Pagination {data} animationSpeed="faster" />
<Pagination {data} animationSpeed="none" />
```

## Customization

Use the `class` attribute to style the pagination container. To style the buttons, use these two props:

- `buttonClasses`: Custom classes for the page number buttons that are not active, and the previous and next buttons.

- `activeButtonClasses`: Custom classes for the active page button.

```html
<Pagination
  {data}
  buttonClasses="text-emerald-700 hover:bg-emerald-100"
  activeButtonClasses="bg-emerald-600 text-white"
/>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`.

## Accessibility

The Pagination component carries the roles and labels a screen reader needs, and every link answers to the keyboard.

- **Keyboard Navigation**: Users can navigate through pagination using the tab key or the ← and → arrow keys to move focus, and Enter or Space to activate a button.

- **ARIA Labels**: The component includes appropriate `aria-label` attributes for previous, next, and page buttons, improving screen reader support. The active page link is marked with `aria-current="page"`.

- **Focus Indicators**: Clear focus styles ensure visibility when navigating with a keyboard.

- **Semantic HTML**: Uses proper HTML elements (`button` and `a`) inside a `role="group"` container labeled `aria-label="Pagination"`, so assistive technology reads it as one group of page links.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | Array | `[]` | An array of pagination links, where each object contains a URL and an optional active state. Each URL must be unique. |
| `align` | 'start' \| 'center' \| 'end' | `center` | Defines the alignment of the pagination. Options are 'start' for left, 'center' for middle, and 'end' for right. |
| `size` | [BUTTON_SIZE](https://www.theui.dev/docs/types#button-size-type) | `md` | Controls the size of the pagination buttons. Accepts predefined button size values. |
| `previousButton` | string | `← Prev` | Text of the previous button. It renders as plain text. |
| `nextButton` | string | `Next →` | Text of the next button. It renders as plain text. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Determines the border radius of the pagination buttons. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed of pagination interactions. Options include 'none', 'slower', 'slow', 'normal', 'fast', and 'faster'. |
| `activeButtonClasses` | string | `` | Custom CSS classes to style the active pagination button. |
| `buttonClasses` | string | `` | Custom CSS classes to style all pagination buttons. |

### Dynamic props

| Name | Description |
| --- | --- |
| `flat` | This attribute makes the Pagination border-less to make it flat and minimalist. |
| `hidePrevious` | This attributes hides the previous button in the Pagination. |
| `hideNext` | This attributes hides the next button in the Pagination. |
| `hidePreviousNext` | This attributes hides both previous and next button in the Pagination. |

### Functions

| Name | Description |
| --- | --- |
| `onPreviousClick` | Triggers on click on the previous button. Type: `(e: MouseEvent) => void`. |
| `onNextClick` | Triggers on click on the next button. Type: `(e: MouseEvent) => void`. |

---

Source: https://www.theui.dev/docs/popover

# Popover

A flexible and customizable UI element that displays additional content when triggered by user interaction. It is useful for providing contextual information, tooltips, or action menus without cluttering the interface.

## About

The **Popover** component allows developers to display a small floating panel next to a specified trigger element. It supports various customization options, including positioning, animation speed, rounded corners, shadow effects, and trigger events (click or hover). The popover can contain a title and body content, both of which can be styled individually using provided class props.

By default, the popover appears above (`top`) the trigger element with a configurable gap. It can be dismissed automatically when clicking outside or manually by interacting with the trigger.

## Example

The **Popover** component can be easily added to your project by wrapping the content you want to display inside it. The `trigger` prop connects the Popover component to a specific element by matching its `id`. When the user interacts with this element, the popover appears next to it. This ensures precise control over where and when the popover is displayed.

```html
<script>
  import { Popover } from "theui-svelte";
</script>

<Popover trigger="my-popover">
  Popover - am amazing component for the displaying additional content.
</Popover>

<Button id="my-popover">Test popover</Button>
```

## Popover Title

The **Popover** component allows adding a title to provide a heading or short description before the main content. You can add a title in two ways:

### Using the title Prop

You can use the `title` prop to define the title of the **Popover**. Just pass the text of the title in the prop. It renders as plain text, so use the title snippet for markup.

```html
<Popover trigger="my-popover" title="Popover Title">
  Popover - am amazing component for the displaying additional content.
</Popover>
```

### Using Snippet

Alternatively, for custom title you can use the `title` snippet.

```html
<Popover trigger="my-popover">
  {#snippet title()}
    Popover <span class="text-brand-500">Title</span>
  {/snippet}
  ...
</Popover>
```

## Position

The **Popover** component allows you to control where it appears relative to the trigger element using the position prop. By default, the popover appears at the top of the trigger, but you can set it to different positions like `top`, `bottom`, `left`, or `right`. You can also use more specific placements such as `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, and `right-end` to fine-tune alignment.

```html
<Popover trigger="my-popover" position="right">
  Popover - am amazing component for the<br>displaying additional content.
</Popover>
```

## Trigger Event

The **Popover** component supports different interaction types through the `triggerEvent` prop, allowing you to control how the popover is activated. By default, the popover opens when the trigger element is **clicked**, but you can also set it to open on **hover**.

### Available Options

- `click` (Default) - The popover appears when the user clicks the trigger element and closes when clicking outside.

- `hover` - The popover appears when the user hovers over the trigger element and disappears when moving away.

```html
<Popover trigger="my-popover5" triggerEvent="hover">
  Popover - am amazing component for the<br>displaying additional content.
</Popover>
```

## Popover Gap

The `gap` prop controls the spacing between the Popover and its trigger element. It accepts a number value, representing the offset in pixels. The default is `8`.

```html
<Popover trigger="my-popover" gap={16}>
  This popover has a larger gap from the trigger.
</Popover>
```

## Close on Clicking Popover

The `closeOnClick` prop determines whether the Popover should close when clicking inside it. By default, this is set to `true`, meaning the popover will close when the user interacts with its content. Set it to `false` to keep the popover open when clicking inside it.

```html
<Popover trigger="my-popover7" closeOnClick={false}>
  Clicking inside this popover won't close it.
</Popover>
```

## Animation Speed

The `animationSpeed` prop controls the speed of the animation when the Popover appears or disappears. It accepts the following values `none`, `slower`, `slow`, `normal`, `fast` and `faster` - which can be used to define how quickly the popover fades in and out.

```html
<Popover trigger="my-popover" animationSpeed="slower">
  This popover has a larger gap from the trigger.
</Popover>
```

## Rounded Corners

The `rounded` prop controls the corner rounding of the **Popover**. You can adjust it using predefined values to give the popover a smooth, rounded appearance. Available values are `sm`, `md`, `lg`, `xl`, `2xl`, `full` and `none`.

```html
<Popover trigger="my-popover" rounded="none">
  This popover has a larger gap from the trigger.
</Popover>
```

## Shadow

The `shadow` prop adds a shadow effect to the Popover, helping it stand out against the background. Available values are `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner`, `none`.

```html
<Popover trigger="my-popover" shadow="xl">
  This popover has a larger gap from the trigger.
</Popover>
```

## Customization

The **Popover** component offers multiple ways to customize its appearance using the `titleClasses`, `bodyClasses`, and `class` attributes. These allow you to apply custom styles to the title, body and the container of the popover.

- `titleClasses` prop lets you add custom styles to the **Popover title**, such as font size, color, or spacing.

- `bodyClasses` prop allows you to style the **Popover body**, including padding, background, border, and typography.

- `class` attribute allows you to styles the **Popover container**, modifying its overall look, size, or layout.

```html
<Popover
  trigger="my-popover"
  title="POPOVER TITLE"
  class="bg-blue-100 text-center"
  titleClasses="font-bold text-blue-500"
  bodyClasses="flex flex-col gap-4"
>
  This popover has a styled title and body.
  <p>
    <Button class="bg-blue-500 hover:bg-blue-600" size="sm">Button</Button>
  </p>
</Popover>
```

Anything else you pass reaches the element itself, so a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`. The `id` is the exception: the component sets its own so the trigger can point at it with `aria-controls`.

## Accessibility

The Popover handles focus, keyboard navigation, and the ARIA attributes that tie it to its trigger.

- **Keyboard Navigation** Users can open and close the popover using the Space or Enter keys while the trigger element is focused when `triggerEvent="click"`. The trigger element is made focusable automatically.

- Pressing Escape closes the popover when it is open when `triggerEvent="click"`.

- The popovers triggered by hover are also accessible via focus for keyboard users.

- **ARIA Attributes** The popover sets these ARIA attributes itself: The `aria-controls` links the trigger element to the popover container.

- The `aria-haspopup` on the trigger element to indicate a popover is available.

- The popover uses `role="dialog"` when `triggerEvent="click"` and `role="tooltip"` when `triggerEvent="hover"`.

- **Focus Management** When opened, focus remains on the trigger element.

- With `triggerEvent="click"`, the popover closes when clicking outside it or when keyboard focus moves away from both the trigger and the popover.

- With `triggerEvent="hover"`, the popover opens when the trigger receives focus and closes when it loses focus.

- The popover keeps its position next to the trigger while the page scrolls or resizes.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string \| Snippet | `undefined` | Defines the title of the popover. Can be a string or a Snippet. A string renders as plain text; use a Snippet for markup. |
| `trigger` | string | `undefined` | ID of the element that triggers the popover. It is a required prop. |
| `position` | [Placement](https://www.theui.dev/docs/types#placement) | `top` | Specifies the position of the popover relative to the trigger. |
| `triggerEvent` | "click" \| "hover" | `click` | Defines how the popover is triggered: by click or hover. |
| `gap` | number | `8` | Sets the distance between the trigger and the popover. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed of the popover. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border-radius of the popover. |
| `shadow` | [SHADOW](https://www.theui.dev/docs/types#shadow-types) | `lg` | Controls the shadow intensity of the popover. |
| `closeOnClick` | boolean | `true` | Determines whether the popover closes when clicking inside it. |
| `titleClasses` | string | `` | Allows custom classes for styling the title. |
| `bodyClasses` | string | `` | Allows custom classes for styling the popover body. |

---

Source: https://www.theui.dev/docs/popup

# Popup

A special type of modal that can be triggered when the page loads (Enter Popup) or when the user tries to leave the page (Exit Popup). This makes it ideal for welcome messages, promotions, or exit-intent offers.

## About

The **Popup** component provides flexible control over when and how it appears. You can trigger it on page **entry**, **exit**, or **both** using the `trigger` prop. The content of the popup can be customized separately for entry (`entryContent`) and exit (`exitContent`). You can also control whether it repeats on every visit, how the backdrop behaves, and apply custom styles.

## Example

The following examples show how to use the Popup component with different triggers and content configurations. You can display a popup when the page loads (onEntry), when the user tries to leave (onExit), or for both events (onEntryExit).

```html
<script>
  import { Popup } from "theui-svelte";
</script>

<Popup>
  Hello! I'm popup!
</Popup>
```

## Trigger Event

The `trigger` prop defines when the Popup appears. It supports three values: `'onEntry'`, `'onExit'`, and `'onEntryExit'`. The default value is `'onEntry'`.

### Entry Popup

When `trigger` is set to `'onEntry'`, the popup will automatically appear as soon as the page loads. No user interaction is needed to trigger it.

```html
<Popup trigger="onEntry"> <!-- Or just <Popup> as onEntry is default -->
  This is entry popup!
</Popup>
```

### Exit Popup

With `trigger` set to `'onExit'`, the popup will appear when the user moves their cursor toward the browser's close button or attempts to leave the page.

```html
<Popup trigger="onExit">
  This is exit popup!
</Popup>
```

### Both Entry-Exit Popup

Setting `trigger` to `'onEntryExit'` will make the popup appear both when the page loads and when the user tries to exit. It combines the behaviors of `'onEntry'` and `'onExit'`.

```html
<Popup trigger="onEntryExit">
  The popup appears in both entry and exit time!
</Popup>
```

Above example will display same content on entry and exit popup! But if you want, you can provide separate content for both entry and exit popup using the `entryContent` and `exitContent` snippet.

```html
<Popup trigger="onEntryExit">
  {#snippet entryContent()}
    <p class="text-success-500 font-bold">I'm content from entry popup!</p>
  {/snippet}

  {#snippet exitContent()}
    <p class="text-error-500 font-bold">I'm content from exit popup!</p>
  {/snippet}
</Popup>
```

## Popup Repetition

The `repeat` prop controls how often the Popup appears. It accepts three values: `true`, `false`, and `'page'`. The default value is `true`.

- `true` - The popup will appear every time the page loads, even if the user reloads the same page. This is the default behavior.

- `false` - The popup will appear only once, and it won't show again, even if the user navigates to a different page.

- `'page'` - The popup will appear once per page. If the user moves to another page, it will show again, but it won't repeat on the same page.

This feature allows precise control over popup behavior across pages. For example, to display the popup only once per visitor, set `repeat={"{"+false+"}"}`. To show the popup once per page the visitor visits, set `repeat="page"`. The visit history is saved in `localStorage` under the `entryPopUp` and `exitPopUp` keys.

## Popup Backdrop

### Static Backdrop

The `staticBackdrop` prop controls whether the Popup closes when clicking on the backdrop. By default, the backdrop is clickable, and clicking it will close the Popup. Setting `staticBackdrop` to `true` makes the backdrop static, meaning the Popup will remain open even when the backdrop is clicked.

```html
<Popup staticBackdrop={true}>
  This popup has a static backdrop!
</Popup>
```

### Backdrop Customization

The `backdrop` prop manages the visibility and style of the backdrop. When set to `true` (default), the backdrop is visible. If set to `false`, the backdrop will be hidden. You can also customize the backdrop by passing custom CSS classes, which will apply directly to the backdrop.

```html
<!-- No backdrop -->
<Popup backdrop={false}>
  This popup has no backdrop!
</Popup>

<!-- Custom backdrop -->
<Popup backdrop="bg-brand-500/80">
  This popup has a custom backdrop!
</Popup>
```

## Rounded Corners

The `rounded` prop sets the corner radius of the Popup. Available values are: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, and `full`. Default value `xl`.

```html
<Popup rounded="none">
  This popup has no rounded corners!
</Popup>
```

## Customization

You can pass your custom classes to the `Popup` component using the `class` attribute. These classes directly applies to the popup component.

```html
<Popup class="border-4 border-brand-200 bg-brand-500 text-on-brand-500">
  This is a custom popup with some extra classes!
</Popup>
```

## Accessibility

Here is what the Popup handles for you:

- **Keyboard Navigation**: You can use the Tab key to move through the popup and the Esc key to close it, making it easy to navigate with a keyboard.

- **Aria Roles**: The popup has `role="dialog"` and `aria-modal="true"` to let users know it's a modal window. Add your own `aria-labelledby` or `aria-label` attribute to the `Popup` so screen readers can announce its title.

- **Backdrop Handling**: The backdrop uses `role="presentation"`, so it is not announced by screen readers.

- **Custom Content**: The `entryContent` and `exitContent` props take any content, so write it so it reads clearly on its own.

The **Popup** is built to work well with screen readers and keyboard navigation, making sure everyone can use it comfortably.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | 'onEntry' \| 'onExit' \| 'onEntryExit' | `onEntry` | Defines when the popup should appear: on page load, before exit, or both. |
| `repeat` | boolean \| 'page' | `true` | Controls how often the popup appears. If true, it shows on every page load. If false, it appears only once. If 'page', it shows once per page. |
| `backdrop` | boolean \| string | `true` | Enables or customizes the popup backdrop. Accepts a boolean or a custom class for styling. |
| `staticBackdrop` | boolean | `false` | If true, prevents closing the popup by clicking outside of it. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `xl` | Defines the border-radius of the popup for consistent design. |

### Snippets

| Name | Description |
| --- | --- |
| `entryContent` | Content to display when the popup is triggered on page entry. |
| `exitContent` | Content to display when the popup is triggered on page exit. |

---

Source: https://www.theui.dev/docs/progress-bar

# Progress bar

The component is used to display progress visually. It helps indicate completion status in a clear and customizable way.

## About

The **Progress** provides flexible options for styling, orientation, and labeling. It supports both horizontal and vertical layouts, with customizable thickness, rounded corners, and additional styling classes. The progress value is determined by the `start` and `end` props, and labels can be displayed in different styles.

## Example

The following example shows a simple progress bar with a set start and end value, along with a label:

```html
<script>
  import { Progress } from "theui-svelte";
</script>

<Progress end={55} />
```

The `end` prop define the end limit of the progress. The `start` is **0** default.

## Progress Range

The `start` and `end` props define the progress range. The `start` prop sets the initial value, while the `end` prop sets the final value of the progress bar. By default, both values are `0`, which is the minimum value. The maximum value is `100`.

- If `start` and `end` are equal, the progress bar will appear empty. Only the label will be display (if available).

- If `start` is greater than `end`, they will swap their values to work properly.

- If `end` is greater than `start` (which is expected), the progress bar will fill accordingly.

- If `end` exceeds the maximum range (100), it will be considered as 100.

```html
<Progress start={55} end={55} label="55" />
<Progress start={75} end={45} label="55" />
<Progress start={25} end={55} label="55" />
<Progress start={25} end={155} label="55" />
```

## Thickness

The `thickness` prop controls the thickness of the progress bar. It accepts five values: `'px'`, `'sm'`, `'md'`, `'lg'`, and `'xl'`. The default value is `'md'`.

> **Note:** If the `thickness` is set to `'lg'` or `'xl'`, the label will always be displayed inline, regardless of the `labelVariant` setting.

```html
<Progress end={55} label="55" thickness="px" />
<Progress end={55} label="55" thickness="sm" />
<Progress end={55} label="55" thickness="md" />
<Progress end={55} label="55" thickness="lg" />
<Progress end={55} label="55" thickness="xl" />
```

## Label

The `label` prop defines the text displayed on the Progress bar, which can represent progress values or any custom text. By default, no label is shown unless explicitly set.

The `labelVariant` prop controls the appearance of the label. When set to `"inline"`, the label appears as inline text. When set to `"bubble"`, the label is enclosed within a bubble for better visibility. The default value for this prop is `"bubble"`.

```html
<Progress end={55} label="55" />
<Progress end={55} label="55" labelVariant="inline" thickness="lg" />
```

> **Note:** Regardless of the `labelVariant` setting, if the `thickness` is `'lg'` or `'xl'`, the label will automatically be displayed inline. Otherwise, it will follow the specified `labelVariant` value. More in the thickness section.

## Vertical Progress

You can add a vertical progress bar by jus adding the `vertical` attribute to the `Progress`.

```html
<Progress end={55} label="55" vertical />
```

## Dynamic Progress

You can update the progress bar with dynamically by making it reactive. The example given below.

```html
<script lang="ts">
  import { Progress } from "theui-svelte";
  let startValue = $state(0)
  let endValue = $state(40)
</script>

<Progress start={startValue} end={endValue} label={endValue}/>

<input type="range" bind:value={startValue} />
<input type="range" bind:value={endValue} />
```

## Customization

The progress bar is fully customizable. Use the `barClasses` prop to apply custom styles to the progress bar, and the `bubbleClasses` prop to customize the bubble label. The `rounded` prop controls the border radius of the progress bar. To further customize the progress bar track, apply classes directly to the `Progress` component using the `class` attribute.

```html
<Progress
  end={50}
  label="50"
  barClasses="bg-green-400"
  bubbleClasses="bg-green-600 text-white"
  class="bg-green-100"
  thickness="lg"
  rounded="none"
/>
```

Anything else you pass reaches the element itself, so an `id`, a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`.

## Accessibility

The Progress component sets the ARIA value attributes itself. Two things are left to you:

- **ARIA attributes**: The component automatically uses `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` to communicate the current progress and its range to screen readers.

- **Color contrast**: Ensure sufficient color contrast to make the progress bar readable for users with visual impairments.

- **Label visibility**: The `"bubble"` label sits above the bar, so leave room for it or it will cover whatever is directly above.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | number | `0` | The starting value of the progress bar. It defines the initial state of the progress. Recommended value: 0-100. |
| `end` | number | `0` | The ending value of the progress bar. It defines the final state of the progress. Recommended value: 0-100. |
| `label` | string | `undefined` | The label text to display on the progress bar. |
| `labelVariant` | 'inline' \| 'bubble' | `bubble` | Controls the appearance of the label. 'inline' displays the label inline, inside the progress bar, while 'bubble' displays it in a bubble format. With 'lg' or 'xl' thickness, the label is always inline. |
| `bubbleClasses` | string | `null` | Custom classes to style the bubble label when 'labelVariant' is set to 'bubble'. |
| `thickness` | 'px' \| 'sm' \| 'md' \| 'lg' \| 'xl' | `md` | Determines the thickness of the progress bar. 'px' is the thinnest, and 'xl' is the thickest. |
| `barClasses` | string | `` | Custom classes to apply to the progress bar itself. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Controls the rounded corners of the progress bar. This helps maintain design consistency. |
| `id` | string | `<RANDOM STRING>` | A unique identifier for the progress bar. If not provided, a unique ID is generated. |

### Dynamic props

| Name | Description |
| --- | --- |
| `vertical` | When set, the progress bar will be displayed vertically. Otherwise, it will be horizontal. |

---

Source: https://www.theui.dev/docs/qab

# Quick Action Button (QAB)

A floating action button fixed to a corner of the viewport. It opens a short menu of actions, so the common ones are one tap away instead of buried in a menu.

## About

The Quick Action Button (QAB) is a floating button fixed to a corner of the viewport. Tapping or hovering it opens the actions you put inside. Because it is fixed, render it once per page and keep it outside any scrolling container.

## Example

To use the Quick Action Button (QAB) in your Svelte application, you need to import both the `Qab` container and the `QabItem` component from the theui-svelte package:

```html
<script>
  import { Qab, QabItem } from "theui-svelte";
</script>

<Qab>
  <QabItem>Link 1</QabItem>
  <QabItem>Link 2</QabItem>
  <QabItem>Link 3</QabItem>
</Qab>
```

## Link

The `href` prop allows the main Quick Action Button (QAB) to function as a link. When this prop is set, the button will navigate to the specified URL when clicked.

```html
<Qab href="/about" />
```

In this example, clicking the main button will take the user to the `/about` page. This prop makes it easy to turn the QAB into a navigational link while still maintaining its quick action functionality.

## Alignment

The `align` prop controls the horizontal alignment of the Quick Action Button (QAB) container. You can set it to either `'start'` or `'end'`, with the default value being `'end'`.

By setting the `align` prop, you can easily control the horizontal position of the buttons within the container.

```html
<Qab align="end"> ... </Qab>
<Qab align="start"> ... </Qab>
```

## Sizes

The `size` prop lets you control how big the Quick Action Button (QAB) is. You can set it to `'sm'` for small, `'md'` for medium (which is the default), `'lg'` for large, or `'xl'` for extra large.

```html
<Qab size="sm"> ... </Qab>
<Qab size="md"> ... </Qab> <!-- Default -->
<Qab size="lg"> ... </Qab>
<Qab size="xl"> ... </Qab>
```

By changing the `size` prop, you can easily adjust the button's size to match your needs.

## Direction

The `direction` prop determines how the Quick Action Buttons (QAB) are arranged. You can set it to `'horizontal'` to place the buttons side by side, or `'vertical'` to stack them on top of each other. The default value is `'vertical'`.

```html
<Qab direction="horizontal"> ... </Qab>
<Qab direction="vertical"> ... </Qab> <!-- Default -->
```

By changing the `direction` prop, you can control whether the buttons are displayed in a row or a column, depending on your design needs.

## QAB Color

The `color` prop customizes the QAB button's appearance by applying predefined color themes. They are the same colors the Button uses. The available color options are `"brand"`, `"error"`, `"info"`, `"success"`, and `"warning"`. The default value is `"brand"`.

```html
<Qab color="info">
    <QabItem>1</QabItem>
    <QabItem>2</QabItem>
</Qab>
  ```

```html
<Qab>
    <QabItem color="success">1</QabItem>
    <QabItem color="error">2</QabItem>
    <QabItem color="warning">3</QabItem>
</Qab>
  ```

Each color carries a meaning, so a reader can tell a destructive action from a safe one. You can still pass your own classes, but the `color` prop keeps the whole app on one palette.

## Theme

The `theme` prop determines the overall style and background of the button. It accepts three values: `'default'`, `'soft'`, and `'gradient'`. The default theme applies the standard button styles, while the soft theme uses softer versions of the default colors for a softer look. The gradient theme gives a more vibrant feel by applying gradient backgrounds to the button.

### Soft Theme

The soft theme is a softer variation of the default button colors, making it suitable for more subtle designs.

```html
<Qab theme="soft" color="info"> ... </Qab>
```

```html
<Qab>
  <QabItem theme="soft" color="success">1</QabItem>
  <QabItem theme="soft" color="info">2</QabItem>
  <QabItem theme="soft" color="error">3</QabItem>
</Qab>
```

### Gradient Theme

The gradient theme fills the button background with a two color gradient.

```html
<Qab theme="gradient" gradientColor="success"> ... </Qab>
```

```html
<Qab>
  <QabItem theme="gradient" gradientColor="success">1</QabItem>
  <QabItem theme="gradient" gradientColor="info">2</QabItem>
  <QabItem theme="gradient" gradientColor="warning">3</QabItem>
</Qab>
```

> **Note:** The color prop can still be used with each theme to specify the button's color, allowing flexibility while maintaining consistency across different button themes.

## QAB Trigger Event

The `triggerEvent` prop controls how the Quick Action Button (QAB) is activated. You can choose `"click"` to make the button activate when the user clicks on it, or `"hover"` to activate it when the user moves their mouse over it. By default, it is set to `"click"`.

```html
<Qab triggerEvent="hover"> ... </Qab>
<Qab triggerEvent="click"> ... </Qab> <!-- Default -->
```

In `"hover"` mode, the items stay open while the pointer moves from the main button to the items, and keyboard users open them by focusing the main button. They close when the pointer or focus leaves the QAB.

## Disabled QAB

Add the `disabled` attribute to the `Qab` to disable the main button. It is dimmed and its items can't be opened. You can also disable an individual `QabItem`. A disabled QAB or item gets `aria-disabled="true"`, and a disabled link item has its link removed.

```html
<!-- Disabled main button -->
<Qab disabled> ... </Qab>

<!-- Disabled item -->
<Qab>
  <QabItem>1</QabItem>
  <QabItem disabled>2</QabItem>
</Qab>
```

## Rounded Button

The `rounded` prop adjusts how rounded the corners of the Quick Action Buttons (QAB) are. You can choose from different levels such as `"sm"` for slightly rounded corners, `"md"` for medium rounding, `"lg"`, `"xl"` or `"2xl"` for more rounded edges, `"full"` for fully circular buttons (default), or `"none"` to keep the corners sharp.

```html
<Qab rounded="none"> ... </Qab>
<Qab rounded="full"> ... </Qab> <!-- Default -->
```

## Animation Speed

The `animationSpeed` prop controls how fast the Quick Action Button (QAB) animations run. You can set it to values like `"none"` for no animation, `"slower"` or `"slow"` for a more gradual effect, `"normal"` for the default speed, or `"fast"` and `"faster"` for quicker animations. The default setting is `"normal"`.

```html
<Qab animationSpeed="slower"> ... </Qab>
<Qab animationSpeed="normal"> ... </Qab> <!-- Default -->
```

## Customization

There are various way to customize the QAB button and QAB items. You can use `theme`, `color`, and `gradientColor` prop to customize the color showing above.

### Main Button Customization

You can apply custom classes to customize the main QAB button with the `class` attribute. Also, to change the icon of the main QAB button, just use `icon` snippet.

```html
<Qab class="border-4 border-brand-200">
  {#snippet icon()}
  <Svg class="w-6 h-6">
    <path d="M2 1a1 1 0 0 ... 2 0 0 1 2-2z"/>
  </Svg>
  {/snippet}
</Qab>
```

### Item Customization

Use `class` attribute to apply custom classes to the QAB items. To change the icon write it inside the `QabItem` component.

Again, if you want to apply some common classes to the default icon of all the QAB items (items without their own content), you can use `iconClasses` on the `Qab` component. The items also inherit `size`, `rounded`, `theme`, `color` and `gradientColor` from the `Qab` component.

```html

<Qab iconClasses="text-yellow-300">
    <Svg>
      <path d="M8 1a5 5 0 0 ... 0 0 1 1-1h1V6a5 5 0 0 0-5-5"/>
    </Svg>
  <QabItem class="border-4 border-brand-200">
    <Svg>
      <path d="M13.601 2.326A7 0 ... 943-.049-.084-.182-.133-.38-.232"/>
    </Svg>
  </QabItem>
  <QabItem class="border-4 border-brand-200">
    <Svg>
      <path d="M3.654 1.328a 0 0 ... .362-1.03-.037-2.137.703-2.877z"/>
    </Svg>
  </QabItem>
</Qab>
```

## Accessibility

The QAB sets `aria-expanded` and `aria-controls` on the trigger, and Escape closes the open items.

### ARIA Labels

The `ariaLabel` prop sets the accessible name of the trigger. The default is `"Quick Action Button"`, which is worth changing to say what the button actually does.

A `QabItem` uses its content as its accessible name. If the content is only an icon, set `ariaLabel` on the item to describe the action. An item without content (showing the default icon) is named `"Quick Action Item"`.

```html
<Qab ariaLabel="Open quick actions">
  <QabItem ariaLabel="Call us">
    <Svg>...</Svg>
  </QabItem>
</Qab>
```

### Keyboard Navigation

The QAB supports standard keyboard interactions: use the `Tab` key to move to the main button and the items, and the `Enter` or `Space` keys to open the items or trigger an action. Pressing `Escape` closes the open items; if focus was on an item, it returns to the main button. In `"hover"` mode, the items open when the main button gets focus.

### Automatic ARIA Management

The QAB component automatically handles important ARIA attributes:

- The `role` attribute is set to `button`, or `link` when `href` is used.

- When the QAB has items, the main button gets `aria-expanded` to show whether the items are open, and `aria-controls` pointing to the items while they are open.

- A disabled QAB or QAB item gets `aria-disabled="true"`.

- The open items close when the user clicks anywhere outside the QAB.

## Configuration

---

Source: https://www.theui.dev/docs/radio-button

# Radio Button

A styled radio input that takes its size, animation speed and label classes from the Form or Fieldset around it.

## About

It is a native `<input type="radio">` underneath, so the browser handles the one-per-group behavior. What the component adds is the styling, the linked label, and the settings it picks up from its parent.

## Example

Here is a basic example of using the Radio Button component:

```html
<script>
  import { Radio } from "theui-svelte";
</script>

<Radio name="gender">Male</Radio>
<Radio name="gender">Female</Radio>
```

## Name and Value

The `name` and `value` props are what group the radio buttons. The `name` ensures that only one radio button from the group can be selected at a time, while the `value` represents the option this radio button stands for. To read which option is selected, use the `group` prop.

```html
<Radio name="myRadio" value="credit-card">Credit Card</Radio>
<Radio name="myRadio" value="paypal">Paypal</Radio>
```

## Selected Option

The `group` prop holds the value of the selected radio button. Give every radio button of the group the same `name` and bind the same variable with `bind:group`. The radio button whose `value` matches the bound variable is selected, so you can also preselect an option by setting that variable.

```html
<script>
  let plan = $state("free");
</script>

<Radio name="plan" value="free" bind:group={plan}>Free plan</Radio>
<Radio name="plan" value="pro" bind:group={plan}>Pro plan</Radio>

<p>Selected plan: {plan}</p>
```

## Radio Button Sizes

The `size` prop controls the size of the radio button, allowing flexibility for different UI layouts. Available sizes include `"sm"`, `"md"` (default), `"lg"` and `"xl"`.

```html
<Radio name="myRadio" size="sm">Small (sm) radio button</Radio>
<Radio name="myRadio" size="md">Medium (md) radio button</Radio>
<Radio name="myRadio" size="lg">Large (lg) radio button</Radio>
<Radio name="myRadio" size="xl">Extra Large (xl) radio button</Radio>
```

## Animation

The `animationSpeed` prop defines the speed of the radio button's selection transition. This improves user interaction by adding smooth effects when selecting options. The available values are `"none"`, `"slower"`, `"slow"` `"normal"` (default), `"fast"` and `"faster"`.

Setting it to `"none"`disables animations, while other values changes the transition speed.

```html
<Radio name="myRadio" animationSpeed="slower">Slower animation</Radio>
<Radio name="myRadio" animationSpeed="slow">Slow animation</Radio>
<Radio name="myRadio" animationSpeed="normal">Normal animation</Radio>
<Radio name="myRadio" animationSpeed="fast">Fast animation</Radio>
<Radio name="myRadio" animationSpeed="faster">Faster animation</Radio>
<Radio name="myRadio" animationSpeed="none">No animation</Radio>
```

## Resetting Style

The `reset` prop removes all default styles from the Radio Button component, leaving only the applied custom styles. This is useful for complete control over styling.

```html
<Radio name="myRadio" reset={true} class="checked:bg-green-500 focus:ring-green-200 focus:border-green-200">Option 1</Radio>
<Radio name="myRadio" reset={true} class="checked:bg-green-500 focus:ring-green-200 focus:border-green-200">Option 2</Radio>
```

## Disabled Radio Button

Add the native `disabled` or `readonly` attribute to prevent changes. The radio button and its label are dimmed and can't be clicked.

```html
<Radio name="myRadio" value="1" disabled>Disabled radio button</Radio>
```

## Label Position

The `labelPosition` prop controls where the label sits. It accepts `"end"` (default), which places the label after the radio button, and `"start"`, which places it before. The position follows the writing direction, so in a right-to-left layout `"start"` puts the label on the right.

```html
<Radio name="myRadio" value="after">Label after the radio button</Radio>
<Radio name="myRadio" value="before" labelPosition="start">Label before the radio button</Radio>
```

## Customization

The Radio Button component offers multiple ways to customize its appearance:

- `labelClasses` - Custom styles for the label. If used within a Fieldset or Form component, it inherits their `labelClasses`. The `size`, `animationSpeed` and `reset` props are inherited the same way.

- `wrapperClasses` - Additional classes for the wrapper , useful for layout adjustments.

- `class` - Apply custom styles to the radio button itself.

```html
<Radio name="myRadio"
  wrapperClasses="flex relative gap-4 text-nowrap"
  labelClasses="text-red-500 font-bold z-[1]"
  class="w-8 h-6"
>
  Option 1
</Radio>

<Radio name="myRadio"
  wrapperClasses="flex relative gap-4 text-nowrap"
  labelClasses="text-red-500 font-bold z-[1]"
  class="w-8 h-6"
>
  Option 2
</Radio>
```

## Accessibility

The `Radio` component uses the native `<input type="radio">`, so screen readers announce whether it is selected. When you bind `group`, the `aria-checked` attribute reflects the selection as well. It also supports `aria-disabled` through `props` for disabled states. Each radio button is associated with a `<Label>` for better accessibility. The radio buttons are grouped together, so only one can be selected at a time, and the label can be placed before the radio button with `labelPosition="start"` for right-aligned designs.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | unknown | `undefined` | The option this radio button stands for. It is sent with the form when the radio button is selected. |
| `group` | unknown | `undefined` | The selected value of the radio button group. Bindable: use `bind:group` on every radio button of the group to read or set the selection. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Controls the size of the radio button. Available options: "sm", "md", "lg", "xl". |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Determines the animation speed for state changes. Options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | If set to true, removes all default styles, allowing full customization. |
| `labelClasses` | string | `Inherited from Fieldset or Form, or "` | Custom classes for styling the label. |
| `wrapperClasses` | string | `` | Additional classes for styling the main wrapper of the radio button. |
| `labelPosition` | 'start' \| 'end' | `end` | Places the label before ("start") or after ("end") the radio button, following the writing direction. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the radio button and dims it together with its label. |
| `readonly` | Prevents changes and dims the radio button together with its label. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The label content of the radio button. |

---

Source: https://www.theui.dev/docs/rating

# Rating

The Rating component collects a score from the user, or shows one that has already been given. It works with the mouse, with touch and with the keyboard, supports half stars, and submits inside a form like any other input.

## Example

Import the component and bind a number to it. Clicking a star sets the value, and clicking the same star again clears it.

```html
<script>
  import { Rating } from "theui-svelte";
  let score = $state(3)
</script>

<Rating bind:value={score} />
```

## Sizes

The `size` prop accepts `sm`, `md`, `lg` and `xl`. The default is `md`.

```html
<Rating value={4} size="sm" readonly />
<Rating value={4} size="md" readonly />
<Rating value={4} size="lg" readonly />
<Rating value={4} size="xl" readonly />
```

## Half Stars

Add `allowHalf` to let the user pick half a star. Each star then has two halves to click, and the arrow keys step by `0.5`.

```html
<script>
  let halfScore = $state(2.5)
</script>

<Rating bind:value={halfScore} allowHalf size="lg" />
```

## Read Only

Use `readonly` to show a score that cannot be changed, such as the average of many reviews. Any fraction is drawn exactly, so `3.7` fills the fourth star seven tenths of the way. A read-only rating is announced as a single image, such as "Rating: 3.7 of 5".

```html
<Rating value={3.7} readonly />
<Rating value={5} readonly />
<Rating value={0} readonly />
```

## Maximum

The `max` prop sets how many stars there are. The default is `5`.

```html
<Rating value={2} max={3} readonly />
<Rating value={7} max={10} readonly />
```

## Disabled and Clearing

A `disabled` rating is dimmed and cannot be changed. Clicking the star that is already chosen clears the rating back to zero; pass `clearable={false}` when a score, once given, must stay.

```html
<Rating value={2} disabled />
<Rating value={3} clearable={false} />
```

## In a Form

Give the component a `name` and the score is submitted with the form, because the stars are real radio inputs underneath. The `onchange` callback runs with the new value whenever it changes.

```html
<form method="POST">
  <Rating name="score" value={4} onchange={(v) => console.log(v)} />
  <button>Send review</button>
</form>
```

## Custom Icon

The `icon` snippet replaces the star with any shape you like. It is drawn twice, once empty and once filled, and takes its colour from the classes below, so use `fill="currentColor"` or an SVG from the library.

```html
<script>
  import { Rating, Svg } from "theui-svelte";
</script>

<Rating value={4} readonly activeClasses="text-error-500">
  {#snippet icon()}
    <Svg size={0} class="size-full">
      <path d="M8 14.25s-6-4-6-8a3.5 3.5 0 0 1 6-2.45A3.5 3.5 0 0 1 14 6.25c0 4-6 8-6 8z"/>
    </Svg>
  {/snippet}
</Rating>
```

## Customization

Use `activeClasses` for the filled part, `inactiveClasses` for the empty part and `itemClasses` for every star, for example to change the gap or add a shadow.

```html
<Rating value={4} readonly activeClasses="text-brand-500" />
<Rating value={4} readonly activeClasses="text-success-500" inactiveClasses="text-success-500/25" />
<Rating value={4} readonly class="gap-3" itemClasses="drop-shadow" />
```

## Accessibility

An editable rating is a group of radio buttons, the pattern screen reader users already know. Tab moves to the group, the arrow keys move between stars, and Space picks one. Each star carries text such as "3 of 5", which you can reword with the `itemLabel` prop, and the group is named by `ariaLabel`. A read-only rating is a single image with its score in the label, so it is read at once instead of star by star. The score is never colour alone: the filled part is a different shape, and the value is in the label.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | `0` | The score. Bindable with `bind:value`. A read-only rating draws any fraction exactly. |
| `max` | number | `5` | Number of stars. |
| `allowHalf` | boolean | `false` | Lets the user pick half a star, so the value moves in steps of 0.5. |
| `readonly` | boolean | `false` | Shows the score without letting anyone change it. It is announced as a single image with its value. |
| `disabled` | boolean | `false` | Dims the rating and stops any change. With a name, the current value is still submitted. |
| `clearable` | boolean | `true` | Clicking the star that is already chosen clears the rating back to 0. |
| `size` | [RATING_SIZE](https://www.theui.dev/docs/types#rating-size-type) | `md` | Size of the stars: "sm", "md", "lg" or "xl". |
| `name` | string | `undefined` | Name of the field, so the score is submitted with the form. |
| `ariaLabel` | string | `Rating` | Accessible name of the rating, such as "Rate this product". |
| `itemLabel` | (value: number, max: number) => string | `` (v, m) => `${v} of ${m}` `` | Builds the text read for each star, and for the whole rating when it is read-only. |
| `onchange` | (value: number) => void | `undefined` | Runs with the new score every time it changes. |
| `itemClasses` | string | `` | Custom classes for every star. |
| `activeClasses` | string | `text-warning-400` | Custom classes for the filled part of the stars. |
| `inactiveClasses` | string | `text-gray-300 dark:text-gray-600` | Custom classes for the empty part of the stars. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the rating element, merged with the default classes. The gap between stars is set here. |

### Snippets

| Name | Description |
| --- | --- |
| `icon` | Replaces the star with your own shape. It is drawn twice, once empty and once filled, and takes the colour from activeClasses and inactiveClasses. |

---

Source: https://www.theui.dev/docs/select

# Select

The Select component provides a customizable dropdown for selecting options. It supports static and dynamic options, floating labels, and various styling options for flexibility.

## About

Options can be written out in the markup or passed as an array through the `options` prop. Floating labels, animation speed and the rest of the form settings come from the Form or Fieldset around the field.

## Example

You can use a `Select` component in two different ways. Either use the `options` prop to pass an array of options dynamically, or write the **** tags manually inside the component. If `options` is set, the content inside the component is ignored. Here's a basic example of the Select component in action:

```html
<script>
  import { Select } from "theui-svelte";

  let data = [
    { text: "Option 1", value: "1" },
    { text: "Option 2", value: "2" },
    { text: "Option 3 (Disabled)", value: "3", disabled: true }
  ]
</script>

<Select label="Select an option" options={data} />
```

## Default Value

The `value` prop allows you to set a default selection for the `Select` component. If a value is provided, the corresponding option will be pre-selected when the component loads. This ensures that users see a predefined choice without needing to manually select it. If no `value` is set, the first option (if available) will be selected by default.

```html
<Select label="Select an option" options={data} value="2" />
```

## Placeholder

The `placeholder` prop adds a disabled option at the top of the list, so the select can start without a real choice. It is only rendered when you set it; there is no placeholder by default. Because the option is disabled, the user cannot go back to it after picking something.

```html
<Select label="Select an option" options={data} placeholder="-- Select --" />
```

## Variant

The `variant` prop controls the appearance of the `Select` component. It has two options:

- `bordered`(default): Displays the select input with a visible border, making it distinct and well-defined.

- `flat`: drops the border and keeps only the bottom rule.

If the `Select` is inside a **Fieldset** or **Form**, it inherits their `variant` unless you set it here. Choosing `flat` also turns on the floating label, unless you set `floatingLabel` yourself.

```html
<Select label="Select an option" options={data} variant="bordered" />
<Select label="Select an option" options={data} variant="flat" />
```

## Label & Floating Label

The `label` prop allows you to add a label to the `Select` component, improving accessibility and user experience. The label can be simple text or a more complex element using a `Snippet`.

If `floatingLabel` is enabled, the label floats above the input when a value is selected. It stays static otherwise. This only works when the label is a string prop, not a `Snippet`, because a snippet is rendered as you wrote it.

The floating label is on by default when the `variant` is `"flat"`, and off for `"bordered"`. Inside a **Fieldset** or **Form**, the `floatingLabel` of the group is used, unless this `Select` sets its own `variant` or `floatingLabel`.

```html
<!-- Using label prop -->
<Select label="Select an option" options={data} />

<!-- Using label snippet -->
<Select options={data}>
  {#snippet label()}
    <div>
      <Label>Select an option</Label>
      <HelperText>This is helper text for the select input!</HelperText>
    </div>
  {/snippet}
</Select>
```

## Sizing

The `size` prop controls the overall size of the Select component. Available options are `"sm"`, `"md"`, `"lg"`, and `"xl"`, with `"md"` as the default. This affects padding, font size, and spacing for a consistent UI. Inside a **Fieldset** or **Form**, the `size` of the group is used unless you set it here.

```html
<Select ... size="sm" />
<Select ... size="md" />
<Select ... size="lg" />
<Select ... size="xl" />
```

## Rounded

The `rounded` prop controls the border-radius of the Select component. You can choose from `"none"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"` and `"full"` to determine the roundness of the corners. The default value is `"md"`, giving the component a moderate rounded appearance. Inside a **Fieldset** or **Form**, the `rounded` value of the group is used unless you set it here.

```html
<Select ... rounded="none" />
<Select ... rounded="sm" />
<Select ... rounded="md" />
<Select ... rounded="lg" />
<Select ... rounded="xl" />
<Select ... rounded="full" />
```

## Animation Speed

The `animationSpeed` prop allows you to control the speed of animations in the Select component. Available values include `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"`, `"faster"`, with `"normal"` being the default. Adjust this value to make transitions quicker or slower based on your needs. It is used for the focus and floating label transitions, and is inherited from a **Fieldset** or **Form** when it is not set here.

```html
<Select ... animationSpeed="slower" />
<Select ... animationSpeed="slow" />
<Select ... animationSpeed="normal" />
<Select ... animationSpeed="fast" />
<Select ... animationSpeed="faster" />
<Select ... animationSpeed="none" />
```

## Helper Text

The `helperText` prop allows you to add additional guidance or information below the Select component. It can be a simple string or a Snippet for more complex content. The helper text is linked to the select with `aria-describedby`, and a string renders as plain text, so use the snippet for markup.

```html
<!-- Using prop -->
<Select label="Select an option" options={data} helperText="This is helper text for the select input!" />
<!-- Using Snippet -->
<Select label="Select an option" options={data}>
  {#snippet helperText()}
    This is helper text for the select input!
  {/snippet}
</Select>
```

## Resetting All Styles

The `reset` prop removes all default styles, applying only the styles you provide. This gives full control over the appearance, making it ideal for custom designs.

```html
<Select ... size="sm" rounded="full" reset />
```

In this example, even though `size="sm"` and `rounded="full"` are set, they won't take effect because the `reset` prop removes all default styles, including size and rounded settings. Only the styles you manually apply will be used.

## Customization

The `size`, `variant`, `rounded`, `animationSpeed`, `labelClasses` and `reset` props are inherited from the nearest **Fieldset** or **Form**, so set them there to style a whole group at once.

- `wrapperClasses`: Style the outer container of the Select component to adjust margins, padding, or additional styling needs.

- `labelClasses`: Customize the label's style by applying custom classes, allowing better control over typography, spacing, and alignment.

- `class` attribute: Directly modify the Select element itself, giving you control over borders, background, and overall appearance.

```html
<Select label="Select an option" options={data}
  wrapperClasses="flex-row items-center gap-16"
  labelClasses="text-xl text-blue-500"
  class="text-blue-500 focus:ring-blue-500 focus:border-blue-500"
/>
```

## Accessibility

The `Select` component is fully accessible by default. It supports a linked label (floating or static) and connects to `HelperText` using `aria-describedby` for screen reader clarity. You can provide options via the `options` prop or write the **** tags inside the component, and every option supports `disabled` for better control. Set `placeholder` if you want the select to start without a real choice. Just make sure a visible `label` or `aria-label` is provided.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | [SELECT_DATA](https://www.theui.dev/docs/types#select-data-type)[] | `undefined` | Array of options for the select input. If it is set, the content of the component is ignored. |
| `value` | string | `undefined` | The selected value. Bindable: use `bind:value` to read or change the selection. |
| `placeholder` | string | `undefined` | Adds a disabled option at the top of the list. No placeholder is shown unless you set it. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `Inherited from Fieldset or Form, or "bordered` | Defines the visual style of the select input: "bordered" or "flat". |
| `label` | Snippet \| string | `undefined` | Defines the label for the select input. A string label is linked to the input; a Snippet is rendered as you wrote it. |
| `floatingLabel` | boolean | `Inherited from Fieldset or Form, or true when variant is "flat` | Makes the label float above the input. It only applies to a string label. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Controls the size of the select input. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `Inherited from Fieldset or Form, or "md` | Defines the border radius of the select input. Options: "none", "sm", "md", "lg", "xl", "2xl", "full". |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Controls the speed of the focus and floating label transitions. |
| `helperText` | Snippet \| string | `undefined` | Provides additional information below the select input, linked with `aria-describedby`. A string renders as plain text; use the snippet for markup. |
| `labelClasses` | string | `Inherited from Fieldset or Form, or "` | Applies custom styles to the label. |
| `wrapperClasses` | string | `` | Applies custom styles to the wrapper element. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Removes all default styles, applying only user-defined styles. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the select input and dims it. |
| `required` | Marks the select as required for form validation. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The `<option>` tags of the select. Used only when the `options` prop is not set. |
| `label` | The label of the select, as an alternative to the string prop. A Snippet label never floats. |
| `helperText` | Helper text shown below the select, as an alternative to the string prop. |

---

Source: https://www.theui.dev/docs/skeleton

# Skeleton

The Skeleton component stands in for content that has not arrived yet. Instead of an empty area or a spinning circle, the page already shows the shape of what is coming, so nothing jumps when the data lands.

## Example

Import the component and give it the size of the thing it replaces. The default variant is a rectangle.

```html
<script>
  import { Skeleton } from "theui-svelte";
</script>

<Skeleton />
```

## Variants

The `variant` prop takes `rect` (default), `circle` for avatars, and `text` for lines of writing.

```html
<Skeleton variant="rect" class="h-16" />
<Skeleton variant="circle" />
<Skeleton variant="text" />
```

## Text Lines

With `variant="text"`, the `lines` prop draws a paragraph. The last line is shorter, the way a real paragraph ends. Each line takes the line height of its parent, so the placeholder matches the text that will replace it.

```html
<Skeleton variant="text" lines={3} />

<!-- The line height comes from the parent -->
<div class="text-2xl">
  <Skeleton variant="text" lines={2} />
</div>
```

## Animation

The `animation` prop takes `pulse` (default), `wave` for a shimmer that travels across, and `none` for a still placeholder.

```html
<Skeleton animation="pulse" class="h-10" />
<Skeleton animation="wave" class="h-10" />
<Skeleton animation="none" class="h-10" />
```

## Size and Shape

Size comes from your own classes, so any width, height or aspect ratio works. The `rounded` prop sets the corner radius of the `rect` and `text` variants.

```html
<Skeleton class="h-8 w-40" rounded="full" />
<Skeleton class="aspect-video w-full max-w-sm" rounded="xl" />

<Skeleton variant="circle" class="size-8" />
<Skeleton variant="circle" class="size-12" />
<Skeleton variant="circle" class="size-16" />
```

## Card Placeholder

Put a few skeletons together to stand in for a whole card. Match the real layout as closely as you can, so the page does not move when the content arrives.

```html
<div class="w-full max-w-sm rounded-xl bg-secondary p-4">
  <Skeleton animation="wave" class="mb-4 aspect-video w-full" rounded="lg" />
  <div class="flex items-center gap-3">
    <Skeleton variant="circle" animation="wave" class="size-10" />
    <div class="grow">
      <Skeleton variant="text" animation="wave" lines={2} />
    </div>
  </div>
</div>
```

## Swapping in Content

Show the skeleton while the data is on its way and the real content once it arrives. Mark the area that is loading with `aria-busy`, so assistive technology knows the content is not final.

```html
<script>
  let loading = $state(true)
</script>

<div aria-busy={loading}>
  {#if loading}
    <Skeleton variant="text" lines={3} />
  {:else}
    <p>The real content is here now.</p>
  {/if}
</div>
```

## Customization

The `class` prop sets the size and the colour of the placeholder, and `lineClasses` styles every line of the `text` variant.

```html
<Skeleton class="h-10 bg-brand-500/20" />
<Skeleton class="h-10 bg-info-200 dark:bg-info-900" animation="wave" />
<Skeleton variant="text" lines={3} lineClasses="h-3 rounded-full" />
```

## Accessibility

A skeleton is decoration, so it is hidden from screen readers with `aria-hidden`. What matters is the area around it: put `aria-busy="true"` on the container while it loads, and remove it once the content is there. Announce the result in a live region if the wait is long. For people who prefer reduced motion both animations stop by themselves, leaving a plain placeholder.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | [SKELETON_VARIANT](https://www.theui.dev/docs/types#skeleton-variant-type) | `rect` | Shape of the placeholder: "rect", "circle" or "text". |
| `animation` | [SKELETON_ANIMATION](https://www.theui.dev/docs/types#skeleton-animation-type) | `pulse` | How the placeholder moves: "pulse", "wave" or "none". Both animations stop for users who prefer reduced motion. |
| `lines` | number | `1` | Number of lines of the "text" variant. With more than one, the last line is shorter. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the "rect" and "text" variants. The "circle" variant is always round. |
| `lineClasses` | string | `` | Custom classes for every line of the "text" variant. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the placeholder, merged with the default classes. Its size and colour are set here. |

---

Source: https://www.theui.dev/docs/slider

# Slider

Show images or any content one slide at a time, or several at once, with smooth effects, swipe, keyboard support and accessible controls.

## About

The Slider shows a set of slides one after another. Each slide is a `Slide` component that holds an image or any content. The Slider can play by itself, loop, follow a swipe or a mouse drag, show several slides at once, and change slides with effects like fade, zoom, flip and cube. It works in right-to-left pages and respects the user's reduced motion setting.

## Example

Put `Slide` components inside a `Slider`. By default the Slider plays by itself and shows arrows, dots, a timer bar and a pause button.

### Image Slider

Give a `Slide` an image with `src` and `alt`.

```html
<Slider>
  <Slide src="..." alt="..." />
  <Slide src="..." alt="..." />
  <Slide src="..." alt="..." />
</Slider>
```

### Custom Content Slider

A `Slide` can hold any content instead of an image. Use `class` to style the slide itself.

```html
<Slider>
  <Slide class="h-72 flex-col gap-2 bg-yellow-200">
    <h3>Build Faster</h3>
    <p>...</p>
  </Slide>
  <Slide class="h-72 flex-col gap-2 bg-rose-200"> ... </Slide>
  <Slide class="h-72 flex-col gap-2 bg-teal-200"> ... </Slide>
</Slider>
```

### Linked Slides

Add `href` to make the whole slide a link. The link is named by the image `alt` or by the slide content, so write an `alt` that describes where it goes. A drag or swipe never follows the link. Don't put other links or buttons inside a linked slide.

```html
<Slider>
  <Slide href="/summer" src="..." alt="Shop the summer collection" />
  <Slide href="/new" src="..." alt="See the new arrivals" />
</Slider>
```

## Controls & Indicator

The `controls` prop shows the previous and next buttons, and the `indicator` prop shows a dot for each slide. Both are `true` by default; set them to `false` to hide them. When the slider doesn't loop, the previous button is disabled on the first slide and the next button on the last.

```html
<Slider indicator={false} controls={false}> ... </Slider>
```

Without controls, users can still change slides by swiping or with the keyboard.

## Custom Controls Icon

Replace the arrow icons of the previous and next buttons with the `prevButton` and `nextButton` snippets. The buttons keep their accessible names.

```html
<Slider>
  <!-- Previous button -->
  {#snippet prevButton()}
    <Svg size={2} class="opacity-50">
      <path fill-rule="evenodd" d="M1 8a7 7 0 1 ... 1 .708.708L5.707 7.5z"/>
    </Svg>
  {/snippet}
  <!-- Next button -->
  {#snippet nextButton()}
    <Svg size={2} class="opacity-50">
      <path fill-rule="evenodd" d="M1 8a7 7 0 1 ... 1 0-.708.708L10.293 7.5z"/>
    </Svg>
  {/snippet}

  <Slide src="..." alt="..." />
  <Slide src="..." alt="..." />
  <Slide src="..." alt="..." />
</Slider>
```

## Auto Play & Stop on Hover

The `autoPlay` prop moves to the next slide by itself. It is `true` by default. At the last slide of a slider that doesn't loop, it goes back to the first slide.

Auto play pauses while the mouse is over the slider and continues from where it stopped when the mouse leaves. Set `stopOnHover` to `false` to keep it running. Auto play also pauses while keyboard focus is inside the slider, while the slider is scrolled out of view and while the browser tab is hidden. Moving to another slide restarts the timer.

```html
<Slider stopOnHover={false}> ... </Slider>
```

## Pause Button

When auto play is on, a pause button in the bottom corner stops and restarts it. Content that moves by itself needs a way to stop it, so keep this button unless you give users another one. Hide it with `pauseButton={false}`.

Use `bind:paused` to read the paused state or to pause the slider from your own control.

```html
<script>
  let paused = $state(false)
</script>

<button onclick={() => paused = !paused}>{paused ? "Play" : "Pause"}</button>

<Slider bind:paused pauseButton={false}> ... </Slider>
```

## Timer & Fraction

The `timer` prop shows a progress bar at the top that fills up until the next slide. It is `true` by default and only shows while auto play is on. The `fraction` prop shows a counter like `2 / 5` in the top corner. It is `false` by default. Use either one, both, or neither.

```html
<Slider timer={false} fraction> ... </Slider>
```

## Slide Duration

The `slideDuration` prop sets how long each slide stays, in milliseconds, before auto play moves to the next one. Default is `5000` (5 seconds).

```html
<Slider slideDuration={2000}> ... </Slider>
```

In the example each slide stays for 2 seconds.

## Transition Duration

The `transitionDuration` prop sets how long the move between two slides takes, in milliseconds. Default is `750`. Set it to `0` to change slides instantly.

```html
<Slider transitionDuration={2000}> ... </Slider>
```

In the example each move takes 2 seconds.

## Active Slide

The `activeSlide` prop sets the slide shown first, starting from `1`. Default is `1`. A number above the slide count shows the last slide.

`activeSlide` is bindable: `bind:activeSlide` follows the current slide, and changing the bound value moves the slider. The `onchange` callback runs with the new slide number every time the slide changes.

```html
<script>
  let active = $state(2)
</script>

<button onclick={() => active = 1}>Show 1</button>

<Slider bind:activeSlide={active} onchange={(slide) => console.log(slide)}> ... </Slider>
```

## Loop

By default the slider loops: after the last slide comes the first one, without a jump back. Set `loop` to `false` to stop at the first and last slides.

```html
<Slider loop={false}> ... </Slider>
```

## Effects

The `effect` prop sets how one slide changes to the next: `"slide"` (default), `"fade"`, `"zoom"`, `"flip"` or `"cube"`. Every effect follows a swipe or drag step by step. `perView`, `gap`, `peek` and `centered` only work with `"slide"`.

### Fade

The slides cross-fade.

```html
<Slider effect="fade"> ... </Slider>
```

### Zoom

The new slide grows in while the old one grows past its size and fades out.

```html
<Slider effect="zoom"> ... </Slider>
```

### Flip

The slide flips like a card, side to side. In a vertical slider it flips top to bottom.

```html
<Slider effect="flip"> ... </Slider>
```

### Cube

The slides are the sides of a turning cube. In a vertical slider the cube turns up and down.

```html
<Slider effect="cube" class="bg-gray-900"> ... </Slider>
```

## Ken Burns

The `kenBurns` prop slowly zooms and pans each image while its slide is shown, each slide in a different direction. It works with every effect and only on image slides (a `Slide` with `src`).

```html
<Slider effect="fade" kenBurns transitionDuration={1500}> ... </Slider>
```

## Parallax

### Image Parallax

The `parallax` prop moves the image of each slide slower than the slide, so it lags behind. `parallax` alone uses `0.5`; set a number from `0` to `1` for less or more. At `1` the image stays still and the slide edge wipes across it. It only works with the `"slide"` effect and on image slides.

```html
<Slider parallax> ... </Slider>
<Slider parallax={1}> ... </Slider>
```

### Layer Parallax

Elements inside any slide can move at their own speed while the slide changes. Add these attributes to an element:

- `data-parallax`: how far the element moves, as a part of the slide size. A higher number moves it more; a negative number moves it ahead of the slide.

- `data-parallax-opacity`: the element's opacity when its slide is out of view, so `0` fades it in as the slide arrives.

- `data-parallax-scale`: the element's scale when its slide is out of view, so `0.5` grows it in.

Layers work with every effect.

```html
<Slider>
  <Slide class="h-72 bg-yellow-200">
    <h3 data-parallax="0.6">Layer slide 1</h3>
    <p data-parallax="0.3" data-parallax-opacity="0">Each layer moves at its own speed.</p>
    <button data-parallax-scale="0.5" data-parallax-opacity="0">Read more</button>
  </Slide>
  ...
</Slider>
```

## Vertical Slider

Set `direction="vertical"` to move the slides up and down. A vertical slider needs a height; it is `h-96` by default and you can change it with `class`. The Up and Down arrow keys change slides, the controls sit at the top and bottom, and the dots move to the side.

```html
<Slider direction="vertical" class="h-80"> ... </Slider>
```

## Multiple Slides

### Slides Per View

The `perView` prop shows several slides at once, like a carousel, and `gap` sets the space between them. `gap` takes a number of pixels or any CSS length like `"1rem"`. The slider still moves one slide at a time.

```html
<Slider perView={3} gap={16}> ... </Slider>
```

### Responsive

`perView`, `gap` and `peek` also take a value per screen size, using the Tailwind breakpoints: `base`, `sm`, `md`, `lg`, `xl` and `2xl`. The largest matching screen size is used. Resize the window to see it change.

```html
<Slider perView={{ base: 1, sm: 2, lg: 3 }} gap={{ base: 8, lg: 20 }}> ... </Slider>
```

The screen size is known only in the browser, so a page rendered on the server starts with the `base` value.

## Peek & Centered

### Peek

The `peek` prop shows a part of the previous and next slides at the edges, so users can see there is more. It takes a number of pixels or any CSS length. The peeking slides can't be reached with the keyboard until they move into view.

```html
<Slider peek={{ base: 24, md: 80 }} gap={16}> ... </Slider>
```

### Centered

The `centered` prop places the active slide in the middle, with the other slides on both sides. It is useful with `perView`. Without `loop`, the first and last slides are centered too, with empty space beside them.

```html
<Slider centered perView={3} gap={12}> ... </Slider>
```

To loop, a slider needs more slides than it can show at once: at least `perView + 1`, or `perView + 3` with `peek`. With fewer slides it stops at the ends.

## Thumbnails

The `thumbnails` prop shows a strip of small images under the slider. Clicking one opens its slide, and the active thumbnail stays in the middle of the strip. A thumbnail uses the slide's `src`; set the `thumbnail` prop on a `Slide` to use another image, or for a content slide. A slide without an image shows its number. You can hide the dots with `indicator={false}`.

```html
<Slider thumbnails indicator={false}>
  <Slide src="..." alt="..." />
  <Slide src="..." alt="..." thumbnail="small-image.jpg" />
  <Slide thumbnail="preview.jpg"> <!-- Custom content --> </Slide>
</Slider>
```

## Swipe & Mousewheel

Users can swipe on touch screens and drag with the mouse. The slides follow the finger, and a move of a small part of a slide is enough to change it. A drag never clicks a link or button inside the slide. Turn it off with `swipe={false}`.

The `mousewheel` prop changes slides with the mouse wheel or a trackpad, one slide per gesture. It is `false` by default because it takes over page scrolling while the pointer is on the slider. Without `loop`, the page scrolls normally again at the first and last slides.

```html
<Slider direction="vertical" class="h-80" mousewheel loop={false}> ... </Slider>
```

## Hero & Background Slider

### Hero Slider

The `overlay` snippet holds content that stays on top while the slides change, like a title and a button over a set of images. Links, buttons and fields in the overlay can be clicked, and dragging on the rest of it still swipes the slides. Set a height with `class` for a full-height hero.

```html
<Slider class="h-[80vh]" effect="fade" kenBurns controls={false} ariaLabel="Hero images">
  {#snippet overlay()}
    <div class="size-full flex flex-col items-center justify-center gap-4 bg-black/30 text-white">
      <h1>Build faster with theui</h1>
      <a href="/docs">Get started</a>
    </div>
  {/snippet}
  <Slide src="..." alt="" />
  <Slide src="..." alt="" />
</Slider>
```

### Page Background

To use the slider as the background of the whole page, fix it behind the content and hide the parts users can't reach. The page content covers the slider's own pause button, so hide it and place your own pause button with `bind:paused`. Images that are only decoration can have an empty `alt`.

```html
<script>
  let paused = $state(false)
</script>

<Slider
  class="fixed inset-0 -z-10 h-auto"
  effect="fade"
  kenBurns
  controls={false}
  indicator={false}
  timer={false}
  swipe={false}
  pauseButton={false}
  bind:paused
  ariaLabel="Page background"
>
  <Slide src="..." alt="" />
  <Slide src="..." alt="" />
</Slider>

<button onclick={() => paused = !paused}>{paused ? "Play" : "Pause"} background</button>
```

## Right to Left

In a right-to-left page (`dir="rtl"`), the slider moves the other way: the next slide comes from the left, the controls swap sides, dragging follows the finger, and the Left arrow key goes to the next slide. The direction is read when the slider loads.

## Customization

Use `class` on the `Slider` for the whole slider and on a `Slide` for that slide. Other attributes, like `id`, go on the same element. These props style the other parts:

- `slideClasses`: classes for every slide, like padding, background or rounded corners.

- `controlButtonClasses`: classes for the previous and next buttons, to change their size, color or position.

- `indicatorContainerClasses`: classes for the container of the dots, to change their position or spacing.

- `indicatorClasses`: classes for every dot, to change its shape, size or color.

- `indicatorActiveClasses`: classes added to the dot of the active slide.

- `thumbnailContainerClasses`: classes for the thumbnail strip.

- `thumbnailClasses`: classes for every thumbnail, like its size.

- `thumbnailActiveClasses`: classes added to the thumbnail of the active slide.

- `timerClasses`: classes for the timer bar, like its height or color.

- `fractionClasses`: classes for the fraction counter, like its position or colors.

- `pauseButtonClasses`: classes for the pause button.

- `overlayClasses`: classes for the container of the `overlay` snippet.

Your classes are merged with the default classes, so a class you set replaces the default one it conflicts with.

## Accessibility

The Slider follows the WAI-ARIA carousel pattern, so it works with the keyboard and with screen readers.

#### Keyboard Navigation

When focus is on a control, a dot, a thumbnail or content inside the slider:

- ← and → move to the previous and next slide (↑ and ↓ in a vertical slider).

- Home and End move to the first and last slide.

- Tab moves through the pause button, the controls, the dots and the content of the slides in view.

- Enter or Space press the focused button.

When a key moves away from a slide that had focus, focus moves to the new slide.

#### Screen Reader Support

- The slider is announced as a carousel, named by the `ariaLabel` prop (default `"Slider"`). Give it a name that describes the slides.

- Each slide is announced as a slide with its position, like "2 of 5".

- Slides that are not in view are hidden from screen readers and can't be reached with Tab.

- Slide changes are announced when the user changes the slide, but not during auto play, so they don't interrupt.

- The previous, next, pause, dot and thumbnail buttons have accessible names, and the active dot and thumbnail are marked as current.

#### Motion

- Auto play stops while keyboard focus is inside the slider, and the pause button stops it for good.

- For users who turn on reduced motion in their system, slides change instantly and auto play, the timer, the pause button and the Ken Burns zoom are turned off.

## Configuration

### Slider

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay` | boolean | `true` | Moves to the next slide by itself. At the last slide of a slider that doesn't loop, it goes back to the first slide. |
| `paused` | boolean | `false` | Bindable. Auto play is stopped, by the pause button or by your own control. |
| `stopOnHover` | boolean | `true` | Pauses auto play while the mouse is over the slider. |
| `slideDuration` | number | `5000` | Time (in milliseconds) each slide stays before auto play moves to the next one. |
| `transitionDuration` | number | `750` | Time (in milliseconds) the move between two slides takes. 0 changes slides instantly. |
| `activeSlide` | number | `1` | Bindable. The current slide, starting from 1. A number above the slide count shows the last slide. |
| `onchange` | (activeSlide: number) => void | `undefined` | Runs with the new slide number every time the slide changes. |
| `loop` | boolean | `true` | After the last slide comes the first one. Looping needs more slides than the slider shows at once. |
| `swipe` | boolean | `true` | Changes slides by swiping on touch screens and dragging with the mouse. |
| `mousewheel` | boolean | `false` | Changes slides with the mouse wheel or a trackpad, one slide per gesture. |
| `effect` | [SLIDER_EFFECT](https://www.theui.dev/docs/types#slider-effect-type) | `slide` | How one slide changes to the next: "slide", "fade", "zoom", "flip" or "cube". |
| `kenBurns` | boolean | `false` | Slowly zooms and pans the image of each slide while it is shown. Works on image slides only. |
| `parallax` | boolean \| number | `false` | Moves the image of each slide slower than the slide. true is 0.5; a number sets the strength from 0 to 1. Works with the "slide" effect on image slides only. |
| `direction` | [SLIDER_DIRECTION](https://www.theui.dev/docs/types#slider-direction-type) | `horizontal` | Moves the slides side to side or, with "vertical", up and down. A vertical slider is h-96 unless you set a height with class. |
| `perView` | [SLIDER_RESPONSIVE](https://www.theui.dev/docs/types#slider-responsive-type)<number> | `1` | Number of slides shown at once, or a number per screen size. Works with the "slide" effect only. |
| `gap` | [SLIDER_RESPONSIVE](https://www.theui.dev/docs/types#slider-responsive-type)<number \| string> | `0` | Space between slides, in pixels or any CSS length, or a value per screen size. Works with the "slide" effect only. |
| `peek` | [SLIDER_RESPONSIVE](https://www.theui.dev/docs/types#slider-responsive-type)<number \| string> | `0` | Width of the previous and next slides shown at the edges, in pixels or any CSS length, or a value per screen size. Works with the "slide" effect only. |
| `centered` | boolean | `false` | Places the active slide in the middle. Works with the "slide" effect only. |
| `controls` | boolean | `true` | Shows the previous and next buttons. |
| `indicator` | boolean | `true` | Shows a dot for each slide. |
| `thumbnails` | boolean | `false` | Shows a strip of thumbnails under the slider. |
| `timer` | boolean | `true` | Shows a progress bar until the next slide while auto play is on. |
| `fraction` | boolean | `false` | Shows a counter like "2 / 5". |
| `pauseButton` | boolean | `true` | Shows a button that stops and restarts auto play. |
| `ariaLabel` | string | `Slider` | Accessible name of the slider. Describe what the slides show. |
| `slideClasses` | string | `` | Custom classes for every slide. |
| `controlButtonClasses` | string | `` | Custom classes for the previous and next buttons. |
| `indicatorContainerClasses` | string | `` | Custom classes for the container of the dots. |
| `indicatorClasses` | string | `` | Custom classes for every dot. |
| `indicatorActiveClasses` | string | `` | Custom classes added to the dot of the active slide. |
| `thumbnailContainerClasses` | string | `` | Custom classes for the thumbnail strip. |
| `thumbnailClasses` | string | `` | Custom classes for every thumbnail. |
| `thumbnailActiveClasses` | string | `` | Custom classes added to the thumbnail of the active slide. |
| `timerClasses` | string | `` | Custom classes for the timer bar. |
| `fractionClasses` | string | `` | Custom classes for the fraction counter. |
| `pauseButtonClasses` | string | `` | Custom classes for the pause button. |
| `overlayClasses` | string | `` | Custom classes for the container of the overlay snippet. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the slider element, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The Slide components. |
| `prevButton` | Custom content of the previous button, like an icon. |
| `nextButton` | Custom content of the next button, like an icon. |
| `overlay` | Content that stays on top while the slides change, like a hero title and button. |

### Slide

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | string | `undefined` | Image of the slide. Without it, the slide shows its content. |
| `alt` | string | `undefined` | Alternative text of the image. Use an empty string for a decorative image. |
| `href` | string | `undefined` | Makes the whole slide a link, named by the image alt or the slide content. |
| `thumbnail` | string | `undefined` | Image for the thumbnail of this slide. Defaults to src. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the slide, merged with the default classes and slideClasses. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | Custom content of the slide, used when src is not set. |

---

Source: https://www.theui.dev/docs/spinner

# Spinner

The Spinner component tells the user that something is on its way. Use it while data loads, while a form is being sent, or inside a button that is busy. Use the Progress bar instead when you know how far along the work is.

## Example

Import the component and place it where the content will appear. It carries the text "Loading" for screen readers, so nothing else is needed for it to be announced.

```html
<script>
  import { Spinner } from "theui-svelte";
</script>

<Spinner />
```

## Variants

The `variant` prop picks the shape: `ring` (default), `dots` or `ping`.

```html
<Spinner variant="ring" />
<Spinner variant="dots" />
<Spinner variant="ping" />
```

## Sizes

Sizes run from `xs` to `xl`, with `md` as the default. Every variant takes the same sizes.

```html
<Spinner size="xs" />
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
<Spinner size="xl" />
```

## Colors

The spinner is drawn in the current text colour, so a text colour class is all it takes to recolour it. The default is your brand colour.

```html
<Spinner />
<Spinner class="text-info-500" />
<Spinner class="text-success-500" variant="dots" />
<Spinner class="text-error-500" variant="ping" />
<Spinner class="text-muted" />
```

## With Text

Put text inside the component to show a visible message next to the spinner. The hidden "Loading" text is dropped in that case, because your own text is read instead.

```html
<Spinner>Loading your data...</Spinner>
<Spinner variant="dots" class="text-muted">Please wait</Spinner>
```

## In a Button

A spinner sits happily inside a button while the form is being sent. Keep the button disabled until the work is done.

```html
<button class="inline-flex items-center gap-2 ..." disabled>
  <Spinner size="xs" class="text-on-brand" label="Saving" />
  Saving...
</button>
```

## Customization

The `class` prop styles the wrapper, which is where the colour and the gap live, and `spinnerClasses` styles the moving shape itself, such as its border width.

```html
<Spinner size="lg" spinnerClasses="border-4 border-brand-500 border-e-transparent" />
<Spinner size="lg" spinnerClasses="border-dotted" />
<Spinner size="lg" class="gap-4 text-info-500 font-semibold">Uploading</Spinner>
```

## Accessibility

The spinner is a live status: it carries `role="status"` and a hidden label, set with the `label` prop, so a screen reader announces that something is loading without moving focus. Change `label` to say what is happening, such as "Saving" or "Sending", when several things can load on one page. For people who prefer reduced motion the animation slows down instead of stopping, so the message is still there. If the wait is long, tell the user what to expect in text rather than leaving a spinning shape alone.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | [SPINNER_VARIANT](https://www.theui.dev/docs/types#spinner-variant-type) | `ring` | Shape of the spinner: "ring", "dots" or "ping". |
| `size` | [SPINNER_SIZE](https://www.theui.dev/docs/types#spinner-size-type) | `md` | Size of the spinner: "xs", "sm", "md", "lg" or "xl". |
| `label` | string | `Loading` | Text read by screen readers. It is not used when you pass visible text as the child. |
| `spinnerClasses` | string | `` | Custom classes for the moving shape, such as its border width. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the wrapper, merged with the default classes. The spinner is drawn in the current text colour, so a text colour class recolours it. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Visible text shown next to the spinner, such as "Loading your data". |

---

Source: https://www.theui.dev/docs/svg-icon

# SVG Icon

The Svg component allows you to easily add SVG icons to your project. It acts as a wrapper for SVG elements and can replace the standard svg tag. You can include any path or other SVG elements within it.

## About

The `Svg` component wraps an icon's `<path>` elements in an `<svg>` with the size, the fill and the viewBox already set. Put the paths inside it and give the size in rem.

## Example

Start by importing the `Svg` component from the theui-svelte library.

You can embed any SVG elements, such as paths, circles, or groups, within the `Svg` component. Here's a simple example:

```html
<script>
  import { Svg } from "theui-svelte";
</script>

<Svg>
  <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
</Svg>
```

This will render a circle outline icon that uses the current text color.

## Icon Size

The `size` prop sets the icon's width and height in `rem`, so it is relative to the root font size. For example, a value of 1 renders the icon at 1rem. You can adjust this value to scale the icon larger or smaller.

**Default**: `1` (1rem)

```html
<Svg>
  <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
</Svg>
<Svg size={1.5}>
  <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
</Svg>
<Svg size={2}>
  <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/>
</Svg>
```

## Modify viewBox

The `viewBox` prop defines the coordinate system and dimensions of the SVG canvas. You can modify this value to adjust the visible area of the SVG content.

**Default**: `"0 0 16 16"`

```html
<Svg viewBox="0 -960 960 960">
  <path d="M200-120q-33 ... 56.5T760-120H200Zm0-80h560v-560H200v560Z"/>
</Svg>
```

## Stroke Icon

When the `stroke` attribute is passed to the `Svg` component, it changes the icon's styling from filled to stroked. This allows you to easily render stroke-based icons.

```html
<Svg stroke>
  <circle cx="8" cy="8" r="4" />
</Svg>
```

## Customization

For customization, you can add your own classes to customize the styles:

```html
<Svg class="fill-brand-500">
  <path d="M8 15A7 7 ... 0 0 16"/>
</Svg>
```

## Accessibility

The `SVG` component is built for flexible, accessible icons.

- **Decorative by default**: Uses `aria-hidden="true"` and `focusable="false"` to skip screen readers and keyboard navigation. Set `focusable={"{"}true{"}"}` to expose the icon to assistive technologies.

- **Custom size and viewbox**: Easily adjust using `size` and `viewBox` props.

- **Dynamic styling**: Use `stroke` prop or `class` for visual customization.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | number | `1` | Sets the icon's width and height in rem. A value of 1 renders the icon at 1rem. |
| `viewBox` | string | `0 0 16 16` | Sets the viewBox size of the icon. |
| `focusable` | boolean | `false` | Indicating whether the icon should be focusable via keyboard navigation. When false, the icon is also hidden from screen readers. |

### Dynamic props

| Name | Description |
| --- | --- |
| `stroke` | When set, it changes the icon's styling from filled to stroked, rendering the icon as an outline. |

---

Source: https://www.theui.dev/docs/table

# Table

A table you can build from data or write out by hand, with stripes, hover rows and border options.

## About

Pass `headers` and `data` and the `Table` builds the rows for you, or write `THead`, `TBody`, `TR`, `TH` and `TD` out by hand. The two styles mix freely, and the output is always wrapped in a horizontally scrollable container.

## Example

There are several ways to build a table. For example:

- Using data

- Using snippet

- Manually using the components

### Setup

At first import the relevant components of the table.

```html
<script>
  import { Table, THead, TBody, TR, TH, TD } from "theui-svelte";
</script>
```

### Example: Using Props

The `Table` component allows you to generate tables dynamically using data. This approach is useful when you have structured data and want to render it efficiently without manually defining each row and column. This method ensures your table remains dynamic and adaptable to different datasets.

Pass the `headers`, `data`, and `keys` as props to the `Table` component.

- `headers: string[]` - An array of column headers.

- `data: object[]` - An array of objects representing table rows.

- `keys: string[]` - An array of keys that map data fields to columns.

Cell values passed this way are rendered as plain text, so HTML inside them is not rendered. A key that is missing from a row renders an empty cell. To add custom markup, use the components as shown in the next example.

```html
<script>
  let headers = ["Heading 1", "Heading 2", "Heading 3", "Heading 4"];
  let data = [
    {item1: "Data 11", item2: "Data 12", item3: "Data 13", item4: "Data 14"},
    {item1: "Data 21", item2: "Data 22", item3: "Data 23", item4: "Data 24"},
    {item1: "Data 31", item2: "Data 23", item3: "Data 33", item4: "Data 43"},
  ];
  let keys = ["item1", "item2", "item3", "item4"];
</script>

<!-- Option 1 -->
<Table {headers} {data} {keys} />

<!-- Option 2 -->
<Table>
  <THead {headers} />
  <TBody {data} {keys} />
</Table>

<!-- Option 3 -->
<Table {headers}>
  <TBody>
    {#each data as d}
      <TR data={d} {keys} />
    {/each}
  </TBody>
</Table>
```

### Example: Using Components

Instead of props or dynamically looping through the data, the table content is written manually using the `THead`, `TBody`, `TR`, `TH` and `TD` components.

- `<THead>` - Contains the header row.

- `<TBody>` - Contains the table rows.

- `<TR>` - Represents a table row. Add `tableHeader={"{true}"}` to the header row so it gets the `trHeadClasses` styles. When a `TR` renders its cells from the `data` prop, `tableHeader` also makes it render `<th>` cells instead of `<td>`.

- `<TH>` - Represents a header cell.

- `<TD>` - Represents a table data containing the actual data.

```html
<Table>
  <THead>
    <TR tableHeader={true}>
      <TH>Heading 1</TH>
      <TH>Heading 2</TH>
      <TH>Heading 3</TH>
      <TH>Heading 4</TH>
    </TR>
  </THead>
  <TBody>
    <TR>
      <TD>Data 11</TD>
      <TD>Data 12</TD>
      <TD>Data 13</TD>
      <TD>Data 14</TD>
    </TR>
    ...
    ...
  </TBody>
</Table>
```

## Custom Header

If you need custom headers or anything other than text in the header just put your custom items in the `TH` component. For example:

```html
<Table>
  <THead>
    <TR>
      <TH class="items-center gap-2">
        Sort
        <Svg class="inline">
          <path d="M3.5 12.5a.5.5 0 0 ... 0 1h1a.5.5 0 0 0 0-1z"/>
        </Svg>
      </TH>
      <TH class="items-center gap-2">
        Sort
        <Svg class="inline">
          <path d="M3.5 2.5a.5.5 0 0 0-1 ... 1h1a.5.5 0 0 0 0-1z"/>
        </Svg>
      </TH>
    </TR>
  </THead>
</Table>
```

## Table Border

The `border` prop controls where borders appear in the table. By default, it is set to `"both"`. Setting it to `"x"` adds borders only between columns, while `"y"` applies borders only between rows. The default option, `"both"`, adds borders between both rows and columns, and `"none"` removes all borders. This prop allows you to customize the table's appearance based on your design preferences.

```html
<Table {headers} {data} {keys} border="x" />
<Table {headers} {data} {keys} border="y" />
<Table {headers} {data} {keys} border="none" />
```

## Table Spacing

The `space` prop adjusts the cell padding to control the overall table spacing, affecting how compact or spacious the table appears.

- `"compact"` - Reduces padding for a denser layout, making the table more space-efficient.

- `"default"` (Default value) - Uses the standard padding, providing a balanced look.

- `"comfortable"` - Increases padding for a more spacious and readable layout.

```html
<Table {headers} {data} {keys} space="compact" />
<Table {headers} {data} {keys} space="comfortable" />
```

## Stripe Rows

The `stripe` prop adds alternating background colors to table rows, improving readability and visual distinction between rows. By default, this feature is disabled (`undefined`), meaning all rows have the same background.

- `"even"` - Applies striping to even-numbered rows, making them visually distinct from odd rows.

- `"odd"` Applies striping to odd-numbered rows, enhancing readability by differentiating them from even rows.

- *Custom class names* - You can specify a class name instead of predefined values to apply custom styling. This allows full control over the appearance of striped rows, making it easy to match your design needs.

```html
<!-- Striped even rows -->
<Table {headers} {data} {keys} stripe="even" />
<!-- Striped odd rows -->
<Table {headers} {data} {keys} stripe="odd" />
<!-- Striped even rows with custom classes -->
<Table {headers} {data} {keys} stripe="even:bg-green-100 dark:even:bg-green-900" />
<!-- Striped odd rows with custom classes -->
<Table {headers} {data} {keys} stripe="odd:bg-green-100 dark:odd:bg-green-900" />
```

## Hoverable Rows

The `hover` prop enables a visual highlight effect when users hover over table rows. By default, this feature is disabled (undefined), meaning no hover effect is applied.

- `true` - When set to `true`, the row background color changes on hover, improving user experience and readability.

- *Custom class names* - Instead of using the default hover effect, you can pass a custom class to define your own hover styles, allowing for more design flexibility.

Use the `animationSpeed` prop to control how fast the hover color changes. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"` (default), `"fast"` and `"faster"`.

```html
<!-- Hoverable rows -->
<Table {headers} {data} {keys} hover={true} />
<!-- Hoverable rows with custom classes -->
<Table {headers} {data} {keys} hover="hover:bg-red-100" />
<!-- Slower hover transition -->
<Table {headers} {data} {keys} hover={true} animationSpeed="slower" />
```

## Customization

You can use the following props to customize the table's appearance, allowing you to style the table and its elements as needed.

- `borderColor` - the border color for the table. The default is `"border-gray-200/80 dark:border-gray-800/80"`, which reads in both light and dark mode. Override it with any Tailwind border color class.

- `trHeadClasses` - Adds custom classes to the table header row (( inside )). This allows you to style the header separately, such as applying background colors, text styles, or spacing adjustments.

- `trClasses` - Applies custom classes to all table body rows ( inside ). Use this to control row styling, such as padding, text alignment, or hover effects.

- `thClasses` - Adds custom classes to all table header cells (), enabling control over the header text size, padding, alignment, or other styles.

- `tdClasses` - Adds custom classes to all table cells (), enabling precise control over text size, padding, alignment, or other styles.

> **Note:** you can use `class` attribute with any table related component to add your custom CSS classes.

## Accessibility

A data table is read cell by cell, so a screen reader has to know which header each cell belongs to. Build the table from `headers` and `data` and that is handled: every header cell is written as `<th scope="col">`.

Writing the rows yourself works the same way, because `TH` now sets `scope="col"` on its own. Change it to `scope="row"` on a header cell that names its row, such as the first cell of each line in a comparison table.

**A header cell that names its row**

```svelte
<TR>
  <TH scope="row">Starter</TH>
  <TD>$9</TD>
  <TD>3 projects</TD>
</TR>
```

Give the table a name with `ariaLabel`, or write a `<caption>` as the first thing inside it. Screen readers list the tables on a page, and an unnamed one is listed as nothing but "table".

**Naming the table**

```svelte
<Table ariaLabel="Pricing plans" {headers} {data} />
```

A table wider than its container scrolls sideways. That box is a tab stop while it overflows, so people who do not use a mouse can scroll it with the arrow keys, and it is announced as a region using the name from `ariaLabel`. When the table fits, the tab stop disappears again, so it never adds a stop for nothing.

Two things are still yours to get right: keep the header row in a `THead` rather than styling the first body row to look like one, and do not use a table for layout, since everything in it is announced as data.

## Configuration

---

Source: https://www.theui.dev/docs/tabs

# Tabs

A simple and flexible way to organize content into multiple panels. It helps in structuring related information efficiently within a compact space.

## About

The Tabs component takes the tab buttons in a `tabs` snippet and the panels as its children. A `Tab` and a `TabPanel` are paired by a matching `value`, not by the order they appear in.

## Tab Values

Every `Tab` and every `TabPanel` takes a required `value`. A tab opens the panel that carries the same value, so the pairs are what link the two lists together. Use any string you like, as long as each pair is unique within one `Tabs`.

## Example

Below is an example of how to implement the Tabs component in your Svelte project. Each tab is linked to a specific content panel, and when you click a tab, the respective content is displayed.

```html
<script>
  import { Tabs, Tab, TabPanel } from "theui-svelte";
</script>

<Tabs>
  {#snippet tabs()}
    <Tab value="tab1">Tab 1</Tab>
    <Tab value="tab2">Tab 2</Tab>
    <Tab value="tab3">Tab 3</Tab>
  {/snippet}
  <TabPanel value="tab1">TabPanel 1</TabPanel>
  <TabPanel value="tab2">TabPanel 2</TabPanel>
  <TabPanel value="tab3">TabPanel 3</TabPanel>
</Tabs>
```

- The `Tabs` component wraps both the `Tab` and `TabPanel` components.

- Each `Tab` and `TabPanel` requires a `value` prop. A tab is linked to the panel with the same `value`, and clicking on a tab will show the associated content.

- The first tab is selected by default.

## Variant

The `variant` prop allows you to customize the style of the tabs. It accepts two values: `"tabs"` and `"pills"`.

- `"tabs"`: Displays the tabs in a traditional horizontal layout with square or rectangular edges.

- `"pills"`: Displays the tabs with rounded edges, giving them a pill-like appearance.

By default, the `variant` is set to `"pills"`, giving the tabs a rounded pill-like design. You can change this to `"tabs"` if you prefer a more classic tab design with square edges.

```html
<Tabs variant="tabs"> ... </Tabs>
```

## Animation Speed

The `animationSpeed` prop controls the transition speed of the tabs when their style changes, like on hover or when a tab becomes active. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"` (default), `"fast"` and `"faster"`. A panel fades in when it is shown; set `animationSpeed` to `"none"` to switch panels without the fade.

```html
<Tabs animationSpeed="none"> ... </Tabs>
```

## Customization

The `Tabs` component is highly customizable, allowing you to tailor its appearance and behavior to fit your design needs. You can adjust various parts of the component using the following props:

### Border Customization

The `"border"` prop controls the border of the tabs. By default, it is set to `true`, which applies the default border style. You can pass a custom class or a `boolean` value to either enable or disable the border.

- `true` (default): Applies the default border.

- `false`: Disables the border.

- `string`: You can pass a custom class for border styling.

```html
<!-- Custom border classes -->
<Tabs border="border-b-4 border-brand-300"> ... </Tabs>
```

### Customize the Tab Container

The `"tabContainerClasses"` prop allows you to customize the tab list container. You can pass any valid Tailwind or custom class to modify the appearance of the tab list.

```html
<Tabs tabContainerClasses="flex justify-center"> ... </Tabs>
```

### Tab Customization

To customize the tabs, use `"tabClasses"` ans `"tabActiveClasses"` props. The `"tabClasses"` prop applies to all tabs, while the `"tabActiveClasses"` prop is applied only to the active tab, overriding the styles from `"tabClasses"`.

```html
<Tabs
  tabClasses="text-gray-500 hover:text-blue-500"
  tabActiveClasses="bg-blue-800 text-blue-50 hover:text-blue-200"
>
  ...
</Tabs>
```

### Panel Customization

You can use the `"tabPanelClasses"` prop to customize the style of the tab panels. You can pass custom classes for margin, padding, background color, or any other styling.

```html
<Tabs tabPanelClasses="p-4 bg-gray-100"> ... </Tabs>
```

### Customize Individual Component

If you want to customize a specific `Tab` or `TabPanel` or event the `Tabs` component, you can use the native `class` attribute with that component.

```html
<Tabs class="border-2 border-yellow-500 py-2 px-4 rounded-lg">
  {#snippet tabs()}
    <Tab value="tab1">Tab 1</Tab>
    <Tab value="tab2" class="font-bold text-2xl">Tab 2</Tab>
    <Tab value="tab3">Tab 3</Tab>
  {/snippet}
  <TabPanel value="tab1">TabPanel 1</TabPanel>
  <TabPanel value="tab2" class="bg-yellow-100 p-4">TabPanel 2</TabPanel>
  <TabPanel value="tab3">TabPanel 3</TabPanel>
</Tabs>
```

In the example above, the native `class` attribute is applied to the `Tabs` component, the second `Tab`, and the second `Tabpanel`.

## Accessibility

The `Tabs` component follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).

- **Built-in Accessibility Features**: The component includes essential ARIA attributes and roles: `role="tablist"` for the container that holds all tabs.

- `role="tab"` for each tab with `aria-selected="true"` on the active one, and `aria-controls` pointing to its panel.

- `role="tabpanel"` for each content section with `aria-labelledby` linking it to its respective tab.

        These attributes are what a screen reader reads to move through the tabs.

- **Keyboard Navigation**: Users can move to the tabs using Tab key, and activate a tab with Enter or Space. Inside the tab list, Arrow Right and Arrow Left move to the next or previous tab (wrapping around at the ends), and Home and End move to the first or last tab. The focused tab is activated right away.

- **Customization Considerations**: When applying custom styles, ensure **focus indicators** remain visible, **contrast is sufficient**, and **animations do not disrupt usability**, particularly for users with motion sensitivity.

By following these best practices, the Tabs component provides an inclusive and accessible experience.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | 'tabs' \| 'pills' | `pills` | Defines the visual style of the tabs. By default, the variant is set to 'pills'. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Defines the speed of tab transitions. The default value is 'normal'. Set it to 'none' to show the panels without the fade effect. |
| `border` | boolean \| string | `true` | Controls whether the border styling is applied to the tabs. Can be a boolean or a custom string for classes. |
| `tabContainerClasses` | string | `` | Custom classes for the tab list container. |
| `tabClasses` | string | `` | Custom classes for each tab element. |
| `tabActiveClasses` | string | `` | Custom classes applied to the active tab. |
| `tabPanelClasses` | string | `` | Custom classes for each tab panel. |
| `id` | string | `<RANDOM STRING>` | An optional unique identifier for the Tabs component. |

### Tab props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `<REQUIRED>` | Links the tab to the `TabPanel` with the same value. Each value is used once per `Tabs`. |
| `children` | Snippet | `<REQUIRED>` | The label of the tab. |
| `class` | string | `null` | Classes for this tab only, merged with `tabClasses` of the `Tabs`. Any other attribute is passed to the tab element. |

### TabPanel props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `<REQUIRED>` | Links the panel to the `Tab` with the same value. |
| `children` | Snippet | `<REQUIRED>` | The content of the panel. |
| `class` | string | `null` | Classes for this panel only, merged with `tabPanelClasses` of the `Tabs`. Any other attribute is passed to the panel element. |

### Snippets

| Name | Description |
| --- | --- |
| `tabs` | The list of tab elements to be displayed inside the Tabs component. |
| `children` | The list of tab panels. Each `TabPanel` is linked to the `Tab` with the same `value`. |

---

Source: https://www.theui.dev/docs/toggle

# Toggle

Fully customizable switch that can replace traditional checkboxes and radio buttons.

## About

The `Toggle` component is a switch for a boolean value. It renders a checkbox by default, or a radio when you set `type="radio"`, and carries `role="switch"` either way.

## Example

The Toggle component can be used in various ways depending on your needs. Below is a basic example:

```html
<script>
  import { Toggle } from "theui-svelte";
</script>

<Toggle name="toggle">Enable Feature</Toggle>
```

Use it in forms and settings panels, anywhere an on and off switch reads better than a checkbox.

## Toggle Type

The `type` prop defines whether the toggle functions as a checkbox or a radio button.

```html
<!-- Checkbox (default) -->
<Toggle name="toggle1" type="checkbox">Checkbox 1</Toggle>
<Toggle name="toggle2" type="checkbox">Checkbox 2</Toggle>

<!-- Radio buttons -->
<Toggle name="toggle3" type="radio" value="1">Radio button 1</Toggle>
<Toggle name="toggle3" type="radio" value="2">Radio button 2</Toggle>
```

## Name and Value

The `name` and `value` props are what the form submission uses, whether the Toggle is a **checkbox** or a **radio button**.

- The `name` prop is required for radio buttons to group multiple toggles under the same name, allowing only one to be selected at a time.

- The `value` prop sets the value of the input. It can be anything: text, number or boolean. When used as a radio button, the value represents the option.

- The `checked` prop controls the state of a checkbox toggle. It is `false` by default and can be bound with `bind:checked`.

- The `group` prop holds the selected value of radio toggles with the same name. Bind it with `bind:group` to get the selected option.

```html
<script>
  let notification = $state(false);
  let gender = $state();
</script>

<Toggle name="preferences" value="ok" bind:checked={notification}>Enable Notifications</Toggle>

<Toggle name="gender" type="radio" value="male" bind:group={gender}>Male</Toggle>
<Toggle name="gender" type="radio" value="female" bind:group={gender}>Female</Toggle>
```

## Toggle Sizes

The `size` prop controls the dimensions of the toggle switch, allowing it to fit various UI designs. Whether you need a compact switch for minimal layouts or a larger one for better accessibility, the `size` prop provides flexibility. Available sizes are: `sm`, `md` (default), `lg` and `xl`.

```html
<Toggle name="toggle" size="sm">Small (sm) toggle</Toggle>
<Toggle name="toggle" size="md">Medium (md) toggle</Toggle>
<Toggle name="toggle" size="lg">Large (lg) toggle</Toggle>
<Toggle name="toggle" size="xl">Extra large (xl) toggle</Toggle>
```

## Animation

The `animationSpeed` prop sets how long the knob takes to slide across. Available values are: `slower`, `slow`, `normal` (default), `fast`, `faster` and `none`.

```html
<Toggle name="toggle" animationSpeed="slower">Slower animation</Toggle>
<Toggle name="toggle" animationSpeed="slow">Slow animation</Toggle>
<Toggle name="toggle" animationSpeed="normal">Normal animation</Toggle>
<Toggle name="toggle" animationSpeed="fast">Fast animation</Toggle>
<Toggle name="toggle" animationSpeed="faster">Faster animation</Toggle>
<Toggle name="toggle" animationSpeed="none">No animation</Toggle>
```

## Rounded Toggle

The `rounded` prop defines the shape of the toggle's switch and background. By adjusting this property, you can make the toggle appear more circular or squared. Available values are: `sm`, `md`, `lg`, `xl`, `2xl`, `full` (default) and `none`.

```html
<Toggle name="toggle" size="xl" rounded="sm">Small rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="md">Medium rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="lg">Large rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="xl">Extra large rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="full">Full rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="none">Not rounded</Toggle>
```

> **Note:** Note: the "xl" size is used here so the switch is easy to see in the demo.

## Label Position

The `labelPosition` prop controls where the label sits. It accepts `"end"` (default), which places the label after the toggle, and `"start"`, which places it before. The position follows the writing direction, so in a right-to-left layout `"start"` puts the label on the right.

```html
<Toggle name="toggle">Label after the toggle</Toggle>
<Toggle name="toggle" labelPosition="start">Label before the toggle</Toggle>
```

## Resetting Style

The `reset` prop removes all default styles from the Toggle component, so only the classes you pass are applied. This is useful when you want full control over the design. It is inherited from the nearest **Fieldset** or **Form**, so a whole form can be reset at once.

```html
<Toggle name="toggle" reset class="w-10 h-5 appearance-none rounded-full bg-green-200 checked:bg-green-500">Reset toggle</Toggle>
```

## Disabled Toggle

Add the native `disabled` or `readonly` attribute to prevent changes. The toggle and its label are dimmed and can not be clicked.

```html
<Toggle name="toggle" disabled>Disabled toggle</Toggle>
<Toggle name="toggle" checked disabled>Disabled toggle (on)</Toggle>
```

## Customization

The `Toggle` component offers flexibility in styling through the `labelClasses`, `wrapperClasses`, and `class` props, allowing you to adjust the appearance of both the label and the toggle's outer container.

`class` The `class` attribute can be used to apply custom styles directly to the toggle input. This gives you full control over its appearance, making it easy to align with your design system.

`wrapperClasses` The `wrapperClasses` prop lets you apply custom styles to the main wrapper . By default, it is an empty string, meaning no additional styles are applied unless specified.

`labelClasses` The `labelClasses` prop is inherited from the parent **Fieldset** or **Form** when there is one. The `size`, `animationSpeed` and `reset` props are inherited the same way. However, you can override it to apply custom styles to the label as needed.

```html
<Toggle
  labelClasses="text-red-500 font-bold"
  wrapperClasses="shadow-xl py-2 px-4 bg-gray-100 dark:bg-gray-800 rounded-full"
  class="bg-blue-200 checked:hover:bg-green-500 checked:focus:bg-green-500 checked:bg-green-500 focus:!ring-gray-500 checked:focus:!ring-green-500"
>
  CUSTOM TOGGLE
</Toggle>
```

## Accessibility

The Toggle carries `role="switch"` and keeps `aria-checked` in step with its state, so a screen reader reads out whether it is on or off. As a checkbox, `aria-checked` follows `checked`. As a radio, it is true when `group` matches the toggle's `value`. The label is tied to the input with `for`, so clicking the text flips the switch as well.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | "checkbox" \| "radio" | `checkbox` | Specifies whether the toggle functions as a checkbox or a radio button. |
| `value` | unknown | `undefined` | Value of the toggle input. It could be anything, text, numeric or boolean! |
| `checked` | boolean | `false` | The checked state of a checkbox toggle. Bindable with `bind:checked`. |
| `group` | unknown | `undefined` | The selected value of a radio toggle group. Bindable with `bind:group`. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form component or "md` | Defines the size of the toggle. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form component or "normal` | Controls the animation speed when toggling. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Defines the border-radius of the toggle switch. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | If set to true, removes all default styles, allowing full customization. |
| `wrapperClasses` | string | `` | Custom CSS classes applied to the wrapper div. |
| `labelPosition` | 'start' \| 'end' | `end` | Places the label before ("start") or after ("end") the toggle, following the writing direction. |
| `labelClasses` | string | `Inherited from Fieldset or Form component or "` | Custom CSS classes for styling the label. Inherits from the Fieldset or Form component if available. |

### Dynamic props

| Name | Description |
| --- | --- |
| `disabled` | Disables the toggle and dims it together with its label. |
| `readonly` | Prevents changes and dims the toggle together with its label. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | The label content of the toggle. |

---

Source: https://www.theui.dev/docs/tooltip

# Tooltip

The Tooltip component provides a way to display informative text when users hover over or click on an element.

## About

The Tooltip component shows a short piece of text when the visitor hovers or focuses an element. Render it once per page, then opt individual elements in with a `data-tooltip` attribute.

This component is highly flexible and supports various animations, colors, and positions. You can easily configure its behavior to appear on hover or click, making it suitable for a wide range of use cases. The Tooltip is designed to be accessible and visually appealing, with customizable animations and styles.

## Example

### Import & Initialize Tooltip

To use the `Tooltip` component, first import it from theui-svelte. It's recommended to initialize `Tooltip` globally, such as in `+layout.svelte`, to make tooltips available throughout your app. Alternatively, you can include it on specific pages where needed.

```html
<script>
  import { Tooltip } from "theui-svelte";
</script>

<Tooltip />
```

### Use with an Element

Once initialized, the Tooltip component enables tooltips in your application. It works in the background, automatically handling hover interactions for elements with tooltip attributes. The `data-tooltip` text can include simple HTML (like `<br>`); it is sanitized before rendering.

```html
<Button data-tooltip="I'm tooltip!">Open tooltip</Button>
```

## Position

The **Tooltip** component lets you control its position using the `position` prop or the `data-tooltip-position` attribute. The `position` prop applies to all tooltips, while `data-tooltip-position` affects only a specific trigger.

By default, the tooltip is displayed at the top, but you can change it to `bottom`, `left`, or `right` as needed. For more precise control, you can use variations like `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, and `right-end` to adjust alignment based on your design requirements.

```html
<!-- Applied to all the Tooltip -->
<Tooltip position="top-end" />

<!-- Applied only to the Tooltip of the trigger -->
<Button data-tooltip-position="top-end" data-tooltip="...">...</Button>
```

## Trigger Event

You can control how the tooltip appears using the `triggerEvent` prop or the `data-tooltip-event` attribute on the trigger element.

- The `triggerEvent` prop applies the same event to all tooltips. By default, it is set to `hover`, but you can change it to `click` to trigger the tooltip on click instead.

- The `data-tooltip-event` attribute allows setting the event for a specific tooltip without affecting others.

```html
<Button data-tooltip="I'm tooltip!" data-tooltip-event="hover">Click me</Button>
<Button data-tooltip="I'm tooltip!" data-tooltip-event="click">Click me</Button>
```

## Animation Speed

You can control the tooltip's animation speed using the `animationSpeed` prop or the `data-tooltip-animation-speed` attribute on the trigger element. Available values are `none`, `slower`, `slow`, `normal`, `fast` and `faster`.

- The `animationSpeed` prop applies the same animation speed to all tooltips.

- The `data-tooltip-animation-speed` attribute allows setting the animation speed for a specific tooltip without affecting others.

```html
<Button data-tooltip="I'm tooltip!" data-tooltip-animation-speed="none">Button</Button>
```

## Rounded Corner

You can customize the tooltip's border-radius using the `rounded` prop or the `data-tooltip-rounded` attribute on the trigger element. Available values are `sm`, `md`, `lg` (default), `xl`, `2xl`, `full` and `none`.

- The `rounded` prop applies the same corner style to all tooltips.

- The `data-tooltip-rounded` attribute allows setting a different border-radius for specific tooltips without affecting others.

```html
<Button data-tooltip="I'm tooltip!" data-tooltip-rounded="none">Button</Button>
```

## Tooltip Gap

You can adjust the spacing between the tooltip and its trigger using the `gap` prop or the `data-tooltip-gap` attribute on the trigger element. Default gap is `12`(px), and the minimum is `8`(px).

- The `gap` prop sets the spacing for all tooltips globally.

- The `data-tooltip-gap` attribute allows setting the spacing for a specific tooltip without affecting others.

```html
<Button data-tooltip="I'm tooltip!" data-tooltip-gap="20">Button</Button>
```

## Customization

You can customize the Tooltip component using the class attribute on the tooltip itself or the data-tooltip-style attribute on the trigger element.

- The `class` attribute applied directly to the Tooltip component will be applied to **all tooltips**.

- The `data-tooltip-style` attribute, when added to a trigger, will style only the tooltip associated with that specific trigger.

```html
<Button data-tooltip="I'm tooltip!" data-tooltip-style="bg-emerald-600 text-emerald-100">Button</Button>
```

Anything else you pass reaches the element itself, so a `title`, a `data-*` attribute or an event handler all work the way they would on a `<div>`. The `id` is the exception: the component sets its own from the id of the element the tooltip describes.

## Accessibility

A tooltip is only useful if it can be reached without a mouse. Here is what the component handles, and what is left to you:

- **Keyboard Navigation** Users can open and close the tooltip using the Space or Enter keys on a focused trigger when `triggerEvent="click"`.

- Pressing Escape closes any open tooltip, whether it is triggered by hover or click.

- The tooltips triggered by hover are also accessible via focus for keyboard users.

- **ARIA Attributes** The tooltip sets these ARIA attributes itself: The tooltip container has `role="tooltip"`.

- If the trigger element has an `id`, the tooltip gets the id `<trigger-id>-tooltip`, and `aria-describedby` is added to the trigger while the tooltip is open. Give your triggers an `id` so screen readers can announce the tooltip text.

- **Focus Management** Focus always stays on the trigger; the tooltip itself does not receive focus.

- The tooltip closes when focus moves away from the trigger, when the user clicks outside of it, or (in click mode) when the trigger is clicked again.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | [Placement](https://www.theui.dev/docs/types#placement) | `top` | Controls where the tooltip appears relative to the trigger element. Can be overridden per trigger with `data-tooltip-position`. |
| `triggerEvent` | 'hover' \| 'click' | `hover` | Determines how the tooltip is triggered, either on hover or click. Can be overridden per trigger with `data-tooltip-event`. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Sets the animation speed for showing and hiding the tooltip. Can be overridden per trigger with `data-tooltip-animation-speed`. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `lg` | Defines the border-radius of the tooltip for corner styling. Can be overridden per trigger with `data-tooltip-rounded`. |
| `gap` | number | `12` | Specifies the spacing (in px) between the tooltip and the trigger element. The minimum is 8. Can be overridden per trigger with `data-tooltip-gap`. |

---

Source: https://www.theui.dev/docs/combobox

# Combobox

The Combobox component is a select box you can type in. It filters as you type, holds one value or many, groups its options, and can fetch them from your server. Use the plain Select when the list is short and needs no search.

## Example

Pass the options as `items` and bind a value. Plain strings are the quickest way to start.

```html
<script>
  import { Combobox } from "theui-svelte";

  const countries = ["Bangladesh", "Brazil", "Canada", "Denmark"]
  let country = $state("Bangladesh")
</script>

<Combobox items={countries} bind:value={country} placeholder="Pick a country">
  Country
</Combobox>
```

## Option Objects

An option can also be an object with a `value`, the text to show, a `disabled` flag and a `group` name. The value is what you get back; the text is what the user reads and searches.

```html
<script>
  const roles = [
    { value: "admin", text: "Administrator", group: "Staff" },
    { value: "editor", text: "Editor", group: "Staff" },
    { value: "member", text: "Member", group: "Public" },
    { value: "guest", text: "Guest", group: "Public", disabled: true },
  ]
</script>

<Combobox items={roles} placeholder="Choose a role">Role</Combobox>
```

## Multiple Selection

Add `multiple` and the value becomes an array. Each choice is shown as a chip with its own remove button, and Backspace in an empty field removes the last one.

```html
<script>
  let frameworks = $state(["Svelte"])
</script>

<Combobox
  items={["Svelte", "React", "Vue", "Solid"]}
  bind:value={frameworks}
  multiple
  placeholder="Pick a few"
>Frameworks</Combobox>
```

## Creating Options

With `creatable`, anything typed that does not match an option can be added as a new one. Use `createText` to reword the entry that offers it.

```html
<Combobox
  items={["Design", "Engineering", "Marketing"]}
  bind:value={tags}
  multiple
  creatable
  createText={(q) => `Add "${q}"`}
>Tags</Combobox>
```

## Async Search

Pass `onsearch` and the component stops filtering on its own: it hands you what was typed and shows whatever `items` you set. Use `loading` while the request is on its way.

```html
<script>
  let items = $state([])
  let loading = $state(false)

  const search = async (query) => {
    if (!query.trim()) { items = []; return }
    loading = true
    items = await fetchCountries(query)
    loading = false
  }
</script>

<Combobox {items} {loading} onsearch={search} placeholder="Search..." emptyText="Nothing found">
  Country
</Combobox>
```

## Custom Options

The `option` snippet takes over how each row is drawn, and is handed the option itself, so a row can hold an avatar, a description or a badge.

```html
<Combobox items={roles} placeholder="Choose a role">
  Rich options
  {#snippet option(item)}
    <Avatar size="xs" name={item.text} />
    <span class="grow">{item.text}</span>
    <span class="text-xs text-muted">{item.group}</span>
  {/snippet}
</Combobox>
```

## Without Search

Set `searchable={false}` to keep the panel and the keyboard but stop the typing, which turns the component into a styled select. `clearable={false}` hides the clear button.

```html
<Combobox items={countries} value="Canada" searchable={false}>Not searchable</Combobox>
<Combobox items={countries} value="Japan" clearable={false}>Cannot be cleared</Combobox>
<Combobox items={countries} value="Kenya" disabled>Disabled</Combobox>
```

## In a Form

Give the component a `name` to submit the value. A multiple combobox submits one field for each choice, the way a multiple select does.

```html
<form method="POST">
  <Combobox items={countries} name="country" value="Brazil">Country</Combobox>
  <button>Save</button>
</form>
```

## Animation Speed

The `animationSpeed` prop sets how quickly the field and its panel react to focus, hover and opening. It takes `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` and `"faster"`, and the default is `"normal"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited, so one setting covers every field at once.

```html
<Combobox items={countries} animationSpeed="slower" placeholder="Slower" />
<Combobox items={countries} animationSpeed="normal" placeholder="Normal" />
<Combobox items={countries} animationSpeed="faster" placeholder="Faster" />
<Combobox items={countries} animationSpeed="none" placeholder="No animation" />
```

## Reset Styles

Set `reset` to `true` to drop the border, background and focus ring of the field and keep only the classes you pass. The chips and the panel keep their layout, so the component still works the same way. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<Combobox
  items={countries}
  reset
  fieldClasses="w-full border-b-2 border-gray-400 px-1 py-2"
  placeholder="Underline only" />
```

## Customization

Sizes and variants come from the [Form](https://www.theui.dev/docs/form) or the [Fieldset](https://www.theui.dev/docs/fieldset), or from the props here. Use `fieldClasses` for the box, `panelClass` for the list, `optionClass` for each row and `chipClasses` for the chips.

```html
<Combobox items={countries} size="lg" variant="flat" placeholder="Flat and large" />
<Combobox items={countries} rounded="full" placeholder="Fully rounded" />
<Combobox items={countries} multiple chipClasses="bg-brand-500 text-on-brand" />
```

## Keyboard

The down arrow opens the list and moves through it, the up arrow moves back, and both wrap around. Enter takes the highlighted option, Escape closes the list and keeps the focus, Home and End jump to the first and last option, and Tab closes the list and moves on. In a multiple combobox, Backspace on an empty field removes the last chip. Disabled options are skipped.

## Accessibility

The component follows the WAI-ARIA combobox pattern. The field is a text input with `role="combobox"` that says whether the list is open and which list it controls; the list is a listbox whose options carry their selected state, and in a multiple combobox the listbox is marked as allowing several. Focus never leaves the input: the highlighted option is pointed at with `aria-activedescendant`, so typing and moving through the list stay in one place. The chips of a multiple combobox each have a remove button named after the option, such as "Remove Svelte", and the clear button has its own name. The list is placed with a fixed strategy, so it flips and shifts to stay on screen instead of being cut off inside a scrolling box.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | [COMBOBOX_ITEM](https://www.theui.dev/docs/types#combobox-item-type)[] | `[]` | The options. Strings and numbers, or objects with value, text, disabled and group. |
| `value` | unknown | `undefined` | The chosen value, or an array of values when multiple is set. Bindable with `bind:value`. |
| `multiple` | boolean | `false` | Lets several options be chosen. Each one is shown as a chip. |
| `searchable` | boolean | `true` | Lets the user type to filter the list. |
| `clearable` | boolean | `true` | Shows a button that clears the choice. |
| `creatable` | boolean | `false` | Offers to add what was typed when it matches no option. |
| `loading` | boolean | `false` | Shows a spinner in the field, for an async search. |
| `placeholder` | string | `` | Text shown while nothing is chosen. |
| `emptyText` | string | `No results` | Text shown when no option matches. |
| `createText` | (query: string) => string | `` (q) => `Create "${q}"` `` | Text of the entry that adds a new option. |
| `filter` | (option: [COMBOBOX_OPTION](https://www.theui.dev/docs/types#combobox-option-type), query: string) => boolean | `text contains the query` | Decides which options match what was typed. |
| `onsearch` | (query: string) => void | `undefined` | Runs with what was typed. When it is set, the component stops filtering and shows the items you pass. |
| `onchange` | (value: unknown) => void | `undefined` | Runs with the new value every time the choice changes. |
| `name` | string | `undefined` | Name of the field. A multiple combobox submits one field for each chosen value. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Size of the field. Inherited from Form or Fieldset. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Style of the field: "bordered" or "flat". Inherited from Form or Fieldset. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the field and the chips. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `fieldClasses` | string | `` | Custom classes for the box that holds the chips and the input. |
| `panelClass` | string | `` | Custom classes for the list panel. |
| `optionClass` | string | `` | Custom classes for every option row. |
| `chipClasses` | string | `` | Custom classes for the chips of a multiple combobox. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes passed to the field, merged with the default classes. |
| `disabled` | Switches the field off. |
| `readonly` | Shows the choice without letting anyone change it. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |
| `option` | Draws one row of the list. It is handed the option, with its value, text, disabled state and group. |

---

Source: https://www.theui.dev/docs/date-picker

# Date Picker

The DatePicker component opens a calendar under the field and gives back the chosen day. The value is a plain YYYY-MM-DD string, so it submits with a form and travels to a server without any date library. The calendar follows the Material style: circular days, a month and year list, and a today and clear action.

## Example

Import the component and bind a string. Click the field to open the calendar.

```html
<script>
  import { DatePicker } from "theui-svelte";
  let date = $state("")
</script>

<DatePicker bind:value={date} placeholder="Pick a date">Birthday</DatePicker>
```

## Limits and Disabled Days

Use `min` and `max`, both ISO dates, to fence the calendar in. For anything else, `disabledDates` is asked about each day and returns `true` for the ones to turn off, such as weekends or days that are already taken.

```html
<DatePicker
  bind:value={meeting}
  min="2026-01-01"
  max="2026-12-31"
  disabledDates={(date) => date.getDay() === 5 || date.getDay() === 6}
>Meeting day</DatePicker>
```

## Locale and First Day

The `locale` prop decides the language of the month and weekday names and how the value is shown, and `firstDayOfWeek` sets which day starts the week, where `0` is Sunday and `1` is Monday. Both use the browser's own date formatting, so nothing extra is loaded.

```html
<DatePicker value="2026-03-14" locale="en-GB" firstDayOfWeek={1} />
<DatePicker value="2026-03-14" locale="de-DE" firstDayOfWeek={1} />
<DatePicker value="2026-03-14" locale="bn-BD" />
```

## Display Format

By default the date is shown in a medium style for the locale. Pass `format` to write it your own way. The value itself never changes, only what is read in the field.

```html
<DatePicker value="2026-03-14" />
<DatePicker value="2026-03-14" format={(d) => d.toLocaleDateString("en-US", {dateStyle: "full"})} />
<DatePicker value="2026-03-14" format={(d) => `${d.getDate()}/${d.getMonth() + 1}/${d.getFullYear()}`} />
```

## Typing a Date

The field is read-only by default, so a tap opens the calendar. Add `editable` to let the date be typed as well. Typing takes the ISO form, `YYYY-MM-DD`, and anything else is put back when the field loses focus.

```html
<DatePicker bind:value={date} editable placeholder="YYYY-MM-DD">Typed date</DatePicker>
```

## Inline Calendar

With `inline` the calendar is always open and there is no field, which suits a booking page or a filter panel.

```html
<DatePicker bind:value={date} inline>Choose a day</DatePicker>
```

## Footer Actions

The calendar has a **Today** button and, once a date is chosen, a **Clear** button. Turn the first off with `showToday={false}` and the second with `clearable={false}`, or rename them with `todayText` and `clearText`.

```html
<DatePicker value="2026-03-14" todayText="Jump to today" clearText="Remove" />
<DatePicker value="2026-03-14" showToday={false} clearable={false} />
```

## In a Form

Give the component a `name` and the ISO value is submitted, which is the form every backend understands. The `onchange` callback runs with the new value.

```html
<form method="POST">
  <DatePicker name="startDate" value="2026-03-14" onchange={(v) => console.log(v)}>
    Start date
  </DatePicker>
  <button>Save</button>
</form>
```

## Animation Speed

The `animationSpeed` prop sets how quickly the field and the calendar react to focus, hover and opening. It takes `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` and `"faster"`, and the default is `"normal"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited, so one setting covers every field at once.

```html
<DatePicker animationSpeed="slower" placeholder="Slower" />
<DatePicker animationSpeed="normal" placeholder="Normal" />
<DatePicker animationSpeed="faster" placeholder="Faster" />
<DatePicker animationSpeed="none" placeholder="No animation" />
```

## Reset Styles

Set `reset` to `true` to drop the border, background and focus ring of the field and keep only the classes you pass. The calendar panel keeps its own styling, so only the closed field changes. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<DatePicker
  reset
  class="w-full border-b-2 border-gray-400 px-1 py-2"
  placeholder="Underline only" />
```

## Customization

Sizes and variants come from the [Form](https://www.theui.dev/docs/form) or the [Fieldset](https://www.theui.dev/docs/fieldset), or from the props here. Use `panelClass` for the calendar, `dayClasses` for every day and `selectedDayClasses` for the chosen one.

```html
<DatePicker value="2026-03-14" size="lg" variant="flat" />
<DatePicker value="2026-03-14" selectedDayClasses="bg-info-500 hover:bg-info-600" />
<DatePicker value="2026-03-14" dayClasses="rounded-lg" />
```

## Keyboard

In the field, the down arrow or Enter opens the calendar. Inside it, the arrow keys move a day at a time, Page Up and Page Down move a month, with Shift a year, Home and End go to the start and end of the week, Enter or Space takes the day, and Escape closes and puts the focus back on the field. Only one day is in the tab order at a time, so Tab leaves the calendar instead of walking through forty-two buttons.

## Accessibility

The calendar is a dialog with a grid inside it, the pattern screen readers know. Each day is a button named in full, such as "Saturday, 14 March 2026", so the number is never read alone; today is marked with `aria-current` and the chosen day with `aria-selected`. The month in view is announced politely as it changes, and days outside the range are disabled rather than hidden. The month and year button opens a list of years and months, so a distant date takes a few clicks instead of many. The panel is positioned with a fixed strategy, so it stays on screen inside scrolling boxes.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `` | The chosen date as "YYYY-MM-DD". Bindable with `bind:value`. |
| `min` | string | `undefined` | Earliest date that can be chosen, as "YYYY-MM-DD". |
| `max` | string | `undefined` | Latest date that can be chosen, as "YYYY-MM-DD". |
| `disabledDates` | (date: Date) => boolean | `undefined` | Asked about every day in the calendar. Return true to turn that day off. |
| `firstDayOfWeek` | number | `0` | Day the week starts on, where 0 is Sunday and 1 is Monday. |
| `locale` | string | `undefined` | Language of the month and weekday names, and of the shown value. Defaults to the browser's own. |
| `format` | (date: Date) => string | `medium date of the locale` | Turns the chosen date into the text shown in the field. |
| `editable` | boolean | `false` | Lets the date be typed into the field, in the ISO form "YYYY-MM-DD". |
| `inline` | boolean | `false` | Shows the calendar in the page instead of in a popup. |
| `clearable` | boolean | `true` | Shows the clear button in the field and in the calendar footer. |
| `showToday` | boolean | `true` | Shows the today button in the calendar footer. |
| `todayText` | string | `Today` | Text of the today button. |
| `clearText` | string | `Clear` | Text of the clear button in the footer. |
| `openLabel` | string | `Choose date` | Accessible name of the calendar button and of the calendar itself. |
| `placeholder` | string | `` | Placeholder of the field while no date is picked. |
| `onchange` | (value: string) => void | `undefined` | Runs with the new value every time the date changes. |
| `name` | string | `undefined` | Name of the field, so the ISO value is submitted with the form. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Size of the field. Inherited from Form or Fieldset. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Style of the field: "bordered" or "flat". Inherited from Form or Fieldset. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the field. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `panelClass` | string | `` | Custom classes for the calendar panel. |
| `dayClasses` | string | `` | Custom classes for every day in the grid. |
| `selectedDayClasses` | string | `` | Custom classes added to the chosen day. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes passed to the field, merged with the default classes. |
| `disabled` | Switches the field off, so the calendar cannot be opened. |
| `readonly` | Shows the date without letting anyone change it. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |

---

Source: https://www.theui.dev/docs/file-dropzone

# File Dropzone

The FileDropzone component takes files by drag and drop or by clicking to browse. It checks the type, the size and the number of files, shows what was chosen with image previews, and lets each file be removed again. Underneath it is a real file input, so it submits with the form and works from the keyboard.

## Example

Import the component and bind `files`. Drop a file on the box, or click it to open the file browser.

```html
<script>
  import { FileDropzone } from "theui-svelte";
  let files = $state<FileList>()
</script>

<FileDropzone bind:files>Attachment</FileDropzone>
```

## Multiple Files

Add `multiple` to accept more than one file, and `maxFiles` to set a ceiling. New files are added to the ones already chosen, so a second drop does not throw the first away.

```html
<FileDropzone multiple maxFiles={4} text="Drop up to four files" />
```

## Type and Size

Use `accept` exactly as on a file input, with extensions such as `.pdf` or types such as `image/*`, and `maxSize` in bytes. Files that do not pass are handed to `onreject`, each with the reason: `type`, `size` or `count`.

These checks run in the browser, where anyone can work around them, and the type comes from the file name and what the browser reports. They are there to spare your visitors a pointless upload, not to keep bad files out. Check the type, the size and the number of files again on your server before you store anything.

```html
<FileDropzone
  accept=".pdf,.doc,.docx"
  maxSize={2 * 1024 * 1024}
  hint="PDF or Word, up to 2 MB"
  onreject={(rejections) => {
    // [{ file, reason: "type" | "size" | "count" }]
    console.log(rejections)
  }}
>Resume</FileDropzone>
```

## Image Previews

Images are shown as thumbnails in the list below the box. Set `preview={false}` to list the names only, or `showList={false}` to hide the list and show the files yourself.

```html
<FileDropzone multiple accept="image/*" text="Drop a few pictures" hint="Images only" />

<!-- Names only -->
<FileDropzone multiple preview={false} />

<!-- No list at all -->
<FileDropzone multiple showList={false} bind:files />
```

## Text and Hint

The `text` prop is the line inside the box and `hint` is the smaller line under it. Use the hint to say what is allowed, so the rule is known before a file is picked.

```html
<FileDropzone
  text="Drag your logo here, or click to browse"
  hint="SVG or PNG, at most 500 KB"
  accept=".svg,.png"
  maxSize={500 * 1024}
/>
```

## Custom Content

The `content` snippet replaces everything inside the box, so you can use your own icon and wording.

```html
<FileDropzone multiple dropzoneClasses="py-10">
  {#snippet content()}
    <Svg size={2} class="text-brand-500">
      <path d="..."/>
    </Svg>
    <span class="font-semibold">Drop your files</span>
    <span class="text-sm text-muted">or click anywhere in this box</span>
  {/snippet}
</FileDropzone>
```

## Reacting to Files

The `onselect` callback runs with the files that were accepted, which is the place to start an upload. Everything that was turned away goes to `onreject` instead.

```html
<FileDropzone
  multiple
  onselect={(files) => upload(files)}
  onreject={(rejections) => showErrors(rejections)}
>Upload</FileDropzone>
```

## Disabled

A `disabled` dropzone takes nothing, by drop or by click, and its list loses the remove buttons.

```html
<FileDropzone disabled text="Uploading is off right now" />
```

## Sizes

The `size` prop sets how tall the drop area is and how large the text inside it reads. It takes `"sm"`, `"md"`, `"lg"` and `"xl"`, and the default is `"md"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited.

```html
<FileDropzone size="sm" text="Small" />
<FileDropzone size="md" text="Medium" />
<FileDropzone size="lg" text="Large" />
<FileDropzone size="xl" text="Extra large" />
```

## Reset Styles

Set `reset` to `true` to drop the dashed border, the hover and the drag highlight and keep only the classes you pass in `dropzoneClasses`. The drop area keeps its layout and its size, so dropping, clicking and the file list all still work. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<FileDropzone
  reset
  dropzoneClasses="rounded-xl bg-secondary shadow-sm"
  text="Drop a file here" />
```

## Customization

Use `dropzoneClasses` for the box, `listClasses` for the list of chosen files and `wrapperClasses` for the whole field.

```html
<FileDropzone dropzoneClasses="border-brand-500 bg-brand-500/5" text="Brand coloured" />
<FileDropzone dropzoneClasses="border-solid border-2 py-10" rounded="2xl" text="Solid border" />
```

## Accessibility

Drag and drop is never the only way in: the box is a label tied to a real file input, so Tab reaches it, Enter and Space open the file browser, and the same focus ring appears as on any other field. The list of chosen files is a plain list with a named remove button for each file, such as "Remove report.pdf", and each row shows the file size in readable units. Say what is allowed in the `hint` or `helperText`, and report what was turned away in your own text through `onreject`, so the reason is not carried by colour alone.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `files` | FileList | `undefined` | The chosen files. Bindable with `bind:files`. |
| `multiple` | boolean | `false` | Accepts more than one file. New files are added to the ones already chosen. |
| `accept` | string | `undefined` | Allowed file types, such as ".pdf,.docx" or "image/*". Anything else is rejected with the reason "type". |
| `maxSize` | number | `undefined` | Largest size of one file, in bytes. A bigger file is rejected with the reason "size". |
| `maxFiles` | number | `undefined` | How many files may be kept. Files over the limit are rejected with the reason "count". |
| `preview` | boolean | `true` | Shows a thumbnail of every image in the list. |
| `showList` | boolean | `true` | Shows the list of chosen files with their size and a remove button. |
| `text` | string | `Drop files here or click to browse` | Main line inside the box. |
| `hint` | string | `undefined` | Smaller line under the main text, for the rules such as allowed types and size. |
| `onselect` | (files: File[]) => void | `undefined` | Runs with the files that were accepted. |
| `onreject` | (rejections: [DROPZONE_REJECTION](https://www.theui.dev/docs/types#dropzone-rejection-type)[]) => void | `undefined` | Runs with the files that were turned away, each with its reason: "type", "size" or "count". |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form, or "md` | Sets the size of the component. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the box and the list rows. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `dropzoneClasses` | string | `` | Custom classes for the drop box. |
| `listClasses` | string | `` | Custom classes for the list of chosen files. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes passed to the file input. |
| `disabled` | Turns the dropzone off, for dropping and for clicking. |
| `name` | Name of the field, so the files are submitted with the form. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |
| `content` | Replaces the icon and text inside the drop box. |

---

Source: https://www.theui.dev/docs/form-wizard

# Form Wizard

The FormWizard component turns one long form into a few short steps. It draws the numbered progress across the top, moves between steps with Back and Next, and checks the fields of a step before it lets the user move on. Every step stays in the page, so nothing typed is ever lost.

## Example

Import both components and put a `FormStep` for each step inside the `FormWizard`. Give every step a `title`, which is the text under its number.

```html
<script>
  import { FormWizard, FormStep } from "theui-svelte";
</script>

<FormWizard>
  <FormStep title="Account">...</FormStep>
  <FormStep title="Profile">...</FormStep>
  <FormStep title="Done">...</FormStep>
</FormWizard>
```

## With a Form

Put the wizard inside a [Form](https://www.theui.dev/docs/form) and use the fields you already know. Before it moves on, the wizard checks the HTML validation of the fields in the current step, so `required`, `type="email"` and the rest are enough for most cases. Try pressing Next with the field empty.

```html
<script>
  let step = $state(1)
</script>

<Form method="POST">
  <FormWizard bind:step onfinish={() => save()}>
    <FormStep title="Account" description="How you sign in">
      <Input name="email" type="email" required>Email</Input>
    </FormStep>
    <FormStep title="Profile" description="About you">
      <Input name="fullName" required>Full name</Input>
    </FormStep>
    <FormStep title="Done">Everything is ready.</FormStep>
  </FormWizard>
</Form>
```

## Step Validation

A step can also check itself with its own `validate` function. Return `false` to keep the user where they are, or `true` to let them through. The function may be async, so a check on your server works too.

```html
<script>
  let accepted = $state(false)
</script>

<FormWizard>
  <FormStep title="Terms" validate={() => accepted}>
    <Checkbox bind:checked={accepted}>I accept the terms</Checkbox>
  </FormStep>
  <FormStep title="Welcome">Thank you.</FormStep>
</FormWizard>

<!-- An async check works as well -->
<FormStep title="Username" validate={async () => await isFree(username)}>...</FormStep>
```

## Vertical Steps

Set `orientation="vertical"` to put the steps down the side. On a narrow screen they stack above the content by themselves.

```html
<FormWizard orientation="vertical">
  <FormStep title="Pick a plan" description="Monthly or yearly">...</FormStep>
  <FormStep title="Payment" description="Card details">...</FormStep>
  <FormStep title="Review">...</FormStep>
</FormWizard>
```

## Free Movement

By default the wizard is linear: a step opens only once the ones before it are done. Pass `linear={false}` to let the user jump to any step from the numbers at the top, which suits a form they are coming back to.

```html
<FormWizard linear={false} step={2}>
  <FormStep title="One">...</FormStep>
  <FormStep title="Two">...</FormStep>
  <FormStep title="Three" optional>...</FormStep>
</FormWizard>
```

## Your Own Controls

Turn the built-in buttons off with `controls={false}`, or the numbers at the top off with `header={false}`, and drive the wizard through `bind:step`. The button labels can be reworded with `backText`, `nextText` and `finishText`.

```html
<script>
  let step = $state(1)
</script>

<FormWizard bind:step controls={false}>
  <FormStep title="First">...</FormStep>
  <FormStep title="Second">...</FormStep>
</FormWizard>

<button onclick={() => step--}>Previous</button>
<button onclick={() => step++}>Continue</button>

<!-- Or keep the buttons and rename them -->
<FormWizard backText="Go back" nextText="Continue" finishText="Create account">...</FormWizard>
```

## Customization

Use `headerClasses` for the row of steps, `indicatorClasses` for every number, and `activeIndicatorClasses` and `completeIndicatorClasses` for the current and the finished ones. `stepClasses` reaches every step, and `controlsClasses` and `buttonClasses` style the buttons.

```html
<FormWizard
  indicatorClasses="rounded-lg"
  activeIndicatorClasses="ring-4 ring-brand-500/20"
  completeIndicatorClasses="bg-success-500 border-success-500"
  buttonClasses="rounded-full px-6"
>
  ...
</FormWizard>
```

## Accessibility

The steps are an ordered list, so a screen reader hears how many there are and which one is current, marked with `aria-current="step"`. A finished step says so in its name, and a step that cannot be reached yet is a disabled button rather than a silent one. Each step is a group named by its title, and moving to a step puts focus on it, so the reading position follows the visible one. Steps that are not shown stay in the page but are hidden and made inert, which keeps their values and keeps them out of the tab order. When a field fails its check, the browser's own message is shown on that field and the wizard stays where it is.

## Configuration

### FormWizard

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `step` | number | `1` | The current step, starting from 1. Bindable with `bind:step`. |
| `orientation` | "horizontal" \| "vertical" | `horizontal` | Puts the steps across the top or down the side. A vertical header stacks on a narrow screen. |
| `header` | boolean | `true` | Shows the numbered steps. |
| `controls` | boolean | `true` | Shows the Back and Next buttons. |
| `linear` | boolean | `true` | A step can only be opened once the steps before it are done. With false, any step can be clicked. |
| `backText` | string | `Back` | Text of the back button. |
| `nextText` | string | `Next` | Text of the next button. |
| `finishText` | string | `Finish` | Text of the next button on the last step. |
| `ariaLabel` | string | `Steps` | Accessible name of the list of steps. |
| `onchange` | (step: number) => void | `undefined` | Runs with the new step number every time the step changes. |
| `onfinish` | () => void | `undefined` | Runs when the button is pressed on the last step and its checks pass. |
| `headerClasses` | string | `` | Custom classes for the list of steps. |
| `indicatorClasses` | string | `` | Custom classes for every step number. |
| `activeIndicatorClasses` | string | `` | Custom classes added to the number of the current step. |
| `completeIndicatorClasses` | string | `` | Custom classes added to the number of a finished step. |
| `stepClasses` | string | `` | Custom classes for every step. |
| `controlsClasses` | string | `` | Custom classes for the row of buttons. |
| `buttonClasses` | string | `` | Custom classes for the back and next buttons. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the wizard element, merged with the default classes. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | The FormStep components. |

### FormStep

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string | `undefined` | Name of the step, shown under its number and used as the accessible name of the step. |
| `description` | string | `undefined` | Smaller text under the title. |
| `optional` | boolean | `false` | Marks the step as optional in the header. |
| `validate` | () => boolean \| Promise<boolean> | `undefined` | Runs before the wizard moves on. Return false to stay on this step. It may be async. |

#### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the step, merged with the default classes and stepClasses. |

#### Snippets

| Name | Description |
| --- | --- |
| `children` | Content of the step, usually the form fields. |

---

Source: https://www.theui.dev/docs/otp-input

# OTP Input

The OtpInput component collects a one time code, the kind sent by SMS or made by an authenticator app. Each character has its own box, typing moves forward by itself, and pasting a whole code fills every box at once.

## Example

Import the component and bind a string. The value is the code as one piece of text, so you can send it straight to your server.

```html
<script>
  import { OtpInput } from "theui-svelte";
  let code = $state("")
</script>

<OtpInput bind:value={code}>Verification code</OtpInput>
```

## Length

The `length` prop sets how many boxes there are. The default is `6`.

```html
<OtpInput length={4} />
<OtpInput length={8} />
```

## Types

The `type` prop decides what may be typed: `number` (default) takes digits only and opens the number keypad on a phone, `text` takes letters and digits, and `password` hides what has been typed.

```html
<OtpInput type="number" length={4} />
<OtpInput type="text" length={4} />
<OtpInput type="password" length={4} />
```

## Separator

Use `separatorAfter` to break a long code into two halves, the way printed codes are grouped.

```html
<OtpInput length={6} separatorAfter={3} />
```

## On Complete

The `oncomplete` callback runs as soon as the last box is filled, which is the moment to check the code without making the user press a button.

```html
<OtpInput length={4} oncomplete={(value) => verify(value)}>
  Enter the code
</OtpInput>
```

## Sizes and Variants

Sizes run from `sm` to `xl`, and the `variant` can be `bordered` or `flat`. Both are inherited from a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset).

```html
<OtpInput length={4} size="sm" />
<OtpInput length={4} size="lg" />
<OtpInput length={4} variant="flat" />
<OtpInput length={4} rounded="full" />
```

## In a Form

Give the component a `name` and the whole code is submitted as one field, not as six. Add `autofocus` when the code is the only thing on the page.

```html
<form method="POST">
  <OtpInput name="otp" length={6} helperText="We sent a code to your phone">
    One time code
  </OtpInput>
  <button>Verify</button>
</form>
```

## Animation Speed

The `animationSpeed` prop sets how quickly each box reacts to focus and hover. It takes `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` and `"faster"`, and the default is `"normal"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited, so one setting covers every field at once.

```html
<OtpInput animationSpeed="slower">Slower</OtpInput>
<OtpInput animationSpeed="faster">Faster</OtpInput>
<OtpInput animationSpeed="none">No animation</OtpInput>
```

## Reset Styles

Set `reset` to `true` to drop the border, background and focus ring of every box and keep only the classes you pass. The boxes stay in a row and keep their width, so paste and the arrow keys are unaffected. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<OtpInput reset boxClasses="border-0 border-b-2 border-gray-400">
  Underline only
</OtpInput>
```

## Customization

Use `boxClasses` for the boxes themselves, and `placeholder` to show a character in the empty ones.

```html
<OtpInput length={4} placeholder="•" />
<OtpInput length={4} boxClasses="w-12 text-xl font-semibold" />
<OtpInput length={4} variant="flat" boxClasses="border-b-4 text-2xl" />
```

## Keyboard and Paste

Typing a character moves to the next box. Backspace clears the box, or steps back and clears the one before when the box is already empty. The left and right arrows move between boxes, Home and End jump to the first and last, and Delete clears without moving. Pasting a code anywhere in the row fills the boxes from that point on, so a copied code never has to be typed.

## Accessibility

Every box is a real input with its own name, such as "Character 3 of 6", which you can reword with the `boxLabel` prop. The row is a group, so a screen reader user hears the label of the field before the boxes. The first box carries `autocomplete="one-time-code"`, which lets phones offer the code from an SMS, and the number type opens the numeric keypad. When you pass a `name`, the code is submitted once as a whole rather than as separate characters.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `` | The code as one string. Bindable with `bind:value`. |
| `length` | number | `6` | Number of boxes. |
| `type` | [OTP_TYPE](https://www.theui.dev/docs/types#otp-type) | `number` | What may be typed: "number" for digits, "text" for letters and digits, or "password" to hide the characters. |
| `separatorAfter` | number | `undefined` | Draws a separator after this many boxes, to group a long code. |
| `autofocus` | boolean | `false` | Puts the cursor in the first box when the page loads. |
| `placeholder` | string | `` | Character shown in an empty box. |
| `oncomplete` | (value: string) => void | `undefined` | Runs with the full code as soon as the last box is filled. |
| `boxLabel` | (index: number, length: number) => string | `` (i, n) => `Character ${i + 1} of ${n}` `` | Builds the accessible name of each box. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Size of the boxes. Inherited from Form or Fieldset. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Style of the boxes: "bordered" or "flat". Inherited from Form or Fieldset. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the boxes. |
| `name` | string | `undefined` | Name of the field. The whole code is submitted as one value. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the boxes for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `boxClasses` | string | `` | Custom classes for every box. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes passed to every box, merged with the default classes. |
| `disabled` | Switches every box off. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |

---

Source: https://www.theui.dev/docs/range

# Range

The Range component lets the user choose a number by dragging a handle. It is a native range input underneath, so the keyboard, touch and screen readers all work, while the track, the handle and the value bubble follow your theme.

## Example

Import the component, bind a number and give it a label as the child. The track fills up to the value as it moves.

```html
<script>
  import { Range } from "theui-svelte";
  let volume = $state(40)
</script>

<Range bind:value={volume}>Volume</Range>
```

## Min, Max and Step

Use `min`, `max` and `step` the way you would on a native input. The default range is `0` to `100` in steps of `1`.

```html
<Range value={30} min={0} max={100} step={10}>Steps of 10</Range>
<Range bind:value={temperature} min={10} max={30} step={0.5}>Half degrees</Range>
```

## Showing the Value

Set `showValue` to put the number beside the slider, or `showValue="tooltip"` to float it above the handle as it moves.

```html
<Range bind:value={volume} showValue>Inline value</Range>
<Range bind:value={volume} showValue="tooltip">Value bubble</Range>
```

## Formatting

The `format` prop turns the number into the text that is shown, for money, units or anything else. It is used by the inline value, the bubble and the text read out to screen readers.

```html
<Range bind:value={budget} min={0} max={1000} step={10} showValue="tooltip" format={(v) => `$${v}`}>
  Budget
</Range>

<Range bind:value={temperature} min={10} max={30} step={0.5} showValue format={(v) => `${v} °C`}>
  Temperature
</Range>
```

## Ticks

Pass `ticks` to mark places along the track. Give it plain numbers, or objects with your own text.

```html
<Range bind:value={temperature} min={10} max={30} ticks={[10, 15, 20, 25, 30]}>Numbers</Range>

<Range
  value={2}
  min={1}
  max={4}
  ticks={[
    {value: 1, label: "Low"},
    {value: 2, label: "Fair"},
    {value: 3, label: "Good"},
    {value: 4, label: "Best"}
  ]}
>Labels</Range>
```

## Sizes

The `size` prop takes `sm`, `md`, `lg` and `xl`, changing the thickness of the track and the size of the handle. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the size is inherited, so you set it once.

```html
<Range value={40} size="sm" />
<Range value={40} size="md" />
<Range value={40} size="lg" />
<Range value={40} size="xl" />
```

## Helper Text and Disabled

Add `helperText` to explain the field, and `disabled` to switch it off. The helper text is linked to the input, so screen readers read it with the label.

```html
<Range value={60} helperText="Drag, or use the arrow keys">Quality</Range>
<Range value={60} disabled>Disabled</Range>
```

## Reset Styles

Set `reset` to `true` to drop the custom track and thumb and hand the control back to the browser, so the slider is drawn the way the operating system draws it. Anything you pass in `rangeClasses` still applies, and the size variables stay, so the label and the helper text are unchanged. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<Range reset rangeClasses="w-full accent-brand-500">Native slider</Range>
```

## Customization

The colour of the filled track and the handle follows the text colour, so a single class recolours both. Use `rangeClasses` for the input itself and `wrapperClasses` for the field around it.

```html
<Range value={40} class="text-info-500" />
<Range value={60} class="text-success-500" size="lg" />
<Range value={80} class="text-error-500" size="xl" showValue />
```

## Accessibility

The component is a native `<input type="range">`, so the browser gives it the slider role, the minimum, maximum and current value, and the usual keys: the arrows move by one step, Page Up and Page Down move in bigger jumps, and Home and End go to the ends. The label you pass is tied to the input, and `helperText` is linked with `aria-describedby`. Where the number needs words, such as a price or a temperature, the `format` function is used for the spoken value as well. The fill direction follows the page, so a right to left page fills from the right.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | `0` | The chosen number. Bindable with `bind:value`. |
| `min` | number | `0` | Lowest value of the range. |
| `max` | number | `100` | Highest value of the range. |
| `step` | number | `1` | How far the value moves at a time. |
| `showValue` | boolean \| "inline" \| "tooltip" | `false` | Shows the value beside the slider, or in a bubble over the handle with "tooltip". |
| `format` | (value: number) => string | `(v) => String(v)` | Turns the number into the text shown, and into the value read by screen readers. |
| `ticks` | [RANGE_TICK](https://www.theui.dev/docs/types#range-tick-type)[] | `undefined` | Marks under the track. Numbers, or objects with a value and a label. |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Thickness of the track and size of the handle. Inherited from Form or Fieldset. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `rangeClasses` | string | `` | Custom classes for the range input itself. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the range input, merged with the default classes. The filled track and the handle follow the text colour. |
| `disabled` | Switches the field off. |
| `name` | Name of the field, so the value is submitted with the form. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |

---

Source: https://www.theui.dev/docs/stepper

# Stepper

The Stepper component is a number field with a minus and a plus button on either side. Use it for quantities, counts and small amounts, where clicking is faster than typing. For a wide range of values where the exact number matters less, use the Range component instead.

## Example

Import the component and bind a number. The buttons step the value, and the field can still be typed into.

```html
<script>
  import { Stepper } from "theui-svelte";
  let quantity = $state(1)
</script>

<Stepper bind:value={quantity}>Quantity</Stepper>
```

## Limits

Set `min` and `max` to fence the value in. The matching button turns itself off at each end, and a number typed outside the range is pulled back when the field loses focus.

```html
<Stepper value={1} min={1} max={5} helperText="Between 1 and 5">Tickets</Stepper>
```

## Decimal Steps

The `step` prop can be a fraction. The component keeps the result clean, so half steps give `1.5` rather than `1.5000000000000002`.

```html
<script>
  let weight = $state(0.5)
</script>

<Stepper bind:value={weight} min={0} max={5} step={0.5}>Weight (kg)</Stepper>
```

## Sizes and Variants

The `size` prop takes `sm`, `md`, `lg` and `xl`, and `variant` takes `bordered` or `flat`. Both are inherited from a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset).

```html
<Stepper value={2} size="sm" />
<Stepper value={2} size="md" />
<Stepper value={2} size="lg" />
<Stepper value={2} variant="flat" />
```

## Disabled and Read Only

A `disabled` stepper is switched off completely. A `readonly` one shows its value but cannot be changed, and still submits with the form.

```html
<Stepper value={2} disabled>Disabled</Stepper>
<Stepper value={2} readonly>Read only</Stepper>
```

## In a Form

Give the field a `name` to submit it, and use `onchange` to react to every change, such as updating a price.

```html
<form method="POST">
  <Stepper name="quantity" bind:value={quantity} min={1} max={10} onchange={(v) => console.log(v)}>
    Quantity
  </Stepper>
  <button>Add to cart</button>
</form>
```

## Animation Speed

The `animationSpeed` prop sets how quickly the field reacts to focus and hover. It takes `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` and `"faster"`, and the default is `"normal"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited, so one setting covers every field at once.

```html
<Stepper animationSpeed="slower">Slower</Stepper>
<Stepper animationSpeed="faster">Faster</Stepper>
<Stepper animationSpeed="none">No animation</Stepper>
```

## Reset Styles

Set `reset` to `true` to drop the border, background and focus ring of the number field and keep only the classes you pass. The two buttons keep their own styling, which `buttonClasses` replaces. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<Stepper
  reset
  class="w-20 border-0 border-b-2 border-gray-400 text-center"
  buttonClasses="border-0 bg-transparent text-xl">
  Underline only
</Stepper>
```

## Customization

Use `buttonClasses` for the minus and plus buttons, `class` for the field itself and `wrapperClasses` for everything together. The button labels can be reworded with `decreaseLabel` and `increaseLabel`.

```html
<Stepper
  value={2}
  rounded="full"
  buttonClasses="rounded-full bg-brand-500 text-on-brand border-transparent"
  class="w-24"
/>

<Stepper value={2} decreaseLabel="One fewer" increaseLabel="One more" />
```

## Accessibility

The field is a native number input, so screen readers announce it as a spin button with its value and limits, and the arrow keys step it. The two buttons have their own names, set with `decreaseLabel` and `increaseLabel`, and point at the field with `aria-controls`. They are real buttons of type `button`, so they never submit the form around them. Holding one down keeps stepping after a short pause, which saves many clicks without making a single click hard to aim.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | `0` | The number in the field. Bindable with `bind:value`. |
| `min` | number | `-Infinity` | Lowest value. The minus button turns off when it is reached. |
| `max` | number | `Infinity` | Highest value. The plus button turns off when it is reached. |
| `step` | number | `1` | How far the value moves at a time. Fractions such as 0.5 stay exact. |
| `decreaseLabel` | string | `Decrease` | Accessible name of the minus button. |
| `increaseLabel` | string | `Increase` | Accessible name of the plus button. |
| `onchange` | (value: number) => void | `undefined` | Runs with the new number every time it changes. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Size of the field and the buttons. Inherited from Form or Fieldset. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Style of the field: "bordered" or "flat". Inherited from Form or Fieldset. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the field and the buttons. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the input for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `buttonClasses` | string | `` | Custom classes for the minus and plus buttons. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the number field, merged with the default classes. |
| `disabled` | Switches the field and both buttons off. |
| `readonly` | Shows the value without letting anyone change it. |
| `name` | Name of the field, so the value is submitted with the form. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |

---

Source: https://www.theui.dev/docs/time-picker

# Time Picker

The TimePicker component holds the hour, the minute and, in twelve hour mode, AM or PM in separate parts. There is no dropdown to scroll: type the digits, step with the arrow keys or the wheel, and move on. The value is a plain HH:mm string in twenty four hour form, whatever the field shows.

## Example

Import the component and bind a string. Click a part and type, or use the up and down arrows.

```html
<script>
  import { TimePicker } from "theui-svelte";
  let start = $state("09:30")
</script>

<TimePicker bind:value={start}>Start</TimePicker>
```

## Twelve Hour

Add `hour12` for a third part with AM and PM. Press **A** or **P** to set it, or Space to flip it. The value stays in twenty four hour form, so `2:30 PM` is still `"14:30"`.

```html
<TimePicker bind:value={end} hour12>End</TimePicker>

<!-- Rename AM and PM for another language -->
<TimePicker hour12 amLabel="প্রা" pmLabel="অপ" />
```

## Limits and Step

Use `min` and `max`, both `"HH:mm"`, to keep the time inside office hours or any other window; a time outside them is pulled back. The `step` prop is how many minutes the minute part moves at a time.

```html
<TimePicker value="09:00" min="09:00" max="17:00">Office hours</TimePicker>
<TimePicker value="10:15" step={15}>Quarter hours</TimePicker>
```

## Stepper Buttons

Small up and down buttons sit at the end of the field and act on whichever part has focus, or on the minutes when none does. Pass `stepper={false}` to replace them with a clock icon.

```html
<TimePicker value="08:00">With buttons</TimePicker>
<TimePicker value="08:00" stepper={false}>With a clock icon</TimePicker>
```

## Sizes and Variants

The `size` and `variant` props work as on every other field, and are inherited from a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset).

```html
<TimePicker value="07:05" size="sm" />
<TimePicker value="07:05" size="lg" />
<TimePicker value="07:05" variant="flat" />
<TimePicker value="07:05" rounded="full" />
<TimePicker value="07:05" disabled>Disabled</TimePicker>
```

## In a Form

Give the component a `name` and the `"HH:mm"` value is submitted, the same form a native time input sends. The `onchange` callback runs with every change.

```html
<form method="POST">
  <TimePicker name="startTime" value="09:30" hour12 onchange={(v) => console.log(v)}>
    Start time
  </TimePicker>
  <button>Save</button>
</form>
```

## Animation Speed

The `animationSpeed` prop sets how quickly the field reacts to focus and hover. It takes `"none"`, `"slower"`, `"slow"`, `"normal"`, `"fast"` and `"faster"`, and the default is `"normal"`. Inside a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) the value is inherited, so one setting covers every field at once.

```html
<TimePicker animationSpeed="slower">Slower</TimePicker>
<TimePicker animationSpeed="normal">Normal</TimePicker>
<TimePicker animationSpeed="faster">Faster</TimePicker>
<TimePicker animationSpeed="none">No animation</TimePicker>
```

## Reset Styles

Set `reset` to `true` to drop the border, background and focus ring and keep only the classes you pass. The hour, minute and meridiem parts keep their layout, so typing and the arrow keys are unaffected. The default is `false`, and a [Form](https://www.theui.dev/docs/form) or a [Fieldset](https://www.theui.dev/docs/fieldset) can set it for every field it holds.

```html
<TimePicker reset class="w-full border-b-2 border-gray-400 px-1 py-2">
  Underline only
</TimePicker>
```

## Customization

Use `segmentClasses` for the hour, minute and AM/PM parts, `class` for the field itself and `wrapperClasses` for the whole thing.

```html
<TimePicker value="09:30" segmentClasses="text-lg font-semibold" />
<TimePicker value="09:30" hour12 segmentClasses="focus:bg-info-500" class="w-48" />
```

## Keyboard and Wheel

Typing digits fills the part you are in and moves on as soon as nothing more can fit, so `9` in the hour jumps straight to the minutes while `1` waits in case you mean `12`. The up and down arrows step the value and wrap around, and stepping the hour past eleven flips AM to PM. The left and right arrows move between parts, and so does the colon key. Home and End go to the lowest and highest value, and Backspace or Delete empties the part. The wheel steps the part that has focus, so the page still scrolls everywhere else. Pasting `14:30` or `2:30 pm` anywhere in the field fills it.

## Accessibility

Each part is a spin button with its own name, its value and its lowest and highest value, which is what a native time field does, so a screen reader says "Hour, 9" and reads the new number as it changes. The parts sit in a group named by the label, and an empty part is read as "Empty" rather than as the two dashes on screen. The stepper buttons are named Increase and Decrease and are left out of the tab order, since the arrow keys already do the same thing from the keyboard. The value is always kept in twenty four hour form, so what is sent does not depend on what is shown.

## Configuration

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | `` | The chosen time as "HH:mm" in twenty four hour form, whatever the field shows. Bindable with `bind:value`. |
| `min` | string | `00:00` | Earliest time that can be chosen, as "HH:mm". |
| `max` | string | `23:59` | Latest time that can be chosen, as "HH:mm". |
| `step` | number | `1` | How many minutes the minute part moves at a time. |
| `hour12` | boolean | `false` | Shows the hour from 1 to 12 with an AM and PM part. |
| `amLabel` | string | `AM` | Text of the morning half, for another language. |
| `pmLabel` | string | `PM` | Text of the afternoon half, for another language. |
| `stepper` | boolean | `true` | Shows the small up and down buttons. They act on the part that has focus, or on the minutes. |
| `clearable` | boolean | `true` | Shows a button that empties the field once a time is set. |
| `onchange` | (value: string) => void | `undefined` | Runs with the new value every time the time changes. |
| `name` | string | `undefined` | Name of the field, so the "HH:mm" value is submitted with the form. |
| `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `md` | Size of the field. Inherited from Form or Fieldset. |
| `variant` | [INPUT_VARIANT](https://www.theui.dev/docs/types#input-variant-type) | `bordered` | Style of the field: "bordered" or "flat". Inherited from Form or Fieldset. |
| `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form, or "normal` | Defines the animation speed for transitions. Available options: "none", "slower", "slow", "normal", "fast", "faster". |
| `reset` | boolean | `Inherited from Fieldset or Form, or false` | Resets all default styles and applies only custom styles. |
| `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Defines the border radius of the field. |
| `helperText` | string \| Snippet | `undefined` | Text under the field, linked to the group for screen readers. |
| `labelClasses` | string | `` | Custom classes for the label. |
| `wrapperClasses` | string | `` | Custom classes for the field wrapper. |
| `segmentClasses` | string | `` | Custom classes for the hour, minute and AM/PM parts. |

### Dynamic props

| Name | Description |
| --- | --- |
| `class` | Classes for the field, merged with the default classes. |
| `disabled` | Switches every part off. |
| `readonly` | Shows the time without letting anyone change it. |

### Snippets

| Name | Description |
| --- | --- |
| `children` | Label of the field. |