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.