FishriftDocs Dashboard
Docs/Developers

Custom widgets

A Custom Widget is a rift with your own HTML, CSS and JavaScript. It receives Fishrift's live events, so you can build anything: a custom follower counter, a mini game, a special alert.

Making one

  1. In the overlay editor, press Add rift and pick Custom Widget.
  2. Write your code in the HTML, CSS and JS tabs.
  3. Put settings in FIELDS (JSON). They are available in your code as FR.fields.

The preview reloads the widget every time you change something.

A first widget

HTML:

<div id="last">Waiting for followers...</div>

CSS:

#last { font: 700 32px/1.2 Inter, sans-serif; color: #fff; text-shadow: 0 2px 6px #000; }

JS:

var el = document.getElementById('last');
var prefix = FR.fields.prefix || 'Latest follower:';

FR.onFollow(function (e) {
  el.textContent = prefix + ' ' + (e.viewer_display_name || e.viewer_name);
});

FR.onDonation(function (e) {
  el.textContent = e.viewer_display_name + ' tipped ' + e.amount;
});

Fields:

{ "prefix": "New follower:" }

The FR object

Your HTML is on the page and window.FR exists before your JavaScript runs. Your script runs once when the widget loads.

MemberWhat it does
FR.fieldsYour Fields JSON as an object
FR.on(type, fn)Calls fn(event) for events of that type. Use "*" for every event
FR.onEvent(fn)Every event
FR.onFollow(fn)Follows
FR.onSubscribe(fn)New subs
FR.onResub(fn)Resubs
FR.onGiftSub(fn)Gift subs
FR.onBits(fn)Cheers
FR.onRaid(fn)Raids
FR.onDonation(fn)Tips: Ko-fi, external donations, Twitch charity and Super Chats

Handlers for a type run first, then "*" handlers. You can add as many handlers as you like.

Tip: errors inside a handler are caught silently. Wrap your code in try { ... } catch (e) { console.error(e); } while you build.

Every event is a full event object, including the platform's original data in raw.

Listening without FR

You can also listen to the messages yourself:

window.addEventListener('message', function (e) {
  if (e.data && e.data.source === 'fishrift-overlay' && e.data.type === 'event') {
    console.log(e.data.event);
  }
});

Testing

Press EMULATE in the editor and turn on Send to OBS too. The test event reaches your widget in the preview and in OBS. With it off, only the Alert Box in the preview plays.

To debug, open the editor preview in your browser and use the developer tools on the widget's frame.

Limits

The widget runs in a sandboxed frame:

  • No cookies, localStorage, sessionStorage or IndexedDB.
  • No access to the overlay page around it, no forms, popups or new windows.
  • Requests to other sites only work when that site allows any origin (CORS). Fishrift's own public API doesn't allow this yet.
  • Fonts, images and scripts from other sites load normally.

Other things to know:

  • Events only reach widgets on overlays that are open. A widget that loads later doesn't get earlier events.
  • Switched off rifts get no events.
  • Bot command events don't reach widgets.
  • Write <\/script> instead of </script> inside your JavaScript or Fields, and avoid </style> in your CSS. They would close the code block early.