Tauri Plugin Widgets

Native widgets for Android, iOS, macOS, Windows, and Linux from one declarative JSON configuration.

Full documentation: https://s00d.github.io/tauri-plugin-widgets

Two CLIs (read this first)

| | Using the plugin in your app | Developing this repository | |---|---|---| | Entry | npx tauri-widgets / pnpm tauri-widgets | pnpm -C scripts cli / pnpm hosts | | Code | published dist-cli/ (from src-cli/) | scripts/ (TypeScript + scripts/sh) | | Examples | init, preview, signing, doctor, validate, trace, clean | hosts up, shot, test, docs-generate, triage |

If you are building an app: ignore pnpm test:android:visual and the rest of the root test:* / *-up scripts — those are for plugin maintainers.

Maintainer map: scripts/README.md · Contributing.

Install

pnpm tauri add tauri-plugin-widgets

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-widgets = "0.5"

pnpm add tauri-plugin-widgets-api

Consumer CLI (app authors)

npx tauri-widgets init                 # detect platforms → init-macos / ios / windows
npx tauri-widgets preview ./widget.json --size medium --watch
npx tauri-widgets signing              # identities + transport verdict
npx tauri-widgets signing --apply      # write plugins.widgets
npx tauri-widgets validate ./widget.json --platforms ios,android
npx tauri-widgets doctor
npx tauri-widgets trace --follow
npx tauri-widgets clean --group group.com.example.app
npx tauri-widgets clean --cache

Preview needs no native build — edits to the JSON reload in the browser.

JSON Schema (IDE autocomplete):

{
  "$schema": "https://s00d.github.io/tauri-plugin-widgets/schemas/widget-config.v1.json"
}

Example

import { setWidgetConfig } from "tauri-plugin-widgets-api";

await setWidgetConfig(
  {
    $schema: "https://s00d.github.io/tauri-plugin-widgets/schemas/widget-config.v1.json",
    small: {
      type: "vstack",
      padding: 12,
      background: "#1a1a2e",
      children: [
        { type: "text", content: "72°", fontSize: 36, fontWeight: "bold", color: "#fff" },
        { type: "progress", value: 0.7, tint: "#4CAF50", label: "Humidity" },
      ],
    },
  },
  "group.com.example.myapp",
  "weather",
);

Register tauri_plugin_widgets::init() and widgets:default in capabilities. Details: Install · First widget.

Platform setup

| Platform | Docs | | --- | --- | | Android | Setup | | iOS | Setup | | macOS | Setup | | Windows | Setup | | Linux | Setup | | Desktop webview | Setup |

Or: npx tauri-widgets init / init-macos / init-ios / init-windows.

Try from zero

Minimal widget JSON + preview (no Tauri app required for layout):

# clone / degit this folder
npx degit s00d/tauri-plugin-widgets/templates/starter my-widget
cd my-widget
npx tauri-widgets preview ./widget.json --watch --open

Full app: use the example or pnpm tauri add then npx tauri-widgets init.

Developing this plugin (maintainers)

pnpm hosts status
pnpm hosts up ios android
pnpm shot weather.small linux
pnpm cli:test -- --platform desktop
pnpm docs:generate

See scripts/README.md.

License

MIT