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": "opacity", "type": "slider", "label": "Background Opacity",
  "min": 0.3, "max": 1, "step": 0.1, "default": 0.85 }

The control shows no numeric readout, so a slider only works when the label alone tells the user what a position means. For a small set of meaningful values, speeds, sizes, intervals, prefer select, which can spell each one out.

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": "#0088FF" }

text

A free-text field.

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

Reading settings in your widget

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 APIPermissions →