# @vertesia/ui Component Library for LLMs

> React component library for building Vertesia UI plugins and applications.
> This file documents component APIs and usage patterns for AI assistants.

## Reference URLs

- Visual style guide: https://docs-ui-style-shadcn.vertesia.dev
- Markdown component guide: https://docs-ui-style-shadcn.vertesia.dev/components.md
- LLM reference: https://docs-ui-style-shadcn.vertesia.dev/llms.txt

# @vertesia/ui Component Reference

> Markdown rendition of the Vertesia UI style guide for LLMs and text-first clients.
> Visual style guide: https://docs-ui-style-shadcn.vertesia.dev

Use this file when generating React UI for Vertesia apps or plugins. Prefer `@vertesia/ui`
components over local duplicates, and use semantic color classes instead of hardcoded colors.

# Import Paths

```tsx
import { Button, Input, Modal, SelectBox, Tabs } from '@vertesia/ui/core';
import { FullHeightLayout, SidebarItem } from '@vertesia/ui/layout';
import { GenericPageNavHeader, ModernAgentConversation } from '@vertesia/ui/features';
import { NavLink, useLocation, useNavigate } from '@vertesia/ui/router';
import { useUserSession } from '@vertesia/ui/session';
```

# Catalog

## Classes

- [Semantic](https://docs-ui-style-shadcn.vertesia.dev/semantic)
- [Background](https://docs-ui-style-shadcn.vertesia.dev/classes/background)
- [Text](https://docs-ui-style-shadcn.vertesia.dev/classes/text)
- [Border & Ring](https://docs-ui-style-shadcn.vertesia.dev/classes/border)
- [Icons](https://docs-ui-style-shadcn.vertesia.dev/classes/icons)

## Components

- [Heading](https://docs-ui-style-shadcn.vertesia.dev/components/heading)
- [Buttons](https://docs-ui-style-shadcn.vertesia.dev/components/buttons)
- [Badges](https://docs-ui-style-shadcn.vertesia.dev/components/badges)
- [Dot Badges](https://docs-ui-style-shadcn.vertesia.dev/components/dotBadges)
- [Message Box](https://docs-ui-style-shadcn.vertesia.dev/components/messageBox)
- [Modal](https://docs-ui-style-shadcn.vertesia.dev/components/modal)
- [Confirm Modal](https://docs-ui-style-shadcn.vertesia.dev/components/confirmModal)
- [Delete Modal](https://docs-ui-style-shadcn.vertesia.dev/components/deleteModal)
- [Filter](https://docs-ui-style-shadcn.vertesia.dev/components/filter)
- [Tabs](https://docs-ui-style-shadcn.vertesia.dev/components/tabs)
- [Tooltips](https://docs-ui-style-shadcn.vertesia.dev/components/tooltips)
- [Switch](https://docs-ui-style-shadcn.vertesia.dev/components/switch)
- [Side Panel](https://docs-ui-style-shadcn.vertesia.dev/components/sidePanel)
- [SelectBox](https://docs-ui-style-shadcn.vertesia.dev/components/selectBox)
- [Overlay](https://docs-ui-style-shadcn.vertesia.dev/components/overlay)
- [Breadcrumbs](https://docs-ui-style-shadcn.vertesia.dev/components/breadcrumb)
- [Monaco](https://docs-ui-style-shadcn.vertesia.dev/components/monaco)
- [Card](https://docs-ui-style-shadcn.vertesia.dev/components/card)
- [Checkbox](https://docs-ui-style-shadcn.vertesia.dev/components/checkbox)
- [Collapsible](https://docs-ui-style-shadcn.vertesia.dev/components/collapsible)
- [Command](https://docs-ui-style-shadcn.vertesia.dev/components/command)
- [Dropdown](https://docs-ui-style-shadcn.vertesia.dev/components/dropdown)
- [Label](https://docs-ui-style-shadcn.vertesia.dev/components/label)
- [Panel](https://docs-ui-style-shadcn.vertesia.dev/components/panel)
- [Popover](https://docs-ui-style-shadcn.vertesia.dev/components/popover)
- [Radio Group](https://docs-ui-style-shadcn.vertesia.dev/components/radioGroup)
- [Resizeable](https://docs-ui-style-shadcn.vertesia.dev/components/resizeable)
- [Separator](https://docs-ui-style-shadcn.vertesia.dev/components/separator)
- [Text](https://docs-ui-style-shadcn.vertesia.dev/components/text)
- [Theme](https://docs-ui-style-shadcn.vertesia.dev/components/theme)

## Layout & Structure

- [Avatar](https://docs-ui-style-shadcn.vertesia.dev/components/avatar)
- [Center](https://docs-ui-style-shadcn.vertesia.dev/components/center)
- [Divider](https://docs-ui-style-shadcn.vertesia.dev/components/divider)
- [Link](https://docs-ui-style-shadcn.vertesia.dev/components/link)
- [Portal](https://docs-ui-style-shadcn.vertesia.dev/components/portal)
- [Spinner](https://docs-ui-style-shadcn.vertesia.dev/components/spinner)

## Forms

- [FormItem](https://docs-ui-style-shadcn.vertesia.dev/components/formItem)
- [Inputs](https://docs-ui-style-shadcn.vertesia.dev/components/inputs)
- [Textarea](https://docs-ui-style-shadcn.vertesia.dev/components/textarea)
- [ComboBox](https://docs-ui-style-shadcn.vertesia.dev/components/comboBox)
- [InputList](https://docs-ui-style-shadcn.vertesia.dev/components/inputList)
- [MenuList](https://docs-ui-style-shadcn.vertesia.dev/components/menuList)
- [NumberInput](https://docs-ui-style-shadcn.vertesia.dev/components/numberInput)
- [SelectList](https://docs-ui-style-shadcn.vertesia.dev/components/selectList)
- [TagsInput](https://docs-ui-style-shadcn.vertesia.dev/components/tagsInput)

# Component Guidance

## Button

Primary action primitive with Vertesia variants, loading state, disabled state, and tooltip support.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/buttons
- Import path: `@vertesia/ui/core`
- Exports: `Button`, `CopyButton`, `buttonVariants`

### Use When

- Use for commands, submissions, toolbar actions, and navigational actions that behave like buttons.
- Use `variant="destructive"` only for dangerous or irreversible actions.
- Use icon-size buttons with lucide icons for compact toolbars.

### Notes

- `alt` or `title` wraps the button in `VTooltip`.
- `isDisabled` and `isLoading` both disable interaction; `isLoading` also renders a spinner.

### Button Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | 'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'unstyled' | 'primary' | Visual treatment. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon' | 'md' | Control dimensions and text size. |
| asChild | boolean | false | Render the child via Radix Slot. |
| alt | string | - | Tooltip text. |
| isDisabled | boolean | false | Disable interaction. |
| isLoading | boolean | false | Show spinner and disable interaction. |
| className | string | - | Additional Tailwind classes. |
| children | React.ReactNode | - | Rendered child content. |

### CopyButton Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| content * | string | - | Text copied to the clipboard. |
| alt | string | - | Tooltip text; defaults to localized copy text. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon' | - | Button size. |

### Example

```tsx
import { Button } from '@vertesia/ui/core';

<Button variant="primary" isLoading={saving} onClick={save}>
  Save
</Button>
```

## Input

Single-line text input with a simplified value-based `onChange` callback.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/inputs
- Import path: `@vertesia/ui/core`
- Exports: `Input`

### Use When

- Use for compact string fields in forms, filters, and search inputs.
- Pass state setters directly because `onChange` receives the next value, not a DOM event.

### Notes

- Textarea intentionally uses standard React change events; do not copy Input handling to Textarea.

### Input Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Current input value. |
| onChange | (value: string) => void | - | Called with the next value. |
| placeholder | string | - | Placeholder text. |
| disabled | boolean | - | Disable editing. |
| clearable | boolean | - | Show a clear button when populated. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Input size. |
| variant | 'default' \| 'unstyled' \| 'noPadding' \| 'legacy' | 'default' | Visual treatment. |

### Example

```tsx
const [name, setName] = useState('');

<Input value={name} onChange={setName} placeholder="Name" />
```

## Textarea

Multi-line text control using standard React textarea event handling.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/textarea
- Import path: `@vertesia/ui/core`
- Exports: `Textarea`

### Use When

- Use for descriptions, prompts, comments, and other multi-line text.

### Notes

- Unlike `Input`, `Textarea` passes a React change event to `onChange`.

### Textarea Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | string | - | Current value. |
| onChange | (event: React.ChangeEvent<HTMLTextAreaElement>) => void | - | Standard React textarea change handler. |
| placeholder | string | - | Placeholder text. |
| disabled | boolean | - | Disable editing. |

### Example

```tsx
<Textarea value={notes} onChange={(event) => setNotes(event.target.value)} />
```

## FormItem

Field wrapper for labels, required indicators, and help tooltips.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/formItem
- Import path: `@vertesia/ui/core`
- Exports: `FormItem`

### Use When

- Use around most labeled fields in create/edit forms.
- Use `description` instead of loose helper paragraphs when a tooltip is enough.

### FormItem Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label * | React.ReactNode | - | Field label. |
| required | boolean | - | Render required marker. |
| description | React.ReactNode | - | Help tooltip content. |
| direction | 'column' \| 'row' | 'column' | Label/control layout. |
| disabled | boolean | - | Dim the label. |
| className | string | - | Additional Tailwind classes. |
| children | React.ReactNode | - | Rendered child content. |

### Example

```tsx
<FormItem label="Name" required description="Visible to users">
  <Input value={name} onChange={setName} />
</FormItem>
```

## Modal

Accessible overlay dialog for focused tasks and forms.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/modal
- Import path: `@vertesia/ui/core`
- Exports: `Modal`, `ModalTitle`, `ModalBody`, `ModalFooter`

### Use When

- Use for short create/edit flows, confirmations with custom content, and focused secondary tasks.
- Use `disableCloseOnClickOutside` for forms with unsaved user input.

### Modal Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| isOpen * | boolean | - | Whether the modal is visible. |
| onClose * | () => void | - | Called when the user dismisses the modal. |
| size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Modal width. |
| disableCloseOnClickOutside | boolean | - | Prevent accidental close from overlay click. |
| noCloseButton | boolean | - | Hide the close button. |
| allowOverflow | boolean | - | Allow content to overflow modal bounds. |

### ModalFooter Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'left' \| 'center' \| 'right' | 'right' | Footer action alignment. |
| className | string | - | Additional Tailwind classes. |
| children | React.ReactNode | - | Rendered child content. |

### Example

```tsx
<Modal isOpen={open} onClose={onClose} size="lg" disableCloseOnClickOutside>
  <ModalTitle>Edit item</ModalTitle>
  <ModalBody>...</ModalBody>
  <ModalFooter>
    <Button variant="outline" onClick={onClose}>Cancel</Button>
    <Button onClick={save}>Save</Button>
  </ModalFooter>
</Modal>
```

## ConfirmModal

Confirmation dialog for actions that need explicit user consent.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/confirmModal
- Import path: `@vertesia/ui/core`
- Exports: `ConfirmModal`

### Use When

- Use for consequential actions when a simple confirmation is enough.

### ConfirmModal Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| isOpen * | boolean | - | Whether the dialog is visible. |
| title * | React.ReactNode | - | Dialog title. |
| content * | React.ReactNode | - | Dialog body. |
| onConfirm * | () => void \| Promise<void> | - | Confirm handler. |
| onCancel * | () => void | - | Cancel handler. |
| isLoading | boolean | - | Show loading state while confirming. |

## DeleteModal

Delete-specific confirmation wrapper with async delete handling and toast feedback.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/deleteModal
- Import path: `@vertesia/ui/core`
- Exports: `DeleteModal`

### Use When

- Use for deletion flows where the target is represented by an id.

### Notes

- Requires a `ToastProvider` ancestor.

### DeleteModal Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| idToDelete * | string \| undefined | - | Open when populated. |
| setIdToDelete * | (id: string \| undefined) => void | - | Closes/reset target. |
| deleteApi * | (id: string) => Promise<void> | - | Async delete function. |
| title * | React.ReactNode | - | Dialog title. |
| content * | React.ReactNode | - | Dialog body. |

## SelectBox

Dropdown select for string or object options, with optional search, clear, and multi-select modes.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/selectBox
- Import path: `@vertesia/ui/core`
- Exports: `SelectBox`

### Use When

- Use for choosing one or more values from a bounded list.
- Use `filterBy` for large lists and `by` for stable object equality.

### SelectBox Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options * | T[] | - | Selectable options. |
| value * | T \| T[] \| undefined | - | Selected value or values. |
| onChange * | (value: T \| T[]) => void | - | Selection change handler. |
| multiple | boolean | false | Enable multi-select. |
| optionLabel | (option: T) => React.ReactNode | - | Custom option renderer. |
| filterBy | keyof T \| ((option: T) => string) | - | Enable searchable filtering. |
| by | keyof T \| ((a: T, b: T) => boolean) | - | Equality key or comparator. |
| isClearable | boolean | false | Show clear action. |
| placeholder | string | - | Placeholder when empty. |
| disabled | boolean | - | Disable interaction. |

### Example

```tsx
<SelectBox<Person>
  options={people}
  value={person}
  onChange={setPerson}
  optionLabel={(option) => option.name}
  filterBy="name"
  by="id"
/>
```

## Tabs

Tab container driven by an array of tab objects and companion bar/panel components.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/tabs
- Import path: `@vertesia/ui/core`
- Exports: `Tabs`, `TabsBar`, `TabsPanel`, `VTabs`, `VTabsBar`, `VTabsPanel`

### Use When

- Use to switch between sibling views on the same page.
- Prefer the current `Tabs` API shown in the style guide for new docs-ui code.

### Tabs Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tabs * | Tab[] | - | Tabs with name, label, and content. |
| defaultValue | string | - | Initially selected tab. |
| value | string | - | Controlled selected tab. |
| onTabChange | (tabName: string) => void | - | Called when selection changes. |
| variant | 'tabs' \| 'pills' | 'tabs' | Visual treatment. |
| fullWidth | boolean | - | Stretch tabs across available width. |
| responsive | boolean | - | Adapt tab layout at smaller widths. |

## Badge and DotBadge

Compact status and category labels.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/badges
- Import path: `@vertesia/ui/core`
- Exports: `Badge`, `DotBadge`

### Use When

- Use `Badge` for short textual labels.
- Use `DotBadge` for status chips where the colored dot carries state.

### Notes

- Use semantic variants for status meaning instead of custom colors.

## MessageBox

Semantic feedback box for success, attention, destructive, done, info, and muted messages.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/messageBox
- Import path: `@vertesia/ui/core`
- Exports: `MessageBox`

### Use When

- Use for inline feedback, warnings, errors, and informational notices.

## Checkbox, Switch, and RadioGroup

Choice controls for boolean values and mutually exclusive option sets.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/checkbox
- Import path: `@vertesia/ui/core`
- Exports: `Checkbox`, `Switch`, `RadioGroup`, `RadioGroupItem`, `RadioGroupOption`

### Use When

- Use `Checkbox` for independent boolean fields.
- Use `Switch` for settings that take effect immediately.
- Use `RadioGroup` for one-of-many choices when all options should be visible.

## Dropdown, Popover, Command, Tooltip

Overlay primitives for action menus, floating content, command palettes, and contextual help.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/dropdown
- Import path: `@vertesia/ui/core`
- Exports: `Dropdown`, `MenuGroup`, `MenuItem`, `Popover`, `Command`, `VTooltip`, `Tooltip`

### Use When

- Use `Dropdown` for action menus.
- Use `Popover` for small interactive floating panels.
- Use `Command` for searchable command or selection lists.
- Use `VTooltip` or `Tooltip` for short hover/focus help.

## Card and Panel

Content containers for repeated items and framed tool surfaces.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/card
- Import path: `@vertesia/ui/core`
- Exports: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `Panel`

### Use When

- Use cards for repeated items, modal content groups, and genuinely framed tools.
- Avoid putting cards inside cards or styling whole page sections as floating cards.

## Layout Primitives

Small primitives for display, separation, links, loading states, portals, and overlays.

- Route: https://docs-ui-style-shadcn.vertesia.dev/components/center
- Import path: `@vertesia/ui/core`
- Exports: `Avatar`, `SvgAvatar`, `Center`, `Divider`, `Link`, `Portal`, `Spinner`, `Separator`, `Overlay`

### Use When

- Use `Spinner` for loading states and `Center` to center short empty/loading content.
- Use `Separator` for semantic separators and `Divider` for a simple visual rule.
- Use `Avatar` for users or entities with image, initials, or fallback display.

## Semantic Colors and Icons

Semantic Tailwind classes and approved lucide-react icon guidance for Vertesia apps.

- Route: https://docs-ui-style-shadcn.vertesia.dev/semantic
- Import path: `@vertesia/ui/core`
- Exports: `ModeToggle`

### Use When

- Use semantic colors: success, attention, destructive, done, info, muted.
- Use lucide-react icons in buttons and toolbars when an icon exists.
- Use `ModeToggle` for light/dark theme control.

### Notes

- Examples: `text-success`, `bg-attention`, `border-destructive`, `bg-mixer-muted/30`.
- Avoid hardcoded color values in application UI.

# Key Rules

- `Input` passes a string value to `onChange`; `Textarea` passes a React change event.
- Use `FormItem` for labeled form fields in create/edit forms.
- Use semantic colors: `success`, `attention`, `destructive`, `done`, `info`, and `muted`.
- Use lucide-react icons in icon buttons and compact toolbars.
- Avoid nested cards and avoid styling whole page sections as cards.
