Settings schema

Widgets can expose user-configurable settings. Declare them in manifest.json under settings.schema as an array of controls. NepTunes renders the controls in the widget’s settings panel and delivers the values to your code through NepTunes.settings.

"settings": {
  "schema": [
    { "id": "showArtwork", "type": "checkbox", "label": "Show Album Artwork", "default": true }
  ]
}

Every control needs an id (how you read it in JS), a type, and a label.

Control types

checkbox

A boolean toggle.

{ "id": "showVolume", "type": "checkbox", "label": "Show Volume Slider", "default": true }

slider

A numeric range.

{ "id": "spinSpeed", "type": "slider", "label": "Spin Speed",
  "min": 1, "max": 5, "step": 1, "default": 3 }

Fields: min, max, step, default (all numbers).

radio

A small set of mutually exclusive options shown as radio buttons.

{ "id": "theme", "type": "radio", "label": "Theme",
  "options": [
    { "value": "dark", "label": "Dark" },
    { "value": "light", "label": "Light" }
  ],
  "default": "dark" }

select

The same as radio, but rendered as a dropdown — better for longer lists.

{ "id": "labelPosition", "type": "select", "label": "Track Info Position",
  "options": [
    { "value": "off", "label": "Hidden" },
    { "value": "left", "label": "Left" },
    { "value": "right", "label": "Right" },
    { "value": "bottom", "label": "Bottom" }
  ],
  "default": "off" }

color

A color picker. default is a hex string.

{ "id": "accent", "type": "color", "label": "Accent Color", "default": "#007AFF" }

text

A free-text field.

{ "id": "label", "type": "text", "label": "Custom Label",
  "placeholder": "Now playing", "default": "" }

Values arrive keyed by id. Read them on load, and listen for changes:

function apply(settings) {
  document.body.dataset.theme = settings.theme;
  artwork.hidden = !settings.showArtwork;
}

apply(NepTunes.settings);
NepTunes.on('settingschange', apply);

← JavaScript API Permissions →