Custom widgets

Build your own overlay widgets with HTML, CSS, and JS - StreamElements custom widgets run as-is.

A custom widget is a widget you write yourself: an HTML pane, a CSS pane, a JS pane, and a JSON schema describing the settings it exposes. It runs on your overlay like any built-in widget - drag it, resize it, stack it, test it from the editor’s emulator - and it receives your tips, follows, subs, cheers, raids, and chat as events the moment they happen.

The runtime is StreamElements-compatible: widgets written for SE’s custom widget system - onWidgetLoad, onEventReceived, SE_API, {{field}} templates, jQuery - run here without changes. If you’ve got a widget from an SE gallery or a commission, paste its four panes in and it works. (A few SE surfaces are stubbed for now - see compatibility below for the list.)

Quick start

The four panes

• HTML - the widget’s markup. {{fieldName}} (or {fieldName}) placeholders are replaced with field values before it renders.
• CSS - styles, same templating. The widget’s box is the rectangle you draw in the editor; html, body inside it are transparent and sized to fill it.
• JS - your logic. jQuery is preloaded (like StreamElements), and {{fieldName}} templates are substituted here too (single-brace {name} is left alone in JS - that’s code, not a template).
• Fields - a JSON object describing your settings form. See below.

Fields

The fields schema is the SE format: each key is a field, each value describes it.

{
  "titleText": { "type": "text", "label": "Title", "value": "Hello chat" },
  "accent":    { "type": "colorpicker", "label": "Accent colour", "value": "#4ade80" },
  "speed":     { "type": "slider", "label": "Speed", "value": 5, "min": 1, "max": 20, "step": 1 },
  "showIcon":  { "type": "checkbox", "label": "Show icon", "value": true },
  "mode":      { "type": "dropdown", "label": "Mode", "value": "bar", "options": { "bar": "Bar", "ring": "Ring" } },
  "logo":      { "type": "image-input", "label": "Logo" },
  "font":      { "type": "googleFont", "label": "Font", "value": "Poppins" },
  "reset":     { "type": "button", "label": "Reset counter", "value": "reset" },
  "widgetName": { "type": "hidden", "value": "My Counter" }
}

Supported types and how the inspector renders them:

Add a "group" property to any field to section the form under a heading. Field values reach your JS as obj.detail.fieldData in onWidgetLoad, and as {{templates}} in all three panes.

The runtime

onWidgetLoad

Fires once when the widget mounts:

window.addEventListener('onWidgetLoad', function (obj) {
  const fieldData = obj.detail.fieldData;   // your fields, typed (numbers, booleans, strings)
  const currency  = obj.detail.currency;    // { code, name, symbol }
  const channel   = obj.detail.channel;     // { username, apiToken: "" }
  const session   = obj.detail.session.data; // SE-shaped session snapshot
});

onEventReceived

Fires on every live event. obj.detail.listener tells you what it is:

Every overlay keeps one shared Twitch chat connection open, whether or not the chat widget is on the layout - so message events always arrive. A pasted SE chat box works on an otherwise-empty overlay.

SE_API

Store limits: 100 keys per widget, 10KB per value.

StreamElements compatibility

Identical today: the event and load lifecycle, listener names, payload shapes, SE_API.store, fields schema and form rendering, {{templates}}, jQuery, per-widget sandboxing.

Known gaps, so you’re never surprised:

• session.data has the right shape but zeroed totals (latest/recent and week/month/total counters). Widgets render; running totals start at 0.
• SE_API.counters always returns 0 (no bot counters yet).
• SE_API.resumeQueue() and the widgetDuration hidden field don’t hold TipPage’s alert queue - alerts are played by the built-in alert widget.
• sound-input / video-input fields are plain URL inputs for now.

Security

Custom widget code runs inside a sandboxed iframe (sandbox="allow-scripts", no same-origin). Concretely, that means pasted code cannot:

• read or touch the rest of the overlay (other widgets, the page DOM);
• see your overlay URL/key or the overlay session token;
• call the TipPage API as you - it has no cookies, no tokens, and channel.apiToken is deliberately empty;
• break other widgets - worst case it wedges its own box.

Its only communication is a fixed set of messages the overlay defines (events in, store calls out). Two things to still be deliberate about:

• Only the overlay owner (and super admins) can create or edit widget code. Team members with overlay access can place widgets and change their fields, but never the code - because the code ultimately executes inside your OBS.
• Sandboxed code can still load external resources and make its own network requests (images, fonts, its own APIs - many SE widgets rely on this). Treat pasting a widget like installing software: use code you trust or can read. The sandbox limits the blast radius to the widget’s own box and whatever events you feed it.

Privacy

What widget code can observe is exactly what your overlay already shows on stream: donor display names, tip amounts and messages, follower/sub/cheer/ raid names, and public chat messages. It never receives emails, payment details, real names, session tokens, or anything from your dashboard.

The code itself runs locally - in your OBS browser source and in the editor preview - not on TipPage’s servers. The only widget data TipPage stores is what you put in it: the code you save, the field values on your layout, and whatever the widget writes to its own key/value store. All of it is scoped to your account, and deleting a widget deletes its store.

Because pasted code can call external services, a malicious widget could send the events it sees (donor names, chat) to a third party. That’s the same trust model as any browser-source widget on any platform - it’s why code editing is owner-only, and why you should paste from sources you trust.

Limits