API

Tauri commands

Every Tauri command of the plugin with its arguments, generated from src/commands.rs.

The #[tauri::command] functions in src/commands.rs, which the JS package calls with invoke('plugin:widgets|<name>', args). You normally use the JS functions instead; this list is for calling commands directly. Arguments are sent in camelCase; AppHandle and State parameters are injected by Tauri and not listed. Rust-side API: Rust.

Command	Description
`set_items`	Store a key-value pair in the widget data store.
`get_items`	Read a previously stored value from the widget data store.
`set_register_widget`	Register widget provider class names or kind strings.
`reload_all_timelines`	Reload all registered widget timelines.
`reload_timelines`	Reload timelines for a specific widget kind or class.
`request_widget`	Request the OS to pin (add) a widget to the home screen.
`create_widget_window`	Create a frameless, transparent desktop widget window.
`close_widget_window`	Close a previously created desktop widget window.
`set_widget_config`	Send a declarative UI configuration to native widgets.
`set_widget_config_from_path`	Load a `WidgetConfig` JSON file from disk, then apply it like `set_widget_config`.
`get_widget_config`	Read the current widget UI configuration from the data store.
`set_widget_data`	Values for `{{data.…}}` without resending the layout. `null` clears them.
`set_widget_state`	Change a placement's local state (`{{state.…}}`) like a `set` tap does: operators `$toggle` / `$inc` / `$dec`, `null` removes a key, `patch: null` clears the stored state. Returns the merged state (defaults included) and emits `widget-state-changed`.
`get_widget_state`	A placement's merged local state: config `state` defaults, then the stored state.
`register_activity_template`	Store a Live Activity layout under `name` (`activity-template:{name}`): activities with `template: name` then send only `data`. `null` removes it.
`set_widget_instances`	Choices for the per-placement picker (Apple Edit Widget sheet; listed for Android and desktop so the app can label placements).
`get_active_widgets`	Widgets placed right now (see `ActiveWidget`).
`start_activity`	Start (or update, when the id runs) a live activity.
`update_activity`	Replace the content of a running live activity.
`end_activity`	End a live activity; `dismissAfterMs` keeps the final state visible that long (iOS / desktop; Android removes the notification at once). `content` is the final state; `dismissalPolicy` `"default"` \| `"immediate"` (`dismissAfterMs` wins).
`get_widget_push_token`	WidgetKit push token (hex) for server-driven widget reloads; `null` where none exists.
`get_activity_push_to_start_token`	iOS 17.2+ push-to-start token (hex) for your APNs server; `null` elsewhere / not yet issued.
`can_promote_activities`	Android 16+: whether ongoing activity notifications may be promoted to Live Updates (status-bar chip, lock screen). `true` where the question does not apply.
`open_activity_promotion_settings`	Android: opens the system setting that allows Live Updates for this app. `false` when there is no such screen (other platforms, older Android).
`list_activities`	Ids of the running live activities this app started.
`activity_island`	Desktop activity island page → host: `expanded` grows / shrinks the island (hover, click), `focus` brings a minimal activity to the pill. Returns what the island shows (`null` on mobile or without an island). Used by the built-in renderer.
`widget_action`	Trigger a `widget-action` event via the Rust plugin.
`poll_pending_actions`
`report_receipt`	Report that a renderer painted a config (desktop widget.html / tests). Native widgets write receipts themselves; this is for the host webview path.
`get_widget_diagnostics`	Live widget instances that recently rendered for `group`.
`get_widget_trace`	Host delivery journal + receipt history for `group`. Active in debug builds or when `WIDGET_DEBUG=1`.
`flush_widget_trace`	Force-flush the in-memory journal to disk (desktop).

Commands

`set_items`

Store a key-value pair in the widget data store.

invoke('plugin:widgets|set_items', { key, value, group })

Argument (JS)	Rust parameter	Type
`key`	`key`	`String`
`value`	`value`	`String`
`group`	`group`	`Option<String>`

Returns bool. Rust: async fn. Permission: widgets:allow-set-items. JS wrapper: setItems().

`get_items`

Read a previously stored value from the widget data store.

invoke('plugin:widgets|get_items', { key, group })

Argument (JS)	Rust parameter	Type
`key`	`key`	`String`
`group`	`group`	`Option<String>`

Returns Option<String>. Rust: async fn. Permission: widgets:allow-get-items. JS wrapper: getItems().

`set_register_widget`

invoke('plugin:widgets|set_register_widget', { widgets })

Argument (JS)	Rust parameter	Type
`widgets`	`widgets`	`Vec<String>`

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-set-register-widget. JS wrapper: setRegisterWidget().

`reload_all_timelines`

Reload all registered widget timelines.

invoke('plugin:widgets|reload_all_timelines')

No arguments.

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-reload-all-timelines. JS wrapper: reloadAllTimelines().

`reload_timelines`

Reload timelines for a specific widget kind or class.

invoke('plugin:widgets|reload_timelines', { ofKind })

Argument (JS)	Rust parameter	Type
`ofKind`	`of_kind`	`String`

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-reload-timelines. JS wrapper: reloadTimelines().

`request_widget`

Request the OS to pin (add) a widget to the home screen.

invoke('plugin:widgets|request_widget')

No arguments.

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-request-widget. JS wrapper: requestWidget().

`create_widget_window`

Create a frameless, transparent desktop widget window.

invoke('plugin:widgets|create_widget_window', { mut config })

Argument (JS)	Rust parameter	Type
`mut config`	`mut config`	`WidgetWindowConfig`

Returns bool. Rust: async fn. Permission: widgets:allow-create-widget-window. JS wrapper: createWidgetWindow().

`close_widget_window`

Close a previously created desktop widget window.

invoke('plugin:widgets|close_widget_window', { label })

Argument (JS)	Rust parameter	Type
`label`	`label`	`String`

Returns bool. Rust: async fn. Permission: widgets:allow-close-widget-window. JS wrapper: closeWidgetWindow().

`set_widget_config`

Send a declarative UI configuration to native widgets.

invoke('plugin:widgets|set_widget_config', { config, group, widgetId, skipReload, instance })

Argument (JS)	Rust parameter	Type
`config`	`config`	`WidgetConfig`
`group`	`group`	`Option<String>`
`widgetId`	`widget_id`	`String`
`skipReload`	`skip_reload`	`Option<bool>`
`instance`	`instance`	`Option<String>`

Returns ApplyOutcome. Rust: async fn. Permission: widgets:allow-set-widget-config. JS wrapper: setWidgetConfig().

`set_widget_config_from_path`

Load a WidgetConfig JSON file from disk, then apply it like set_widget_config.

path must be readable by the app process (absolute path or resolved resource / app-data path). Network URLs are not supported.

invoke('plugin:widgets|set_widget_config_from_path', { path, group, widgetId, skipReload, instance })

Argument (JS)	Rust parameter	Type
`path`	`path`	`String`
`group`	`group`	`Option<String>`
`widgetId`	`widget_id`	`String`
`skipReload`	`skip_reload`	`Option<bool>`
`instance`	`instance`	`Option<String>`

Returns ApplyOutcome. Rust: async fn. Permission: widgets:allow-set-widget-config-from-path. JS wrapper: setWidgetConfigFromPath().

`get_widget_config`

Read the current widget UI configuration from the data store.

invoke('plugin:widgets|get_widget_config', { group, widgetId, instance })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`
`widgetId`	`widget_id`	`String`
`instance`	`instance`	`Option<String>`

Returns Option<WidgetConfig>. Rust: async fn. Permission: widgets:allow-get-widget-config. JS wrapper: getWidgetConfig().

`set_widget_data`

Values for {{data.…}} without resending the layout. null clears them.

invoke('plugin:widgets|set_widget_data', { widgetId, data, instance, group, skipReload })

Argument (JS)	Rust parameter	Type
`widgetId`	`widget_id`	`String`
`data`	`data`	`serde_json::Value`
`instance`	`instance`	`Option<String>`
`group`	`group`	`Option<String>`
`skipReload`	`skip_reload`	`Option<bool>`

Returns bool. Rust: async fn. Permission: widgets:allow-set-widget-data. JS wrapper: setWidgetData().

`set_widget_state`

Change a placement's local state ({{state.…}}) like a set tap does: operators $toggle / $inc / $dec, null removes a key, patch: null clears the stored state. Returns the merged state (defaults included) and emits widget-state-changed.

invoke('plugin:widgets|set_widget_state', { widgetId, patch, instance, group, skipReload })

Argument (JS)	Rust parameter	Type
`widgetId`	`widget_id`	`String`
`patch`	`patch`	`serde_json::Value`
`instance`	`instance`	`Option<String>`
`group`	`group`	`Option<String>`
`skipReload`	`skip_reload`	`Option<bool>`

Returns serde_json::Value. Rust: async fn. Permission: widgets:allow-set-widget-state. JS wrapper: setWidgetState().

`get_widget_state`

A placement's merged local state: config state defaults, then the stored state.

invoke('plugin:widgets|get_widget_state', { widgetId, instance, group })

Argument (JS)	Rust parameter	Type
`widgetId`	`widget_id`	`String`
`instance`	`instance`	`Option<String>`
`group`	`group`	`Option<String>`

Returns serde_json::Value. Rust: async fn. Permission: widgets:allow-get-widget-state. JS wrapper: getWidgetState().

`register_activity_template`

Store a Live Activity layout under name (activity-template:{name}): activities with template: name then send only data. null removes it.

invoke('plugin:widgets|register_activity_template', { name, layout, group })

Argument (JS)	Rust parameter	Type
`name`	`name`	`String`
`layout`	`layout`	`serde_json::Value`
`group`	`group`	`Option<String>`

Returns bool. Rust: async fn. Permission: widgets:allow-register-activity-template. JS wrapper: registerActivityTemplate().

`set_widget_instances`

Choices for the per-placement picker (Apple Edit Widget sheet; listed for Android and desktop so the app can label placements).

invoke('plugin:widgets|set_widget_instances', { widgetId, instances, group })

Argument (JS)	Rust parameter	Type
`widgetId`	`widget_id`	`String`
`instances`	`instances`	`Vec<WidgetInstanceOption>`
`group`	`group`	`Option<String>`

Returns bool. Rust: async fn. Permission: widgets:allow-set-widget-instances. JS wrapper: setWidgetInstances().

`get_active_widgets`

Widgets placed right now (see ActiveWidget).

invoke('plugin:widgets|get_active_widgets', { group })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`

Returns Vec<ActiveWidget>. Rust: async fn. Permission: widgets:allow-get-active-widgets. JS wrapper: getActiveWidgets().

`start_activity`

Start (or update, when the id runs) a live activity.

invoke('plugin:widgets|start_activity', { content, group })

Argument (JS)	Rust parameter	Type
`content`	`content`	`ActivityContent`
`group`	`group`	`Option<String>`

Returns ActivityHandle. Rust: async fn. Permission: widgets:allow-start-activity. JS wrapper: startActivity().

`update_activity`

Replace the content of a running live activity.

invoke('plugin:widgets|update_activity', { content, group })

Argument (JS)	Rust parameter	Type
`content`	`content`	`ActivityContent`
`group`	`group`	`Option<String>`

Returns bool. Rust: async fn. Permission: widgets:allow-update-activity. JS wrapper: updateActivity().

`end_activity`

End a live activity; dismissAfterMs keeps the final state visible that long (iOS / desktop; Android removes the notification at once). content is the final state; dismissalPolicy "default" | "immediate" (dismissAfterMs wins).

invoke('plugin:widgets|end_activity', { id, dismissAfterMs, content, dismissalPolicy, group })

Argument (JS)	Rust parameter	Type
`id`	`id`	`String`
`dismissAfterMs`	`dismiss_after_ms`	`Option<u64>`
`content`	`content`	`Option<ActivityContent>`
`dismissalPolicy`	`dismissal_policy`	`Option<String>`
`group`	`group`	`Option<String>`

Returns bool. Rust: async fn. Permission: widgets:allow-end-activity. JS wrapper: endActivity().

`get_widget_push_token`

WidgetKit push token (hex) for server-driven widget reloads; null where none exists.

invoke('plugin:widgets|get_widget_push_token', { group })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`

Returns Option<String>. Rust: async fn. Permission: widgets:allow-get-widget-push-token. JS wrapper: getWidgetPushToken().

`get_activity_push_to_start_token`

iOS 17.2+ push-to-start token (hex) for your APNs server; null elsewhere / not yet issued.

invoke('plugin:widgets|get_activity_push_to_start_token')

No arguments.

Returns Option<String>. Rust: async fn. Permission: widgets:allow-get-activity-push-to-start-token. JS wrapper: getActivityPushToStartToken().

`can_promote_activities`

Android 16+: whether ongoing activity notifications may be promoted to Live Updates (status-bar chip, lock screen). true where the question does not apply.

invoke('plugin:widgets|can_promote_activities')

No arguments.

Returns bool. Rust: async fn. Permission: widgets:allow-can-promote-activities. JS wrapper: canPromoteActivities().

`open_activity_promotion_settings`

Android: opens the system setting that allows Live Updates for this app. false when there is no such screen (other platforms, older Android).

invoke('plugin:widgets|open_activity_promotion_settings')

No arguments.

Returns bool. Rust: async fn. Permission: widgets:allow-open-activity-promotion-settings. JS wrapper: openActivityPromotionSettings().

`list_activities`

Ids of the running live activities this app started.

invoke('plugin:widgets|list_activities')

No arguments.

Returns Vec<String>. Rust: async fn. Permission: widgets:allow-list-activities. JS wrapper: listActivities().

`activity_island`

Desktop activity island page → host: expanded grows / shrinks the island (hover, click), focus brings a minimal activity to the pill. Returns what the island shows (null on mobile or without an island). Used by the built-in renderer.

invoke('plugin:widgets|activity_island', { expanded, focus })

Argument (JS)	Rust parameter	Type
`expanded`	`expanded`	`Option<bool>`
`focus`	`focus`	`Option<String>`

Returns Option<serde_json::Value>. Rust: async fn. Permission: widgets:allow-activity-island.

`widget_action`

Trigger a widget-action event via the Rust plugin.

invoke('plugin:widgets|widget_action', { action, payload, widgetId, group })

Argument (JS)	Rust parameter	Type
`action`	`action`	`String`
`payload`	`payload`	`Option<String>`
`widgetId`	`widget_id`	`Option<String>`
`group`	`group`	`Option<String>`

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-widget-action. JS wrapper: widgetAction().

`poll_pending_actions`

invoke('plugin:widgets|poll_pending_actions', { group })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`

Returns Vec<crate::WidgetActionEnvelope>. Rust: async fn. Permission: widgets:allow-poll-pending-actions.

`report_receipt`

Report that a renderer painted a config (desktop widget.html / tests). Native widgets write receipts themselves; this is for the host webview path.

invoke('plugin:widgets|report_receipt', { mut receipt })

Argument (JS)	Rust parameter	Type
`mut receipt`	`mut receipt`	`crate::receipt::WidgetRenderReceipt`

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-report-receipt. JS wrapper: reportReceipt().

`get_widget_diagnostics`

Live widget instances that recently rendered for group.

invoke('plugin:widgets|get_widget_diagnostics', { group })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`

Returns Vec<crate::receipt::WidgetRenderReceipt>. Rust: plain (sync) fn. Permission: widgets:allow-get-widget-diagnostics. JS wrapper: getWidgetDiagnostics().

`get_widget_trace`

Host delivery journal + receipt history for group. Active in debug builds or when WIDGET_DEBUG=1.

invoke('plugin:widgets|get_widget_trace', { group, sinceMs })

Argument (JS)	Rust parameter	Type
`group`	`group`	`Option<String>`
`sinceMs`	`since_ms`	`Option<u64>`

Returns crate::trace::WidgetTrace. Rust: plain (sync) fn. Permission: widgets:allow-get-widget-trace. JS wrapper: getWidgetTrace().

`flush_widget_trace`

Force-flush the in-memory journal to disk (desktop).

invoke('plugin:widgets|flush_widget_trace')

No arguments.

Returns bool. Rust: plain (sync) fn. Permission: widgets:allow-flush-widget-trace. JS wrapper: flushWidgetTrace().

Rust API

This page is a narrative guide for calling the plugin from Rust. The full type reference lives on docs.rs/tauri-plugin-widgets.

Plugin config

Optional. Everything under plugins.widgets in tauri.conf.json has a default: