# Tarve documentation

Everything you need to ship a native Windows and Linux interface from Bun and TSX: setup, the rendering model and a reference page for each of the 99 built-in components.

## Getting started

1. ### Install

   Tarve needs Bun 1.4+ (or Node.js 26.10+) on Windows x64 or Linux x64. From there you also build for [Android](https://tarve.dev/docs/android.md).

   ```sh
   bun add @tarve/core
   bun add -d typescript @types/bun
   ```

2. ### Configure TypeScript

   Point the JSX runtime at `@tarve/core`.

   ```tsx title="tsconfig.json"
   {
     "compilerOptions": {
       "target": "ESNext",
       "module": "ESNext",
       "moduleResolution": "Bundler",
       "strict": true,
       "jsx": "react-jsx",
       "jsxImportSource": "@tarve/core",
       "types": ["bun", "@tarve/core/assets"]
     }
   }
   ```

3. ### Write a window

   ```tsx title="app.tsx"
   import { Button, Column, Text, Window, createApp } from "@tarve/core";

   let count = 0;

   function App() {
     return (
       <Window title="Counter" width={520} height={360}>
         <Column flex={1} align="center" justify="center" gap={16}>
           <Text size={42} weight={700}>{count}</Text>
           <Button onClick={() => count++}>Increase</Button>
         </Column>
       </Window>
     );
   }

   const app = createApp(App);
   await app.ready;
   await app.closed;
   ```

4. ### Run and ship

   ```sh
   # runs the source directly, no build step
   bun app.tsx

   # Windows → .exe with the native runtime embedded
   bun run tarve build app.tsx --outfile dist/App.exe

   # cross-compile for Linux x64, no Rust toolchain needed
   bun run tarve build app.tsx --target linux-x64 --outfile dist/App
   ```

## How rendering works

Your view is a plain function that returns TSX. Tarve compiles it into a retained tree, diffs it against the previous one and sends only the changed nodes to the native runtime, where Taffy lays them out and Vello, D3D11 or the CPU renderer paints them.

State can live in ordinary variables. When a native event handler such as `onClick` or `onChange` runs, Tarve schedules a re-render automatically. For changes that happen outside an event (timers, network responses, file watchers) call `app.update()` on the handle returned by `createApp`.

Controls are *controlled*: pass the current value (`checked`, `value`, `open`…) and update it in the matching `on…Change` callback. An idle window presents zero frames.

For values that change many times a second (a clock, a progress bar, an animation), use a `signal()`. Passed as a text child or a style value, it is bound to that node: setting `count.value` sends only that field to the native runtime, with no render, diff or layout when the size stays the same. `batch()` groups several changes into one update, and `<audio time={position}>` writes the playback position into a signal.

```tsx title="clock.tsx"
import { Text, Window, createApp, signal } from "@tarve/core";

const time = signal(new Date().toLocaleTimeString());
setInterval(() => { time.value = new Date().toLocaleTimeString(); }, 1000);

createApp(() => (
  <Window title="Clock">
    <Text size={48}>{time}</Text>
  </Window>
));
```

`<Scroll followTail>` keeps a chat or a log at its end while content grows, until the user scrolls away; `app.scrollTo(id, { y: "end", smooth: true })` scrolls a `Scroll` after the next layout.

Style anything with the `style` prop or with [Tailwind classes](https://tarve.dev/docs/tailwind.md): `class="flex gap-2 p-4 hover:bg-muted"` compiles to the same native style, with no CSS involved.

## Components

### Window & layout

Windows, flex containers, scrolling regions and the primitives every screen is built from.

- [**Window** The root of every Tarve app: a native OS window with size, position and theme.](https://tarve.dev/docs/components/Window.md)
- [**TitleBar** A custom, draggable title bar with native minimize, maximize and close controls.](https://tarve.dev/docs/components/TitleBar.md)
- [**View** The base box. Flexbox/Grid layout, styling and events for anything you render.](https://tarve.dev/docs/components/View.md)
- [**Row** A View that lays its children out horizontally.](https://tarve.dev/docs/components/Row.md)
- [**Column** A View that lays its children out vertically.](https://tarve.dev/docs/components/Column.md)
- [**Scroll** A native scroll container with vertical, horizontal or two-axis scrolling.](https://tarve.dev/docs/components/Scroll.md)
- [**ScrollArea** A scroll container with themed scrollbars, ready for panels and lists.](https://tarve.dev/docs/components/ScrollArea.md)
- [**Overflow** Shows the items that fit on one line and hands the rest to a "more" control.](https://tarve.dev/docs/components/Overflow.md)
- [**Portal** Renders its children above the rest of the window, outside the parent's clipping.](https://tarve.dev/docs/components/Portal.md)
- [**Pressable** A headless interactive surface: click, hover, keyboard and context-menu events.](https://tarve.dev/docs/components/Pressable.md)
- [**Resizable** Two panels separated by a draggable, keyboard-accessible splitter.](https://tarve.dev/docs/components/Resizable.md)
- [**AspectRatio** Keeps its content at a fixed width-to-height ratio.](https://tarve.dev/docs/components/AspectRatio.md)
- [**Direction** Switches a subtree between left-to-right and right-to-left flow.](https://tarve.dev/docs/components/Direction.md)
- [**Separator** A thin horizontal or vertical divider line.](https://tarve.dev/docs/components/Separator.md)
- [**AnimatePresence** Keeps a child mounted while its native exit animation runs.](https://tarve.dev/docs/components/AnimatePresence.md)
- [**Glass** Liquid Glass: a refracting, blurring surface for toolbars, tab bars and floating controls.](https://tarve.dev/docs/components/Glass.md)

### Text & media

Parley-shaped text, typography presets, images, icons and declarative SVG.

- [**Text** Native, Parley-shaped text with size, weight, colour and selection.](https://tarve.dev/docs/components/Text.md)
- [**Typography** Preset text styles: headings, lead, muted, code and blockquote.](https://tarve.dev/docs/components/Typography.md)
- [**Link** A native hyperlink that opens through the platform's URI handler.](https://tarve.dev/docs/components/Link.md)
- [**Label** A form label with required and disabled states.](https://tarve.dev/docs/components/Label.md)
- [**Kbd** Renders a keyboard key or shortcut.](https://tarve.dev/docs/components/Kbd.md)
- [**Image** Displays files, URLs, encoded bytes or raw RGBA pixels.](https://tarve.dev/docs/components/Image.md)
- [**Avatar** A circular user image with a text fallback.](https://tarve.dev/docs/components/Avatar.md)
- [**Icon** Built-in stroke icons, or any icon from an SVG node list.](https://tarve.dev/docs/components/Icon.md)
- [**Svg** A declarative SVG canvas rendered natively.](https://tarve.dev/docs/components/Svg.md)
- [**Path** An SVG path element.](https://tarve.dev/docs/components/Path.md)
- [**Circle** An SVG circle element.](https://tarve.dev/docs/components/Circle.md)
- [**Ellipse** An SVG ellipse element.](https://tarve.dev/docs/components/Ellipse.md)
- [**Line** An SVG line element.](https://tarve.dev/docs/components/Line.md)
- [**Polyline** An SVG polyline element.](https://tarve.dev/docs/components/Polyline.md)
- [**Polygon** An SVG polygon element.](https://tarve.dev/docs/components/Polygon.md)
- [**SvgRect** An SVG rect element.](https://tarve.dev/docs/components/SvgRect.md)

### Inputs & forms

Text editing with IME and undo, choice controls, dates and form structure.

- [**Input** A single-line native text field with IME, selection and undo/redo.](https://tarve.dev/docs/components/Input.md)
- [**TextArea** A multi-line native text editor.](https://tarve.dev/docs/components/TextArea.md)
- [**InputGroup** Wraps an input with leading and trailing adornments.](https://tarve.dev/docs/components/InputGroup.md)
- [**InputOTP** A segmented one-time-code input.](https://tarve.dev/docs/components/InputOTP.md)
- [**Field** Label, description and error message around a form control.](https://tarve.dev/docs/components/Field.md)
- [**Checkbox** A labelled, controlled checkbox.](https://tarve.dev/docs/components/Checkbox.md)
- [**Switch** A labelled on/off toggle switch.](https://tarve.dev/docs/components/Switch.md)
- [**RadioGroup** A set of mutually exclusive options.](https://tarve.dev/docs/components/RadioGroup.md)
- [**Select** A themed dropdown for choosing one option.](https://tarve.dev/docs/components/Select.md)
- [**NativeSelect** A compact select with native-feeling keyboard behaviour.](https://tarve.dev/docs/components/NativeSelect.md)
- [**Combobox** A searchable select with filtering and keywords.](https://tarve.dev/docs/components/Combobox.md)
- [**Slider** Picks a number from a range by dragging or with the keyboard.](https://tarve.dev/docs/components/Slider.md)
- [**Toggle** A two-state button, like bold in a text toolbar.](https://tarve.dev/docs/components/Toggle.md)
- [**ToggleGroup** A row of toggles with single or multiple selection.](https://tarve.dev/docs/components/ToggleGroup.md)
- [**Calendar** A month grid for picking a date, with min/max and disabled days.](https://tarve.dev/docs/components/Calendar.md)
- [**DatePicker** A button that opens a Calendar popup.](https://tarve.dev/docs/components/DatePicker.md)

### Actions & feedback

Buttons, status indicators, notifications and empty states.

- [**Button** The primary action control, with variants and sizes.](https://tarve.dev/docs/components/Button.md)
- [**ButtonGroup** Joins related buttons into one segmented control.](https://tarve.dev/docs/components/ButtonGroup.md)
- [**Badge** A small status or count label.](https://tarve.dev/docs/components/Badge.md)
- [**Progress** A determinate progress bar.](https://tarve.dev/docs/components/Progress.md)
- [**Spinner** A loading indicator drawn by the renderer.](https://tarve.dev/docs/components/Spinner.md)
- [**Skeleton** A placeholder block for content that is still loading.](https://tarve.dev/docs/components/Skeleton.md)
- [**Alert** A highlighted message with title, description and icon.](https://tarve.dev/docs/components/Alert.md)
- [**Toast** A single transient notification.](https://tarve.dev/docs/components/Toast.md)
- [**Toaster** Stacks and positions a list of toasts you control.](https://tarve.dev/docs/components/Toaster.md)
- [**Empty** An empty state with icon, message and call to action.](https://tarve.dev/docs/components/Empty.md)

### Overlays

Modal and non-modal surfaces: dialogs, sheets, popovers, menus and command palettes.

- [**Modal** A modal dialog with title, description, body and footer.](https://tarve.dev/docs/components/Modal.md)
- [**Dialog** Alias of Modal, named after the shadcn convention.](https://tarve.dev/docs/components/Dialog.md)
- [**AlertDialog** A confirmation dialog with cancel and action buttons.](https://tarve.dev/docs/components/AlertDialog.md)
- [**Sheet** A panel that slides in from any edge of the window.](https://tarve.dev/docs/components/Sheet.md)
- [**Drawer** A Sheet that defaults to the bottom edge.](https://tarve.dev/docs/components/Drawer.md)
- [**Popover** Floating content anchored to a trigger.](https://tarve.dev/docs/components/Popover.md)
- [**Flyout** Unstyled anchored popup with light dismiss; its anchor toggles it.](https://tarve.dev/docs/components/Flyout.md)
- [**Tooltip** A short hint shown next to its trigger.](https://tarve.dev/docs/components/Tooltip.md)
- [**HoverCard** Rich preview content shown while hovering a trigger.](https://tarve.dev/docs/components/HoverCard.md)
- [**DropdownMenu** A menu of actions opened from a trigger.](https://tarve.dev/docs/components/DropdownMenu.md)
- [**ContextMenu** A right-click menu attached to a region.](https://tarve.dev/docs/components/ContextMenu.md)
- [**Command** An inline, searchable list of commands.](https://tarve.dev/docs/components/Command.md)
- [**CommandPalette** A modal command search, the classic Ctrl+K palette.](https://tarve.dev/docs/components/CommandPalette.md)

### Navigation

Tabs, menus, sidebars and other ways to move around an app.

- [**Tabs** Switches between panels of content.](https://tarve.dev/docs/components/Tabs.md)
- [**Accordion** Vertically stacked sections that expand one at a time.](https://tarve.dev/docs/components/Accordion.md)
- [**Collapsible** A single section that shows and hides its content.](https://tarve.dev/docs/components/Collapsible.md)
- [**Breadcrumb** Shows the path to the current location.](https://tarve.dev/docs/components/Breadcrumb.md)
- [**Pagination** Page navigation with previous, next and numbered pages.](https://tarve.dev/docs/components/Pagination.md)
- [**NavigationMenu** Top-level navigation with dropdown link panels.](https://tarve.dev/docs/components/NavigationMenu.md)
- [**Menubar** A desktop-style menu bar: File, Edit, View…](https://tarve.dev/docs/components/Menubar.md)
- [**AppMenuBar** The window's application menu bar, with access keys, accelerators and submenus; what app.menuBar draws.](https://tarve.dev/docs/components/AppMenuBar.md)
- [**Sidebar** A collapsible app sidebar with icons and badges.](https://tarve.dev/docs/components/Sidebar.md)
- [**Carousel** Steps through slides with buttons and indicators.](https://tarve.dev/docs/components/Carousel.md)

### Data display

Lists, virtualized collections, tables, grids, trees and charts.

- [**Card** A bordered container with title, description and footer.](https://tarve.dev/docs/components/Card.md)
- [**Item** A list row with title, description and leading/trailing slots.](https://tarve.dev/docs/components/Item.md)
- [**List** A simple, non-virtual list where every item stays mounted.](https://tarve.dev/docs/components/List.md)
- [**VirtualList** Renders only visible rows: fixed, measured or externally windowed.](https://tarve.dev/docs/components/VirtualList.md)
- [**Table** A static table built from column definitions.](https://tarve.dev/docs/components/Table.md)
- [**DataTable** A Table with clickable rows and an empty state.](https://tarve.dev/docs/components/DataTable.md)
- [**DataGrid** A virtualized grid with sorting, filtering and selection.](https://tarve.dev/docs/components/DataGrid.md)
- [**TreeView** A keyboard-navigable tree with expand and select.](https://tarve.dev/docs/components/TreeView.md)
- [**Chart** A simple native bar chart.](https://tarve.dev/docs/components/Chart.md)

### Rich content

Native leaves for large documents: Markdown, highlighted code and diffs.

- [**Markdown** Renders Markdown natively, built for large documents.](https://tarve.dev/docs/components/Markdown.md)
- [**Code** Syntax-highlighted code with optional line numbers.](https://tarve.dev/docs/components/Code.md)
- [**Diff** Unified diffs with word-level highlights and collapsible files.](https://tarve.dev/docs/components/Diff.md)

### App & chat

Building blocks for chat, assistant and onboarding interfaces.

- [**Message** A chat message with avatar, author, timestamp and actions.](https://tarve.dev/docs/components/Message.md)
- [**Bubble** The speech bubble used inside a message.](https://tarve.dev/docs/components/Bubble.md)
- [**MessageScroller** A scroll container for a conversation.](https://tarve.dev/docs/components/MessageScroller.md)
- [**Marker** A labelled divider, such as a date between messages.](https://tarve.dev/docs/components/Marker.md)
- [**Attachment** A file chip with upload progress and remove action.](https://tarve.dev/docs/components/Attachment.md)
- [**Questionnaire** A step-by-step form with text, single and multiple choice.](https://tarve.dev/docs/components/Questionnaire.md)

## Common props

Every component accepts these props in addition to its own.

| Prop | Type | Default |
| --- | --- | --- |
| `children`<br>Content rendered inside the component. | `Child` | — |
| `class`<br>Same as `className`, HTML spelling. Both may be given; `className` comes last. | `string` | — |
| `className`<br>Tailwind utility classes, compiled to `style` at the call site; an explicit `style` wins. | `string` | — |
| `draggable` | `boolean` | — |
| `dropTarget` | `boolean` | — |
| `fileDropTarget` | `boolean` | — |
| `highlight`<br>Highlights text matches inside the node, as used by find-in-page. | `TextHighlight` | — |
| `id`<br>Stable native node id. Used for focus, scrolling, tests and accessibility; popups derive their part ids from it. | `string` | — |
| `key`<br>Reconciliation key that keeps list items stable between renders. | `string \| number` | — |
| `motionFrom`<br>Initial numeric values for a native enter transition. | `MotionValues` | — |
| `onDragEnd` | `(event: DragEndEvent) => void` | — |
| `onDragEnter` | `(source: string) => void` | — |
| `onDragLeave` | `(source: string) => void` | — |
| `onDragMove` | `(event: DragMoveEvent) => void` | — |
| `onDragStart` | `(position: DragPosition) => void` | — |
| `onDrop` | `(event: DropEvent) => void` | — |
| `onFileDragEnter`<br>Files entered the node; `paths` are the dragged files. | `(paths: string[]) => void` | — |
| `onFileDragLeave` | `() => void` | — |
| `onFileDrop` | `(event: FileDropEvent) => void` | — |
| `onHighlight`<br>Reports how many highlight matches were found. | `(event: { matchCount: number }) => void` | — |
| `onPaste`<br>Receives non-text clipboard content (files or a bitmap) pasted while focused. | `(payload: PastePayload) => void` | — |
| `onPointerLeave`<br>The pointer left this node and its children (DOM `pointerleave`). | `() => void` | — |
| `onPointerMove`<br>Pointer position inside this node (like DOM `offsetX`/`offsetY`) while it is over it or its children. | `(point: { x: number; y: number }) => void` | — |
| `onSize`<br>Size after layout, on mount and whenever it changes (a ResizeObserver): `width`/`height` the content box (without padding and border, as `contentRect`), `borderBox` the whole box with them (`borderBoxSize`). | `(size: SizeEvent) => void` | — |
| `onTransitionEnd`<br>Called when a native transition finishes on a property. | `(event: { property: MotionProperty }) => void` | — |
| `rovingGroup`<br>Joins a roving-focus group so arrow keys move focus between siblings. | `boolean` | — |
| `style`<br>Layout, colour, border, shadow, gradient, transform and transition styles, plus hover/focus/active/disabled state styles. | `Style` | — |

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs · Index for agents: https://tarve.dev/llms.txt
