tauri-plugin-widgets

Appearance

Core vs extended ​

Not every element is held to the same cross-platform bar. Pixel-identical Core+Extended everywhere is not possible — Adaptive Cards, Glance, and WidgetKit each miss overlays, live timers, or network fetch. Aim for a portable Core and treat Extended as best-effort.

Core elements versus extended best-effort elements

Core ​

Core means the element is present on every matrix platform and keeps its IR semantics (layout role, text, tap target, bitmap image, …). It does not mean identical pixels. Degraded cells (for example Windows zstack / shape, or image.systemName outside Apple) are documented in the matrix below — check them before assuming Board/Glance look like WidgetKit.

The authoritative list is CORE_ELEMENTS in src/snapshot.rs (also mirrored under Capability matrix). Prefer that set when you need broad coverage.

Portable Core checklist ​

  • Prefer solid backgrounds (or accept gradient bake / first-stop degradation).
  • Prefer image.data / image.url over image.systemName for Board/Android parity — SF Symbols exist only on Apple; elsewhere the feature row is degraded (glyph/emoji).
  • Remote image.url is prefetched on the host where wired — do not rely on live network inside the extension process.
  • Prefer Desktop webview when you need true overlays, live timers, or full SVG canvas.

Extended ​

Extended (EXTENDED_ELEMENTS) is best-effort and platform-dependent. Expect degraded or unsupported cells (live timer on Windows Board, chart rasterization on Adaptive Cards). The live list is in the matrix section.

How to read the matrix ​

LevelMeaning
fullSupported with the intended semantics
degradedRenders with known limitations (see footnotes under the matrix)
unsupportedDo not rely on this feature on that platform

Desktop column: one IR path shared by the desktop webview hosts — WKWebView (macOS window), WebView2 (Windows window), and webkit2gtk (Linux). Semantics match; differences are system fonts and CSS engine version. Linux also has its own golden stand (tests/golden/linux/) for pinning / layer-shell, but it is not a sixth matrix column. Windows Widgets Board (Adaptive Cards) is the separate Windows column.

Showcase presets exercise both tiers; docs build fails if a schema element has zero fixture coverage.

Runtime behavior ​

Capability warnings on setWidgetConfig ​

Each setWidgetConfig runs validate_config for the current host platform and emits log::warn! via log_capabilities when a used element or feature is degraded / unsupported (for example image.systemName outside Apple). Warnings are advisory — the write still proceeds. There is no public guest API to dry-run validation yet; treat host logs (and the matrix) as the source of truth before shipping a config.

Skipped elements in render receipts ​

When a renderer cannot express a node (common on Adaptive Cards without the rasterize feature, or after a flatten), the element is recorded on the render receipt as skipped: [{ type, reason }], not as a silent hole you must guess about.

Inspect recent receipts with getWidgetDiagnostics(group):

ts
import { getWidgetDiagnostics } from "tauri-plugin-widgets-api";

const receipts = await getWidgetDiagnostics("com.example.widgets");
for (const r of receipts) {
  if (r.skipped?.length) {
    console.warn(r.widgetId, r.skipped);
    // e.g. [{ type: "canvas", reason: "adaptive-cards: enable crate feature `rasterize`" }]
  }
}

Desktop / debug builds can also use getWidgetTrace(group) for the host journal plus receipt history.

Capability matrix ​

Table is authored in src/capabilities.rs; this page embeds it automatically. Refresh with cargo test --lib capabilities::write_docs::capability_matrix_doc_matches (delete docs/guide/_generated/capability-matrix.md first if drifted) then pnpm docs:generate.

Element lists ​

Core (CORE_ELEMENTS in src/snapshot.rs): vstack, hstack, zstack, container, grid, text, image, spacer, divider, progress, button, link, shape

Extended (EXTENDED_ELEMENTS): gauge, toggle, date, chart, list, timer, canvas, label

Core ​

ElementiOSmacOSAndroidDesktopWindows
vstackfullfullfullfullfull1
hstackfullfullfullfullfull1
zstackfullfullfullfulldegraded2
containerfullfullfullfullfull1
gridfullfullfullfullfull1
textfullfullfullfullfull1
imagefullfullfull3fullfull4
spacerfullfullfullfullfull1
dividerfullfullfullfullfull1
progressfullfullfullfullfull1
buttonfullfullfullfullfull1
linkfullfullfullfullfull1
shapefullfullfullfulldegraded5

Extended ​

ElementiOSmacOSAndroidDesktopWindows
gaugefullfullfullfulldegraded5
togglefullfullfullfullfull1
datefullfullfullfullfull1
chartfullfullfull6full7degraded5
listfullfullfull8fulldegraded9
timerfullfullfull10full11degraded12
canvasfullfulldegraded13full7degraded5
labelfullfullfullfullfull1

Feature notes ​

FeatureiOSmacOSAndroidDesktopWindows
image.urlfull14full14full15fullfull16
image.systemNamefull17full17degraded18degraded18degraded19
background.gradientfull20full20full21full22degraded23
canvas.pathfull24full24full25full26degraded27
timer.livefull28full28full10full29degraded30

Choosing a surface set ​

Pick the platforms you ship, then stay in the full set for that profile. Degraded cells still render, but check the Notes and element pages.

Apple only ​

Platforms: iOS + macOS.

Apple + Android ​

Platforms: iOS + macOS + Android.

All five matrix columns ​

Platforms: iOS + macOS + Android + Desktop + Windows.

Notes ​

  1. Adaptive Cards 1.5
  2. rasterized PNG overlay when possible; else flattened Container
  3. url via localPath preprocess; see image.systemName
  4. url/data URI; see image.systemName
  5. rasterized PNG
  6. bitmap bar/line/area/pie
  7. SVG
  8. Column chunking; soft cap ~50 items
  9. Adaptive Cards Table
  10. Chronometer via AndroidRemoteViews
  11. setInterval
  12. provider minute push + static TextBlock
  13. bitmap canvas (full SVG path via PathParser)
  14. host prefetch to data URI on setWidgetConfig
  15. preprocess to localPath on setWidgetConfig
  16. Adaptive Cards Image.url
  17. SF Symbols
  18. SF→Material / emoji map (not SF Symbols)
  19. emoji TextBlock by default; glyph PNG Image with feature rasterize
  20. linear/radial/angular SwiftUI
  21. baked bitmap at LocalSize / frame
  22. linear/radial/angular CSS/SVG
  23. rasterized PNG backgroundImage when rasterize enabled
  24. SVG path grammar
  25. PathParser full SVG path
  26. SVG path
  27. rasterized via SVG
  28. Text(..., .timer)
  29. JS interval
  30. provider pushes UpdateWidget ~1/min

Released under the MIT License. · Contributing

Copyright © s00d