Skip to main content

Dashboard custom widgets

Dashboard custom widgets (QWidget) let you describe your own home card in a single .qwidget file: layout, text, buttons, inputs, media, data sources, triggers, and TypeScript functions. It is a separate mechanism from plugin dashboard:widgets:

Open the editor

  1. On the home page, click Edit layout in the top-right corner.
  2. Click ＋ on the toolbar.
  3. In the Custom widgets section, click New widget.
The editor has two tabs:
  • XML: widget structure with line numbers, syntax highlighting, folding, search, schema completion, and live validation.
  • Functions: edit Function.Script TypeScript with completion for Input / Inputs / Data / Resources / Results / Host, plus Run.
The right side shows preview, domain confirmation, and widget information.

First widget

After saving, the widget appears at the end of the home grid. You can drag, resize, hide, and restore it like built-in widgets.

Import and export

  • Import from URL: enter https://.../*.qwidget, fetch and validate it, then load it. Once saved, the widget checks for updates silently every 6 hours.
  • Import file: choose a local .qwidget / .xml file. Relative paths are based on that file’s directory.
  • Export file: save the current XML. Local Widget.Using Name="..." dependencies are not inlined; the editor warns about missing dependencies before export.

Domain confirmation

The right panel lists every domain the widget will access:
  • Data Source="Url" sources
  • Widget UpdateUrl / online import source
  • Widget.Using Url nested widgets
  • Static Image / Media URLs
All domains must be checked before saving. Static images/media only load from confirmed domains; data requests go through the backend proxy with https:443, no redirects, and private-address blocking.

Updates and risk

Online widgets check for updates silently every 6 hours; data, text, and layout updates do not prompt. Custom widgets can run TypeScript, execute commands, call plugin APIs, and read local files, so:
  • Confirm when a remote widget import or update adds/changes executable content; decline keeps the old XML.
  • Literal commands in local widgets and user-input commands do not prompt on every click.
  • Commands generated from online data are confirmed by final command hash.
  • See Security and trust.
  • Only use widgets you trust. The launcher developers are not responsible for risks caused by custom widgets.

Storage and limits

  • Definitions and data caches are stored in local localStorage; layout uses the existing home grid storage.
  • XML ≤256KB, depth 16, 1000 elements, 8 data sources, 200 rendered list items.
  • Online text/JSON/XML ≤1MB, binary ≤8MB.
  • Nesting depth ≤5, up to 20 nested instances per parent.
  • Function scripts ≤64KB, default timeout 3 seconds (max 10 seconds).

Next