# iv-ui — full documentation # iv-ui A Svelte 5 component library with a monochrome, console-grade design system. Token-pure, accessible, runes-native. Version 0.3.0 · 37 components · Svelte 5 · MIT ## Install ```sh bun add @elluzion/iv-ui @tabler/icons-svelte ``` ## Documentation - [Installation](https://iv-ui.vercel.app/docs/installation.md) - [Quickstart](https://iv-ui.vercel.app/docs/quickstart.md) - [Theming](https://iv-ui.vercel.app/docs/theming.md) - [Accessibility](https://iv-ui.vercel.app/docs/accessibility.md) - [For agents](https://iv-ui.vercel.app/docs/for-agents.md) - [Tokens](https://iv-ui.vercel.app/foundations/tokens.md) ## Components ### Form & Input - [Button](https://iv-ui.vercel.app/components/button.md): Triggers an action or submits a form. - [Input](https://iv-ui.vercel.app/components/input.md): A single-line text field with an optional label, helper, and error state. - [Checkbox](https://iv-ui.vercel.app/components/checkbox.md): A binary choice with an optional label and a mixed state. - [Field](https://iv-ui.vercel.app/components/field.md): Labels a custom control and renders its helper or error message. - [InputGroup](https://iv-ui.vercel.app/components/input-group.md): Joins an input with prefix and suffix addons inside one frame. - [NativeSelect](https://iv-ui.vercel.app/components/native-select.md): A native select element with the library field treatment. - [RadioGroup](https://iv-ui.vercel.app/components/radio-group.md): A set of mutually exclusive options with one selected value. - [Select](https://iv-ui.vercel.app/components/select.md): A custom listbox with search, multiple selection, and clearing. - [Slider](https://iv-ui.vercel.app/components/slider.md): Selects a number, or a range, along a track. - [Switch](https://iv-ui.vercel.app/components/switch.md): An on/off control that applies immediately. - [Textarea](https://iv-ui.vercel.app/components/textarea.md): A multi-line text field with an optional count and error state. - [Toggle](https://iv-ui.vercel.app/components/toggle.md): A pressable button that keeps a checked state. - [ToggleGroup](https://iv-ui.vercel.app/components/toggle-group.md): A row of toggles with single or multiple selection. - [ButtonGroup](https://iv-ui.vercel.app/components/button-group.md): Joins related buttons into one segmented control. ### Layout & Navigation - [Accordion](https://iv-ui.vercel.app/components/accordion.md): A stack of collapsible sections; one or several can be open. - [Article](https://iv-ui.vercel.app/components/article.md): A readable page body with an optional title and standfirst. - [Breadcrumb](https://iv-ui.vercel.app/components/breadcrumb.md): Shows the path to the current page. - [Card](https://iv-ui.vercel.app/components/card.md): A bordered surface for grouped content and actions. - [Collapsible](https://iv-ui.vercel.app/components/collapsible.md): A single section that expands to reveal content. - [Separator](https://iv-ui.vercel.app/components/separator.md): A hairline rule that separates content. - [Tabs](https://iv-ui.vercel.app/components/tabs.md): Switches between panels that share one context. ### Overlays - [AlertDialog](https://iv-ui.vercel.app/components/alert-dialog.md): A blocking confirmation that returns a decision through an action. - [ContextMenu](https://iv-ui.vercel.app/components/context-menu.md): Opens a menu at the pointer or from the keyboard Menu key. - [Dialog](https://iv-ui.vercel.app/components/dialog.md): A modal surface for focused tasks and confirmations. - [Menu](https://iv-ui.vercel.app/components/menu.md): A vertical list of commands, options, or links. - [Popover](https://iv-ui.vercel.app/components/popover.md): A floating panel anchored to an element. - [Sheet](https://iv-ui.vercel.app/components/sheet.md): A panel that slides in from an edge for secondary flows. - [Toast](https://iv-ui.vercel.app/components/toast.md): A single transient notification driven by the toast store. - [Tooltip](https://iv-ui.vercel.app/components/tooltip.md): A short label shown on hover or focus. ### Feedback & Status - [Alert](https://iv-ui.vercel.app/components/alert.md): An inline message for information, success, warning, or error. - [EmptyState](https://iv-ui.vercel.app/components/empty-state.md): Explains why an area has no content and offers the next step. - [LoadingSpinner](https://iv-ui.vercel.app/components/loading-spinner.md): An indeterminate indicator for short waits. - [Progress](https://iv-ui.vercel.app/components/progress.md): Shows how much of a task is complete. - [Skeleton](https://iv-ui.vercel.app/components/skeleton.md): A pulsing placeholder that holds the shape of loading content. ### Display & Misc - [Avatar](https://iv-ui.vercel.app/components/avatar.md): A circular identity image with initials and an optional presence dot. - [Badge](https://iv-ui.vercel.app/components/badge.md): A compact label for status, counts, or categories. - [Shortcut](https://iv-ui.vercel.app/components/shortcut.md): Renders a keyboard combination as key caps. ## Machine-readable - [llms.txt](https://iv-ui.vercel.app/llms.txt) - [Full documentation](https://iv-ui.vercel.app/llms-full.txt) - [API corpus](https://iv-ui.vercel.app/llms-api.txt) - [API index](https://iv-ui.vercel.app/api/index.json) --- # Button Triggers an action or submits a form. ## Import ```svelte import { Button } from '@elluzion/iv-ui'; ``` ## Preview Six levels of emphasis. `secondary` is the default. ```svelte
``` ## Usage - Keep one primary action per view; everything else stays `secondary` or `outline`. - Use `loading` for async work — it sets `aria-busy` and ignores clicks without removing the button from the tab order. - Icon-only buttons need an `aria-label`; the `icon` variant has no text to fall back on. ## Examples ### Sizes `sm`, `md`, and `lg` share the same shape. ```svelte
``` ### Icons Icons inherit the text size. Icon-only buttons use `variant="icon"`. ```svelte
``` ### Loading Spinner replaces the label and clicks are ignored while `loading` is true. ```svelte
``` ### Events `onclick` and the legacy `on:click` both receive the native mouse event. ```svelte

onclick {clicks} · on:click {legacy}

``` ### Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'icon' \| 'danger'` | `'secondary'` | Visual emphasis. `secondary` is the default. | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button height and padding. | | `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. | | `loading` | `boolean` | `false` | Shows a spinner, sets `aria-busy`, and ignores clicks. | | `className` | `string` | `''` | Extra classes merged onto the root element. | | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native button type. | All native `{/snippet}

last search: {submitted || '—'}

``` ### Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size shared by the group and its addons. | | `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. | | `className` | `string` | `''` | Extra classes merged onto the root element. | ### Snippets | Snippet | Type | Description | | --- | --- | --- | | `prefix` | `Snippet` | Content rendered before the input, such as a protocol or icon. | | `suffix` | `Snippet` | Content rendered after the input, such as a unit or button. | | `children` | `Snippet` | The input control. | ### Tokens used `--iv_border` · `--iv_border-focus` · `--iv_border-hover` · `--iv_control-pad-x` · `--iv_control-pad-x-lg` · `--iv_control-pad-x-sm` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_font-ui` · `--iv_foreground-dim` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_surface-elevated` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-body-sm` · `--iv_text-label` · `--iv_transition-base` See the [token reference](https://iv-ui.vercel.app/foundations/tokens.md) for values. ### CSS hooks `.iv-addon` · `.iv-control` · `.iv-disabled` · `.iv-input-group` · `.iv-input-wrapper` · `.iv-lg` · `.iv-native-select` · `.iv-prefix` · `.iv-sm` · `.iv-suffix` · `.iv-textarea-wrapper` · `.iv-trigger` ## Accessibility - The group is a visual container only; label the inner control itself. - Focus styling is applied to the whole frame through `:focus-within`. ## Related - [Input](https://iv-ui.vercel.app/components/input.md) - [NativeSelect](https://iv-ui.vercel.app/components/native-select.md) - [Field](https://iv-ui.vercel.app/components/field.md) - [Select](https://iv-ui.vercel.app/components/select.md) --- # NativeSelect A native select element with the library field treatment. ## Import ```svelte import { NativeSelect } from '@elluzion/iv-ui'; ``` ## Preview A labelled select with a placeholder and helper text. ```svelte
``` ## Usage - Use when the platform picker is preferable to the custom `Select`. - `options` accepts strings or `{ value, label, disabled }`; `placeholder` adds a disabled first option. - Pass `children` with `