Skip to main content

Plugin settings pages (settingsPages)

Plugins often need their own configuration UI (toggles, API keys, default behavior). Instead of scattering Settings buttons across plugin pages, put the settings UI inside the Launcher: in Settings → Plugins → Plugin settings (Settings → Plugins → Plugin Settings) the left side lists one vertical tab per plugin and the right side shows the settings UI that plugin provides. Users can find it and do not get lost.

Quick start

Step 1: Declare a Plugin settings page (Plugin Settings) in contributes.settingsPages of manifest.json (the relative path of an HTML file inside the .qplugin package):
Step 2: Write dist/settings.html inside the package. It is a plain HTML page running in exactly the same Sandbox environment as the plugin’s main page (iframe Sandbox + full __PLUGIN_API__ Bridge + injected theme variables); use getSettings / setSettings to read and write the plugin’s own configuration:
Step 3: Pack the .qplugin, install it, and enable the plugin. Settings → Plugins → Plugin settings now shows a tab named after the plugin, and opening it shows the UI you wrote.

Runtime environment

  • iframe Sandbox: <iframe sandbox="allow-scripts"> rendered through srcdoc, isolated from the main interface DOM/CSS; every __PLUGIN_API__ method is available (same Permission checks as plugin pages)
  • Theme following: the Launcher injects the theme CSS variables (--foreground / --background / --primary / --border, and so on) and .p-* Component styles, and light and dark themes switch automatically; you do not need to handle it yourself
  • Container size: the content area on the right is about 560px high and adapts in width; when the page overflows it scrolls internally, so just lay out your root element at 100% height
  • Configuration persistence: getSettings / setSettings read and write plugins/{plugin id}/settings.json, and setSettings merges by key (concurrency-safe), so you never write the whole object at once

Jump straight to the settings page

When you provide a Settings button on a plugin page or inside an Overlay window, jump with openPluginSettings; the Launcher opens Plugin settings and selects your plugin:
  • Permission: config:read
  • If the target plugin declares no settingsPages, the plugin settings area still opens (at its default position)
  • If one plugin declares several settings pages, the first one is selected

Rules and Lifecycle (lifecycle)

Consumers of plugin configuration (widgets, Overlay windows) should also call getSettings at runtime and apply the latest values; the settings page only writes, and it does not broadcast changes automatically.