Attributes reference

The <livelayer-widget> custom element reads its configuration from HTML attributes. All attributes are optional except agent-id. Attributes can be changed at runtime — the widget reacts via attributeChangedCallback.

html

<livelayer-widget
  agent-id="agt_abc123"
  mode="widget"
  position="bottom-right"
  capabilities="navigate,scroll"
  base-url="https://livelayer.app"
  api-key="ll_live_...">
</livelayer-widget>

Reference

Name	Type	Description
agent-id*	string	Published agent ID from the dashboard. Required.
mode	"widget" \| "embedded" \| "fullscreen"	Override the experience mode set in the dashboard. widget = floating bubble (default for marketing). embedded = renders inline at the element's size. fullscreen = takes over the viewport.
position	"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"	Where the floating bubble docks. Only applies when mode = widget. Default: bottom-right.
capabilities	comma-separated list	Restrict what page actions the agent can perform. Comma-separated list of: navigate, scroll, click. Omit for unrestricted (default behavior preserved for back-compat). See Capabilities page.
base-url	string	Override the live-layer API base URL. Auto-detected from the script src; only set this if you're self-hosting (uncommon).
api-key	string	Cross-origin auth. When set, fetches add the x-api-key header. Only needed if your widget loads on a domain other than the agent's published origin.
greeting	string	Custom greeting the agent says on connect, overriding the dashboard-configured one.
theme	"light" \| "dark"	Force light or dark theme. Default: follows system preference.

Setting attributes from JavaScript

The element reacts to attribute changes via attributeChangedCallback, so you can change configuration at runtime:

const widget = document.querySelector("livelayer-widget");
if (widget) {
  // Switch to a different agent on the fly
  widget.setAttribute("agent-id", "agt_xyz789");

  // Tighten the capability allowlist after a checkout step
  widget.setAttribute("capabilities", "navigate");
}

Embedded-mode sizing

When mode="embedded", the widget fills its parent container. Wrap it to control size:

html

<div style="width: 100%; max-width: 480px; height: 600px;">
  <livelayer-widget
    agent-id="agt_abc123"
    mode="embedded">
  </livelayer-widget>
</div>

Multiple widgets on one page

You can have multiple <livelayer-widget> elements on the same page (e.g., one in a hero section and one persistent in the footer) — each runs its own session. They don't share state.

If you want them to share state (same conversation across two surfaces), use the NPM controlledSession prop instead.