# System integration

Everything an app does with the operating system around its window: tray, hotkeys, dialogs, widgets, its icon and name, and its own title bar.

## Tray icon

```tsx title="tray.tsx"
const tray = app.tray({
  tooltip: "Pulse",
  menu: [
    { id: "show", label: "Show", onSelect: () => app.activate() },
    { id: "pause", label: "Pause monitoring", checked: paused, onSelect: togglePause },
    { type: "separator" },
    { id: "quit", label: "Quit", onSelect: () => app.close() },
  ],
  onClick: () => app.activate(),
  // No tray host (GNOME without AppIndicator, a restarting Explorer): keep the window.
  onAvailability: ({ supported, available }) => { canHide = supported && available; },
});

tray.update({ tooltip: "Pulse — paused" }); // modified in place
tray.availability(); // { supported, available, reason? }
```

Windows and Linux (a StatusNotifierItem, shown by KDE, most desktops and GNOME with the AppIndicator extension); other platforms answer `supported: false`. A missing host is a state, not an error: `onAvailability` and `tray.availability()` report `{ supported, available, reason? }`, and the item turns `available` on when a host starts (Explorer restarting, an extension enabled). An app that hides to the tray should keep its window, or minimize instead, while `available` is false. A second `app.tray()` replaces the first. The icon defaults to the app icon. Combine it with `<Window onCloseRequest={e => { e.preventDefault(); app.hide(); }}>` for hide-on-close apps. `app.show()`, `app.hide()`, `app.minimize()` and `app.activate()` (show, restore and bring to front) control the window.

## Global hotkeys

```tsx title="app.tsx"
const unregister = app.registerHotkey("Ctrl+Shift+Space", () => app.activate());
// later
unregister();
```

Shortcuts work while the app is in the background. Handler errors go to `onError` with `source: "hotkey"`.

## File dialogs

```tsx title="app.tsx"
const file = await app.openFileDialog({ title: "Open project", filters: [{ name: "JSON", extensions: ["json"] }] });
const files = await app.openFilesDialog();
const folder = await app.openFolderDialog();
const target = await app.saveFileDialog({ fileName: "report.json", directory: home });
```

Each resolves to a path (or paths), or `undefined` when cancelled. Linux uses the XDG desktop portal. On Android the system document picker opens: an opened document is copied into the app's cache, a saved one is copied back when the app closes the file, and folders report an error. `<input type="file">` opens the same dialog.

## Clipboard and paste

Text fields handle copy, cut and paste natively. When the clipboard holds no text, `Ctrl+V` delivers files or a bitmap to the focused element's `onPaste`:

```tsx title="app.tsx"
<View focusable onPaste={payload => {
  if (payload.kind === "files") attach(payload.files);
  else if (payload.kind === "image") addImage(payload.width, payload.height, payload.rgba);
}} />
```

## Desktop widgets

```tsx title="widget.tsx"
<Window title="Clock" desktopWidget={{ columns: 3, rows: 2 }} position="top-right">
  <Clock />
</Window>
```

A desktop widget sits under every other window, stays out of the taskbar and snaps into free cells of a grid when dragged across the desktop. `level: "alwaysOnBottom"` or `"alwaysOnTop"` set the stacking without the grid. Not available on Android.

## App icon and metadata

Name, icon and publisher live in `package.json` under `"tarve"`. `tarve build`, `run` and `dev` read them; `--name`, `--version`, `--icon`, `--publisher`, `--copyright`, `--description` and `--app-id` override them.

```tsx title="package.json"
{
  "name": "pulse",
  "version": "1.2.0",
  "tarve": {
    "name": "Pulse",
    "description": "System monitor",
    "publisher": "Example Inc.",
    "copyright": "© 2026 Example Inc.",
    "icon": "assets/icon.png",
    "appId": "Example.Pulse"
  }
}
```

The icon is a square PNG (256 px or larger) or an `.ico`. On Windows the build writes a multi-size icon and version info into the `.exe`; on Linux it writes `<App>.desktop` and `<App>.png` beside the binary. The window, taskbar and tray use the same icon, and `appId` names the app in media controls and notifications. A monorepo sets per-entry values under `"tarve": { "apps": { "pulse/pulse.tsx": { … } } }`; `createApp(view, { icon })` sets the window icon directly.

## Custom title bar

```tsx title="app.tsx"
<Window title="My app" width={1000} height={700}>
  <TitleBar title="My app" />
  <View flex={1}>{/* application */}</View>
</Window>
```

`TitleBar` opts into Tarve-drawn window chrome while keeping native dragging, resize hit testing and minimize/maximize/close; Windows also gets Windows 11 corners and maximized/fullscreen border handling. A menu bar can sit inside it with `<AppMenuBar items>`; see [Desktop integration](https://tarve.dev/docs/desktop.md#menu-bar) and [TitleBar](https://tarve.dev/docs/components/TitleBar.md).

## Icon libraries

`Icon` and the SVG primitives are native. `@tarve/react-icons` adapts static SVG icon components from Lucide, Phosphor, Heroicons or Tabler without adding React to Tarve:

```tsx title="app.tsx"
import { lucideReactAdapter, phosphorReactAdapter, reactSvgAdapter } from "@tarve/react-icons";
import { Save } from "lucide-react";

const app = createApp(App, { componentAdapters: [reactSvgAdapter, lucideReactAdapter, phosphorReactAdapter] });

<Save size={16} />
```

---

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