Widget Setup & Configuration

<pulse-widget> is the main element you add to your page. This page covers all the options.

Required Attributes

<pulse-widget
  api-key="pk_your_publishable_key"
  token="USER_JWT_TOKEN"
  room="my-page"
  endpoint="wss://pulse.hire.rest"
></pulse-widget>

Attribute	Description
api-key	Your publishable key (pk_...) from the Admin Panel
token	User JWT returned by POST /auth/token — see Authentication
room	A unique string identifying this collaboration context (usually one per page)
endpoint	URL of the Pulse server (e.g., wss://pulse.hire.rest)

Optional Attributes

Attribute	Default	Options	Description
position	bottom-right	bottom-right, bottom-left, top-right, top-left	Where the floating toolbar appears
display	floating	floating, inline	Display mode (see below)

Display Modes

Floating (default)

The toolbar floats in a fixed position over your page content. Panels slide out from the toolbar.

<pulse-widget
  api-key="pk_..." token="..." room="..." endpoint="..."
  position="bottom-right"
></pulse-widget>

Inline

The widget renders as a regular element in the page flow. Use a <slot> to provide your own trigger button:

<pulse-widget
  api-key="pk_..." token="..." room="..." endpoint="..."
  display="inline"
>
  <button class="my-collab-btn">Collaborate</button>
</pulse-widget>

Clicking the slotted content toggles the collaboration toolbar and panels.

Position Options

<!-- Bottom-right corner (default) -->
<pulse-widget position="bottom-right" ...></pulse-widget>

<!-- Bottom-left corner -->
<pulse-widget position="bottom-left" ...></pulse-widget>

<!-- Top-right corner -->
<pulse-widget position="top-right" ...></pulse-widget>

<!-- Top-left corner -->
<pulse-widget position="top-left" ...></pulse-widget>

Switching Rooms Dynamically

Update the room attribute to move users between collaboration contexts:

const widget = document.querySelector('pulse-widget');

// When user navigates to a different page
widget.setAttribute('room', 'new-page-id');

Pulse automatically:

1. Disconnects from the old room
2. Connects to the new room
3. Loads that room's threads, comments, and presence

Connection Status

The widget shows a small banner when connection state changes:

State	Banner
Reconnecting	Amber pill with "Reconnecting..."
Disconnected	Red pill with "Disconnected"
Reconnected	Green flash "Connected" (fades after 2s)

This is automatic — no configuration needed.

Multiple Widgets

You can have multiple widgets on one page (e.g., different rooms for different sections):

<pulse-widget
  api-key="pk_..." token="..." endpoint="..."
  room="sidebar-chat"
  display="inline"
>
  <button>Chat</button>
</pulse-widget>

<pulse-widget
  api-key="pk_..." token="..." endpoint="..."
  room="page-review"
  position="bottom-right"
></pulse-widget>

Each widget connects independently to its own room.

Important

Never create multiple widgets for the same room on one page (e.g., one for desktop and one for mobile). Each widget creates its own WebSocket connection and state store — pins created by one widget won't appear in the other widget's Comments panel. Use CSS to show/hide a single widget instance across screen sizes instead.