Skip to main content

Plugin Field Types Reference

This document provides a quick reference for all available field types that can be used in plugin settings and action definitions.

Overview​

Both settings and actions in your plugin manifest support various field types for collecting user input.

Property support is not identical between settings and actions:

  • Settings support disabled and richer string-length validation (minLength/maxLength).
  • Both settings and action fields support multi-select on select via multiple.
  • Both settings and action fields support freeform select input via allowTyping.
  • Action fields support runtime-oriented options such as allowVariables.

Easy-to-miss settings-only structured types:

  • named_map - best when users should define labeled entries such as name -> URL, name -> file, or name -> selector
  • json - best when the value is inherently structured and should be edited as JSON
  • roi - best when the value is a rectangular region with x/y/width/height

Supported Field Types​

Text Input Types​

text​

Single-line text input with optional variable support (set allowVariables: true).

{
  "key": "username",
  "label": "Username",
  "type": "text",
  "placeholder": "Enter username",
  "helperText": "Supports variables like {{username}}"
}

Properties:

  • placeholder - Placeholder text
  • validation.pattern - Regex pattern for validation
  • validation.minLength - Minimum character length (settings)
  • validation.maxLength - Maximum character length (settings)
  • allowVariables - Enable template variables for action fields

email​

Email address input with built-in validation and optional variable support (set allowVariables: true).

{
  "key": "userEmail",
  "label": "Email Address",
  "type": "email",
  "placeholder": "user@example.com",
  "required": true
}

Properties:

  • Same as text with automatic email input validation

url​

URL input with built-in validation and optional variable support (set allowVariables: true).

{
  "key": "webhookUrl",
  "label": "Webhook URL",
  "type": "url",
  "placeholder": "https://example.com/webhook",
  "required": true
}

Properties:

  • Same as text with automatic URL input validation

password​

Password input with hidden characters.

{
  "key": "apiKey",
  "label": "API Key",
  "type": "password",
  "placeholder": "Enter your API key",
  "helperText": "Get this from your service dashboard",
  "required": true
}

Properties:

  • Same as text but displays hidden characters
  • Actions do not currently expose password fields

textarea​

Multi-line text input with optional variable support (set allowVariables: true) and configurable rows.

{
  "key": "message",
  "label": "Message",
  "type": "textarea",
  "placeholder": "Enter your message",
  "rows": 6,
  "helperText": "Multi-line text with variable support"
}

Properties:

  • rows - Number of visible text rows (default: 4)
  • placeholder - Placeholder text
  • validation.pattern - Regex pattern for validation
  • validation.minLength - Minimum character length (settings)
  • validation.maxLength - Maximum character length (settings)
  • allowVariables - Enable template variables for action fields

Date/Time Types​

datetime​

Native local date/time picker.

{
  "key": "publishAt",
  "label": "Publish At",
  "type": "datetime",
  "defaultValue": "2026-03-01T15:30"
}

Properties:

  • Returns a local datetime string in YYYY-MM-DDTHH:mm format
  • allowVariables - Enable template variables for action fields

Numeric Input Types​

number​

Numeric input with optional constraints.

{
  "key": "volume",
  "label": "Volume",
  "type": "number",
  "defaultValue": 50,
  "validation": {
    "min": 0,
    "max": 100
  }
}

Properties:

  • validation.min - Minimum value (settings and actions)
  • validation.max - Maximum value (settings and actions)
  • min - Minimum value (action fields)
  • max - Maximum value (action fields)
  • allowVariables - Enable template variables for action fields

slider​

Numeric slider input with visual feedback.

{
  "key": "brightness",
  "label": "Brightness",
  "type": "slider",
  "defaultValue": 100,
  "min": 0,
  "max": 255,
  "step": 5
}

Properties:

  • min - Minimum value (action fields)
  • max - Maximum value (action fields)
  • step - Increment step (action fields)
  • validation.min - Minimum value (settings and actions)
  • validation.max - Maximum value (settings and actions)

Selection Types​

select​

Dropdown selection from predefined options.

{
  "key": "mode",
  "label": "Mode",
  "type": "select",
  "allowTyping": true,
  "defaultValue": "normal",
  "options": [
    { "label": "Normal", "value": "normal" },
    { "label": "Fast", "value": "fast" },
    { "label": "Slow", "value": "slow" }
  ]
}

Properties:

  • options - Array of objects with label and value properties (required)
  • allowTyping - Allow typing a custom value in addition to dropdown options (settings and actions)
  • multiple - Allow selecting multiple options; value becomes an array (settings and actions)
  • allowVariables - Enable template variable insertion (action fields)
  • dynamicOptions - Allow runtime option updates from plugin code (settings and actions)

Multi-select with select​

To allow multiple selections, keep type: "select" and set multiple: true.

{
  "key": "enabledGames",
  "label": "Enabled Games",
  "type": "select",
  "multiple": true,
  "allowTyping": true,
  "defaultValue": ["valorant", "rocket_league"],
  "options": [
    { "label": "Valorant", "value": "valorant" },
    { "label": "Rocket League", "value": "rocket_league" },
    { "label": "Overwatch", "value": "overwatch" }
  ]
}

Properties:

  • options - Array of objects with label and value properties (required)
  • Stored value is always an array of selected option values
  • Use allowTyping: true to allow user-defined values in addition to provided options

Boolean Types​

checkbox​

Boolean checkbox input.

{
  "key": "enableNotifications",
  "label": "Enable Notifications",
  "type": "checkbox",
  "defaultValue": true
}

Properties:

  • Accepts boolean values (true/false)

toggle​

Boolean toggle control.

{
  "key": "autoStart",
  "label": "Auto Start",
  "type": "toggle",
  "defaultValue": false,
  "helperText": "Automatically start on load"
}

Properties:

  • Accepts boolean values (true/false)

Special Input Types​

color​

Color picker that outputs hex color values.

{
  "key": "backgroundColor",
  "label": "Background Color",
  "type": "color",
  "defaultValue": "#000000",
  "helperText": "Choose a background color"
}

Properties:

  • Outputs hex color strings (e.g., #FF0000)
  • Default value should be in hex format

file​

File path input with file browser dialog.

{
  "key": "audioFile",
  "label": "Audio File",
  "type": "file",
  "helperText": "Select an audio file to play"
}

Properties:

  • Opens native file picker dialog
  • Returns absolute file path as string
  • allowVariables - Enable template variable insertion for action fields

media​

Media path input with a picker dialog for local files or remote URLs.

{
  "key": "postMedia",
  "label": "Media",
  "type": "media",
  "helperText": "Choose a local file or paste a remote URL"
}

Properties:

  • Opens a media picker dialog with local-file and URL tabs
  • Returns a single string value
  • Local selections return an absolute file path string
  • Remote selections return the entered URL string
  • allowVariables - Enable template variable insertion for action fields

named_map (settings only)​

Name-to-value map editor. Users can add multiple rows, where each row has:

  • name (unique key by default)
  • value (typed with valueType / valueField)
{
  "key": "sounds",
  "label": "Named Sounds",
  "type": "named_map",
  "valueType": "file",
  "outputMode": "array"
}

Properties:

  • valueType - Row value input type (text, datetime, number, select, checkbox/toggle, file, json)
  • valueField - Optional full field config override for the row value editor (label, placeholder, options, rows, etc.)
  • nameKey / valueKey - Customize serialized payload keys
  • outputMode - Store as array (default) or object/map
  • objectValueMode - For object output, choose object (default), value, or path
  • allowDuplicateNames - Allow duplicate names (default behavior is unique names)

json​

Structured JSON input stored as an object/array value.

{
  "key": "detectionRegion",
  "label": "Detection Region",
  "type": "json",
  "defaultValue": {
    "x": 0.72,
    "y": 0.02,
    "width": 0.27,
    "height": 0.45,
    "unit": "ratio"
  },
  "helperText": "Enter valid JSON."
}

Properties:

  • Renders as a multiline editor in auth/settings UIs
  • Accepts JSON object/array input
  • Stored value is parsed JSON (not raw text)

roi​

Structured region-of-interest editor for screen detection coordinates.

{
  "key": "killFeedRoi",
  "label": "Kill Feed ROI",
  "type": "roi",
  "defaultValue": {
    "x": 0.72,
    "y": 0.02,
    "width": 0.27,
    "height": 0.45,
    "unit": "ratio"
  },
  "helperText": "Use ratio (0-1) or pixels for the detection region."
}

Properties:

  • Renders dedicated x/y/width/height controls plus unit (ratio or pixels)
  • Stored value is an object with { x, y, width, height, unit }
  • ratio values are constrained to 0..1; pixels values are absolute coordinates

Field Type Matrix​

TypeSettingsActionsVariablesValidationNotes
text✅✅With allowVariablespattern, lengthSingle-line input
email✅✅With allowVariablesautoEmail validation
url✅✅With allowVariablesautoURL validation
password✅❌❌pattern, length (settings)Hidden characters
textarea✅✅With allowVariablespattern, length (settings)Multi-line, rows configurable
datetime✅✅With allowVariables-Native datetime picker (YYYY-MM-DDTHH:mm)
number✅✅With allowVariablesmin, maxNumeric input (min/max top-level on actions)
slider✅✅❌min, maxVisual slider (min/max/step top-level on actions)
select✅✅With allowVariables-Dropdown, supports allowTyping; set multiple: true for multi-value; supports dynamicOptions
checkbox✅✅❌-Boolean checkbox
toggle✅✅❌-Boolean toggle control
color✅✅❌-Color picker
file✅✅With allowVariables-File browser
media✅✅With allowVariables on actions-Media picker (local file or URL)
named_map✅❌❌Row-level required checks + duplicate-name checksName-to-value map
json✅❌❌JSON parseStructured object/array editor
roi✅❌❌ROI shape + numeric boundsRegion-of-interest editor

Common Properties​

Setting Fields (config.settings)​

{
  "key": "fieldKey",           // Required: Unique identifier for the field
  "label": "Field Label",       // Required: Display label
  "type": "text",              // Required: Field type
  "placeholder": "...",        // Optional: Placeholder text
  "helperText": "...",         // Optional: Help text below field
  "defaultValue": null,        // Optional: Default value (string, number, boolean, string[], or JSON object/array)
  "required": false,           // Optional: Whether field is required
  "disabled": false,           // Optional: Render read-only in UI
  "hidden": false,             // Optional: Do not render this field in UI
  "visibleIf": {               // Optional: Conditional visibility
    "key": "captureMode",
    "equals": "custom"
  },
  "section": "Detection",      // Optional: Top-level settings tab name
  "sectionOrder": 1,           // Optional: Section/tab sort order (ascending)
  "group": {                   // Optional: In-section grouped container
    "key": "valorant",
    "label": "Valorant Detection",
    "helperText": "Character-specific rules",
    "visibleIf": {
      "key": "enabledGames",
      "equals": "valorant"
    }
  },
  "allowTyping": false,        // Optional: Select fields only
  "rows": 4,                   // Optional: Textarea only
  "options": [],               // Optional: Select fields
  "validation": {              // Optional
    "pattern": "^[a-z]+$",
    "min": 0,
    "max": 100,
    "minLength": 1,
    "maxLength": 100
  }
}

visibleIf follows overlay syntax:

  • visibleIf.key: another field key to check
  • visibleIf.equals: expected value (scalar or array)
  • Match behavior:
    • If current value is array and equals is array: visible if any overlap
    • If current value is array and equals is scalar: visible if array includes scalar
    • If current value is scalar and equals is array: visible if array includes scalar
    • If both scalar: strict equality

group.visibleIf uses the exact same syntax and behavior as visibleIf.

Sections vs Groups (How Layout Works)​

Use both together, but for different jobs:

  • section: creates top-level tabs in plugin settings (Basics, Detection, Advanced, etc.)
  • sectionOrder: controls tab ordering (lower numbers appear first)
  • group: creates a visual container inside a section so related fields are shown together
  • group.visibleIf: hides/shows the entire group container at once
  • field-level visibleIf: still applies per field even when the field is inside a group

Resolution rules used by Lumia:

  • Section label priority: field.section -> group.section -> General
  • Group shorthand is allowed: "group": "my_group" (uses key as label)
  • Group metadata form is allowed: "group": { "key": "my_group", ... }
  • If the same group key is reused, define label/helper text once in the first object-form declaration

UI rendering shape:

Plugin Settings
├─ Tab: Connection            (section="Connection")
│  ├─ Field: API Key
│  └─ Field: Poll Interval
└─ Tab: Detection             (section="Detection")
   ├─ Group: Valorant Rules   (group="valorant_rules")
   │  ├─ Field: Kill Template
   │  └─ Field: ROI
   └─ Group: Rocket Rules     (group="rocket_rules")
      ├─ Field: Goal Template
      └─ Field: ROI

Example A: Sections Only​

Use this when you only need tabs and no inner container.

{
  "config": {
    "settings": [
      {
        "key": "apiKey",
        "label": "API Key",
        "type": "password",
        "section": "Connection",
        "sectionOrder": 1
      },
      {
        "key": "enabledGames",
        "label": "Enabled Games",
        "type": "select",
        "multiple": true,
        "section": "Detection",
        "sectionOrder": 2,
        "options": [
          { "label": "Valorant", "value": "valorant" },
          { "label": "Overwatch", "value": "overwatch" }
        ]
      },
      {
        "key": "cooldownMs",
        "label": "Cooldown (ms)",
        "type": "number",
        "section": "Detection",
        "sectionOrder": 2,
        "defaultValue": 1200
      }
    ]
  }
}

Example B: Sections + Groups​

Use this when one section has multiple sub-areas that should be visually separated.

{
  "config": {
    "settings": [
      {
        "key": "enabledGames",
        "label": "Enabled Games",
        "type": "select",
        "multiple": true,
        "section": "Detection",
        "sectionOrder": 2,
        "options": [
          { "label": "Valorant", "value": "valorant" },
          { "label": "Rocket League", "value": "rocket_league" }
        ]
      },
      {
        "key": "valorantTemplate",
        "label": "Kill Icon Template",
        "type": "file",
        "section": "Detection",
        "group": {
          "key": "valorant_rules",
          "label": "Valorant Rules",
          "helperText": "Templates and ROI for Valorant events.",
          "order": 1,
          "visibleIf": {
            "key": "enabledGames",
            "equals": "valorant"
          }
        }
      },
      {
        "key": "valorantRoi",
        "label": "Valorant ROI",
        "type": "roi",
        "section": "Detection",
        "group": "valorant_rules"
      },
      {
        "key": "rocketLeagueTemplate",
        "label": "Goal Template",
        "type": "file",
        "section": "Detection",
        "group": {
          "key": "rocket_league_rules",
          "label": "Rocket League Rules",
          "order": 2
        },
        "visibleIf": {
          "key": "enabledGames",
          "equals": "rocket_league"
        }
      }
    ]
  }
}

In this example:

  • Detection is one tab (section)
  • valorant_rules and rocket_league_rules are two separate containers (group) inside that tab
  • Valorant container visibility is controlled by group.visibleIf
  • Rocket League field visibility is controlled by field-level visibleIf

Action Fields (config.actions[].fields)​

{
  "key": "fieldKey",           // Required: Unique identifier for the field
  "label": "Field Label",       // Required: Display label
  "type": "text",              // Required: Field type
  "placeholder": "...",        // Optional: Placeholder text
  "helperText": "...",         // Optional: Help text below field
  "defaultValue": null,        // Optional: Any JSON value
  "required": false,           // Optional: Whether field is required
  "allowVariables": false,     // Optional: Enable {{variable}} insertion
  "dynamicOptions": false,     // Optional: Select fields that receive runtime options
  "allowTyping": false,        // Optional: Select fields
  "multiple": false,           // Optional: Select fields
  "rows": 4,                   // Optional: Textarea only
  "min": 0,                    // Optional: Numeric and slider style fields
  "max": 100,                  // Optional: Numeric and slider style fields
  "step": 1,                   // Optional: Slider/number increment
  "options": [],               // Optional: Select fields
  "validation": {              // Optional
    "pattern": "^[a-z]+$",
    "min": 0,
    "max": 100
  }
}

Validation Options​

Validation shape differs between settings and action fields.

Settings Validation (config.settings[].validation)​

{
  "validation": {
    "pattern": "^[a-zA-Z0-9]+$",  // Regex pattern
    "min": 0,                      // Numeric minimum
    "max": 100,                    // Numeric maximum
    "minLength": 5,                // Minimum character length
    "maxLength": 50                // Maximum character length
  }
}

Action Validation (config.actions[].fields[].validation)​

{
  "validation": {
    "pattern": "^[a-zA-Z0-9]+$",  // Regex pattern
    "min": 0,                      // Numeric minimum
    "max": 100                     // Numeric maximum
  }
}

Variable Support​

Variable support for action fields is controlled by allowVariables.

  • Set allowVariables: true to enable variables for any field.
  • When omitted, variables are not enabled (including select fields with allowTyping).

Settings fields do not expose variable insertion in the UI.

Example: Complete Action with Multiple Field Types​

{
  "type": "send_notification",
  "label": "Send Custom Notification",
  "description": "Send a customizable notification with various options",
  "fields": [
    {
      "key": "title",
      "label": "Title",
      "type": "text",
      "required": true,
      "placeholder": "Notification title"
    },
    {
      "key": "message",
      "label": "Message",
      "type": "textarea",
      "required": true,
      "rows": 4,
      "placeholder": "Enter your message here..."
    },
    {
      "key": "priority",
      "label": "Priority",
      "type": "select",
      "defaultValue": "normal",
      "options": [
        { "label": "Low", "value": "low" },
        { "label": "Normal", "value": "normal" },
        { "label": "High", "value": "high" }
      ]
    },
    {
      "key": "backgroundColor",
      "label": "Background Color",
      "type": "color",
      "defaultValue": "#000000"
    },
    {
      "key": "volume",
      "label": "Sound Volume",
      "type": "slider",
      "defaultValue": 50,
      "min": 0,
      "max": 100,
      "step": 5
    },
    {
      "key": "playSound",
      "label": "Play Sound",
      "type": "toggle",
      "defaultValue": true
    },
    {
      "key": "soundFile",
      "label": "Custom Sound File",
      "type": "file",
      "helperText": "Optional: Select a custom sound file"
    }
  ]
}

Common Gotchas​

  • Use toggle for boolean fields: This is the canonical plugin field type for toggle-style boolean inputs.
  • allowVariables is opt-in: Variables are not enabled by default on any field, including select with allowTyping. You must set allowVariables: true explicitly on each action field that needs it.
  • Settings don't support allowVariables: Variable insertion is only available on action fields, not config.settings.
  • password is settings-only: The password type is not available in action fields.
  • named_map, json, roi are settings-only: These structured types are not available in action fields.
  • min/max location differs: For action fields, use top-level min/max; for settings fields, use validation.min/validation.max. Both are accepted but the canonical location differs.
  • multiple: true changes the value shape: When multiple is enabled on select, the stored value is always an array even if one item is selected. Set defaultValue to an array accordingly.
  • dynamicOptions requires a runtime call: Declaring dynamicOptions: true on a field does nothing on its own; your plugin must call lumia.updateActionFieldOptions(...) or lumia.updateSettingsFieldOptions(...) to populate the options.

See Also​