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
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
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
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:
<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
<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.
{
"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
<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 and TitleBar.
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:
import { lucideReactAdapter, phosphorReactAdapter, reactSvgAdapter } from "@tarve/react-icons";
import { Save } from "lucide-react";
const app = createApp(App, { componentAdapters: [reactSvgAdapter, lucideReactAdapter, phosphorReactAdapter] });
<Save size={16} />