# TheUI Svelte

> 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.

## 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.

## Guides

- [Accessibility Guide](https://www.theui.dev/docs/accessibility.md): What theui-svelte handles for accessibility, what you still have to do, and the keys every component answers to.
- [AI Coding Assistants](https://www.theui.dev/docs/ai-assistants.md): Set up Claude Code, Codex, Cursor, GitHub Copilot, VS Code or any other coding agent so it writes correct theui-svelte components the first time.
- [CLI](https://www.theui.dev/docs/cli.md): The theui command line tool. One command points your coding agent at the library's rules, plus the options, the files it writes and how to undo it.
- [Colors](https://www.theui.dev/docs/colors.md): Customize your app's look using theui-svelte's Colors and Branding guide to apply brand colors easily.
- [Global Defaults](https://www.theui.dev/docs/global-defaults.md): Set the corner radius, animation speed, shadow and reset for every theui-svelte component from one place with setTheuiDefaults.
- [Installation Guide](https://www.theui.dev/docs/installation.md): Step by step instructions for installing the theui-svelte component library.
- [Introduction](https://www.theui.dev/docs/introduction.md): Get started quickly with theui-svelte. Learn how to set up and integrate the component library in your SvelteKit projects.
- [License](https://www.theui.dev/docs/license.md): Review licensing terms for TheUI-Svelte, including usage and distribution rules.
- [RTL Support Guide](https://www.theui.dev/docs/rtl.md): Right to left support, applied across the whole site or to single components.
- [Type Definition](https://www.theui.dev/docs/types.md): Every TypeScript type theui-svelte exports, in alphabetical order, with what it is for and which components use it.
- [Z-index Guide](https://www.theui.dev/docs/z-index.md): The stacking order theui-svelte uses, how stacking contexts change it, and where to put your own overlays.

## Components

- [Accordion](https://www.theui.dev/docs/accordion.md): A flexible and accessible accordion component for Svelte apps using theui-svelte.
- [Alert](https://www.theui.dev/docs/alert.md): Display important messages in your Svelte app with theui-svelte's customizable Alert component.
- [Avatar](https://www.theui.dev/docs/avatar.md): Show a user with a photo, initials or an icon, add a status dot, and stack a group of avatars with theui-svelte's Avatar component.
- [Badge](https://www.theui.dev/docs/badge.md): Add dynamic visual indicators like notifications and status labels with theui-svelte's Badge component.
- [Breadcrumb](https://www.theui.dev/docs/breadcrumb.md): Show the path to the current page with theui-svelte's Breadcrumb component.
- [Button](https://www.theui.dev/docs/button.md): Create responsive and stylish buttons for your Svelte app with theui-svelte's fully customizable Button component.
- [Button Group](https://www.theui.dev/docs/button-group.md): Create responsive and stylish button groups for your Svelte app with theui-svelte, fully customizable with TailwindCSS.
- [Card](https://www.theui.dev/docs/card.md): A content surface with an optional title, top or bottom image, and a side by side layout.
- [Checkbox](https://www.theui.dev/docs/checkbox.md): A styled checkbox that takes its size, shape and label classes from the Form or Fieldset around it.
- [Chips](https://www.theui.dev/docs/chips.md): Compact pills for tags, filters and selected people, with an optional image and close button.
- [Close Button](https://www.theui.dev/docs/close.md): A functional close button component for your Svelte app in theui-svelte library.
- [Collapse](https://www.theui.dev/docs/collapse.md): Toggle content visibility smoothly with theui-svelte's Collapse component for a better user experience.
- [Container](https://www.theui.dev/docs/container.md): Structure your Svelte app with theui-svelte's Container component for flexible and responsive layouts.
- [Dark Mode](https://www.theui.dev/docs/dark-mode.md): A button that switches between light and dark mode and remembers the choice.
- [Divider](https://www.theui.dev/docs/divider.md): Separate content with a horizontal or vertical line, with an optional label, using theui-svelte's Divider component.
- [Drawer](https://www.theui.dev/docs/drawer.md): A panel that slides in from the edge of the screen to hold navigation or extra content.
- [Dropdown](https://www.theui.dev/docs/dropdown.md): A customizable dropdown menu component for selecting options with smooth interaction and accessibility.
- [Fieldset](https://www.theui.dev/docs/fieldset.md): A wrapper for grouping related inputs, providing better structure and styling control in forms.
- [FileInput](https://www.theui.dev/docs/file-input.md): A customizable file selection input to handle uploads with consistent style and behavior.
- [Form](https://www.theui.dev/docs/form.md): A reusable wrapper for HTML forms to simplify creation, submission, and event handling.
- [Helper Text](https://www.theui.dev/docs/helper-text.md): Provides additional context or guidance for form inputs, like hints or error messages, supporting plain and dynamic text.
- [Input](https://www.theui.dev/docs/input.md): A flexible, customizable input component supporting various types for consistent user experience.
- [Label](https://www.theui.dev/docs/label.md): A reusable component for consistent form labels supporting strings and snippets, integrated with form inputs.
- [List Group](https://www.theui.dev/docs/list-group.md): A list of links or plain rows, in a bordered or a flat variant.
- [Modal](https://www.theui.dev/docs/modal.md): Modal dialogs with a focus trap, a scroll lock and Escape to close.
- [Navbar](https://www.theui.dev/docs/navbar.md): Responsive and accessible navigation bars tailored for usability in your Svelte app.
- [Notification](https://www.theui.dev/docs/notification.md): Deliver user notifications with various alert styles for effective communication.
- [Pagination](https://www.theui.dev/docs/pagination.md): Page links with previous and next controls, for a list split across pages.
- [Popover](https://www.theui.dev/docs/popover.md): Flexible UI element showing extra content on user interaction for context or actions.
- [Popup](https://www.theui.dev/docs/popup.md): Entry and exit intent popups, with control over how often they show.
- [Progress Bar](https://www.theui.dev/docs/progress-bar.md): Visual indicator of task progress with customizable styling options.
- [Quick Action Button - QAB](https://www.theui.dev/docs/qab.md): A floating action button fixed to a corner of the viewport, with a menu of actions.
- [Radio Button](https://www.theui.dev/docs/radio-button.md): Select a single option from a group with a modern, customizable radio button supporting sizes and animations.
- [Rating](https://www.theui.dev/docs/rating.md): Collect or display a star rating, with half stars, read-only mode and full keyboard support, using theui-svelte's Rating component.
- [Select](https://www.theui.dev/docs/select.md): Customizable dropdown for selecting options with support for static/dynamic options and floating labels.
- [Skeleton](https://www.theui.dev/docs/skeleton.md): Show the shape of content while it loads with theui-svelte's Skeleton component, in text, rectangle and circle variants.
- [Slider](https://www.theui.dev/docs/slider.md): Show images or content one after another with theui-svelte's Slider component, with effects, swipe, thumbnails and parallax.
- [Spinner](https://www.theui.dev/docs/spinner.md): Show that something is loading with a ring, dots or ping spinner from theui-svelte.
- [Svg Icon](https://www.theui.dev/docs/svg-icon.md): Add scalable vector icons to your Svelte app, improving UI clarity and style.
- [Table](https://www.theui.dev/docs/table.md): Display data responsively with customizable tables for your Svelte app.
- [Tabs](https://www.theui.dev/docs/tabs.md): Organize content into navigable sections with tabs and pills for a smooth user experience.
- [Toggle](https://www.theui.dev/docs/toggle.md): Customizable switch component replacing checkboxes and radio buttons.
- [Tooltip](https://www.theui.dev/docs/tooltip.md): Provide contextual information using informative tooltips in your Svelte app.

## Forms

- [Combobox](https://www.theui.dev/docs/combobox.md): A searchable select with multi-select chips, option groups, created entries and async search, from theui-svelte.
- [Date Picker](https://www.theui.dev/docs/date-picker.md): Pick a date from a calendar with limits, disabled days, any locale and full keyboard support, using theui-svelte's DatePicker component.
- [File Dropzone](https://www.theui.dev/docs/file-dropzone.md): Let users drop or pick files, with type and size checks, image previews and a removable list, using theui-svelte's FileDropzone component.
- [Form Wizard](https://www.theui.dev/docs/form-wizard.md): Break a long form into numbered steps with validation, progress and Back and Next buttons, using theui-svelte's FormWizard and FormStep components.
- [OTP Input](https://www.theui.dev/docs/otp-input.md): Collect a one time code in separate boxes, with paste, backspace and SMS autofill support, using theui-svelte's OtpInput component.
- [Range](https://www.theui.dev/docs/range.md): Let users pick a number by dragging, with a value bubble, ticks and full form support, using theui-svelte's Range component.
- [Stepper](https://www.theui.dev/docs/stepper.md): A number field with minus and plus buttons, limits, decimal steps and press and hold repeat, from theui-svelte.
- [Time Picker](https://www.theui.dev/docs/time-picker.md): Pick a time in separate hour, minute and AM/PM parts, with typing, arrow keys and the mouse wheel, using theui-svelte's TimePicker component.

## Optional

- [Full documentation in one file](https://www.theui.dev/svelte/llms-full.txt): every page above concatenated, for pasting into a context window in one go.
- [Repository](https://github.com/mbparvezme/theui-svelte): source, issues and changelog.