ws context

last updated: September 8, 2026

createWS() returns the context object for the current widget instance:

const WS = createWS();

for script widgets, wrap the file in a function and call createWS() at the top.
for iframe widgets, include https://widget.st/js/iframe.js in <head> first. you can also read the same data from query parameters.

properties

element - mount point. host element for script, document.body for iframe
settings - instance settings by key. learn more about settings format here
instanceId - instance id (number)
widgetId - widget id (number)
domain - hostname the widget is embedded on
name - instance name
embedMode - "script" or "iframe"

fetch

WS.fetch(url, opts) - works the same as normal fetch, but more resilient to CSP blocks (like on free Neocities sites). recommended to use instead of normal fetch.

const res = await WS.fetch('https://example.com/api/data');
const data = await res.json();

important: it does not send cookies and Origin will be https://widget.st if request is rerouted.

owner auth

getOwnerToken() - existing owner token, or null.
authorizeOwner() - token, opens a popup if the owner isn't authorized yet
authorizeOwner({ requestUserData: true }) - same, but also asks to share username and email

verify the token on your server:

// client:
const token = await WS.authorizeOwner();

// ...send token to your server
// server:
const res = await fetch('https://widget.st/api/verify-owner', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token }),
});
const data = await res.json();
// data.instance_id, data.widget_id, data.user_id
// data.username, data.email if requested