Wox Plugin Settings Patterns

This document contains self-contained settings examples. Use it when plugin.json needs SettingDefinitions, validators, dynamic settings, or advanced table/select controls.

Choose The Right Pattern

Use a textbox for free-form string input.
Add validators when empty or non-numeric values should be rejected.
Use a select for a fixed option list.
Use selectAIModel when the value should come from Wox-configured AI models.
Use a table when users need to add, edit, or delete rows.
Use a dynamic placeholder when the visible setting depends on current runtime state.
Decide whether each setting is platform-specific before publishing it. Normal plugin settings are eligible for cloud sync, so values that only work on one OS should use IsPlatformSpecific: true.

Cloud Sync Decision Checklist

Keep IsPlatformSpecific: false for account IDs, API keys, remote service hosts, shared feature toggles, and preferences that mean the same thing on Windows, macOS, and Linux.
Set IsPlatformSpecific: true for local directories, executable paths, shell commands, hotkeys, browser profiles, app paths, and system integration settings.
Use DisabledInPlatforms only to disable a setting on selected platforms. It does not isolate stored values.
When saving settings from code, pass the same platform-specific flag that the setting metadata declares.

Pattern 1: Textbox With Validators

json

{
  "Type": "textbox",
  "Value": {
    "Key": "timeout_ms",
    "Label": "Timeout",
    "DefaultValue": "300",
    "Tooltip": "Delay before query execution",
    "Suffix": "ms",
    "MaxLines": 1,
    "Validators": [
      {
        "Type": "is_number",
        "Value": {
          "IsInteger": true,
          "IsFloat": false
        }
      }
    ],
    "Style": {
      "Width": 220
    }
  }
}

Use not_empty for required strings:

json

{
  "Type": "textbox",
  "Value": {
    "Key": "api_key",
    "Label": "API Key",
    "DefaultValue": "",
    "Validators": [
      {
        "Type": "not_empty",
        "Value": {}
      }
    ]
  }
}

Pattern 2: Select And Multi-Select

json

{
  "Type": "select",
  "Value": {
    "Key": "theme",
    "Label": "Theme",
    "DefaultValue": "dark",
    "Tooltip": "Choose one theme",
    "IsMulti": false,
    "Options": [
      { "Label": "Dark", "Value": "dark" },
      { "Label": "Light", "Value": "light" }
    ],
    "Validators": [],
    "Style": {}
  }
}

Multi-select example:

json

{
  "Type": "select",
  "Value": {
    "Key": "providers",
    "Label": "Providers",
    "DefaultValue": "",
    "IsMulti": true,
    "Options": [
      { "Label": "All", "Value": "all", "IsSelectAll": true },
      { "Label": "OpenAI", "Value": "openai" },
      { "Label": "Anthropic", "Value": "anthropic" }
    ]
  }
}

Pattern 3: AI Model Selector

json

{
  "Type": "selectAIModel",
  "Value": {
    "Key": "default_model",
    "Label": "Default Model",
    "DefaultValue": "",
    "Tooltip": "Choose one configured AI model",
    "Validators": [],
    "Style": {}
  }
}

Pattern 4: Editable Table

Use tables when a plugin needs a list of structured items.

json

{
  "Type": "table",
  "Value": {
    "Key": "shortcuts",
    "DefaultValue": "[]",
    "Title": "Shortcuts",
    "Tooltip": "Manage saved shortcuts",
    "SortColumnKey": "name",
    "SortOrder": "asc",
    "MaxHeight": 420,
    "Columns": [
      {
        "Key": "name",
        "Label": "Name",
        "Type": "text",
        "Width": 120,
        "Validators": [{ "Type": "not_empty", "Value": {} }]
      },
      {
        "Key": "enabled",
        "Label": "Enabled",
        "Type": "checkbox",
        "Width": 70
      },
      {
        "Key": "model",
        "Label": "Model",
        "Type": "selectAIModel",
        "Width": 130
      }
    ]
  }
}

Useful table column options:

TextMaxLines: multi-line text editor for text columns
SelectOptions: option list for select columns
HideInTable: keep field in the edit dialog only
HideInUpdate: show field in the table only

Pattern 5: Dynamic Setting

Use dynamic when the displayed setting should be computed at runtime. The dynamic entry itself is only a placeholder; the plugin API callback must return the actual setting item.

Manifest:

json

{
  "Type": "dynamic",
  "Value": {
    "Key": "separator_preview"
  }
}

Node.js callback pattern:

typescript

await api.OnGetDynamicSetting(ctx, async (_ctx, key) => {
  if (key === "separator_preview") {
    return {
      Type: "label",
      Value: {
        Content: "Preview: 1,234.56",
        Tooltip: "",
        Style: {},
      },
    };
  }

  return {
    Type: "label",
    Value: {
      Content: "Unknown setting",
      Tooltip: "",
      Style: {},
    },
  };
});

Python callback pattern:

python

from wox_plugin import (
    PluginSettingDefinitionItem,
    PluginSettingDefinitionType,
    PluginSettingValueLabel,
)

async def _on_get_dynamic_setting(ctx, key):
    if key == "separator_preview":
        return PluginSettingDefinitionItem(
            type=PluginSettingDefinitionType.LABEL,
            value=PluginSettingValueLabel(content="Preview: 1,234.56"),
        )

    return PluginSettingDefinitionItem(
        type=PluginSettingDefinitionType.LABEL,
        value=PluginSettingValueLabel(content="Unknown setting"),
    )

Pattern 6: Platform-Specific Settings

Use these top-level properties on any setting item whose value should differ by platform after cloud sync:

json

{
  "Type": "textbox",
  "Value": {
    "Key": "executable_path",
    "Label": "Executable Path",
    "DefaultValue": ""
  },
  "DisabledInPlatforms": ["linux"],
  "IsPlatformSpecific": true
}

DisabledInPlatforms: disable the control on selected platforms
IsPlatformSpecific: store a different value per platform

Do not mark shared credentials or remote service configuration as platform-specific unless the service itself requires per-platform values:

json

{
  "Type": "textbox",
  "Value": {
    "Key": "api_key",
    "Label": "API Key",
    "DefaultValue": ""
  },
  "IsPlatformSpecific": false
}

Node.js Notes

SaveSetting requires isPlatformSpecific. Use the same value declared by the matching setting definition, especially for settings saved from actions or dynamic UI.
OnGetDynamicSetting is the runtime hook for dynamic.
Keep settings JSON-compatible; avoid relying on repo-local type files being present.

Python Notes

Helper builders are intentionally limited.
For select, table, validators, or dynamic, build PluginSettingDefinitionItem and value objects directly.
save_setting requires is_platform_specific. Use the same value declared by the matching setting definition, especially for settings saved from actions or dynamic UI.