Embed reference

Every attribute, CSS token, custom event, and imperative method exposed by the <breeze-buddy-assist> custom element.

<breeze-buddy-assist> is a Svelte 5 custom element that renders inside a Shadow DOM, so host-page CSS cannot bleed in and widget CSS cannot bleed out.

Attributes

All attributes map to Svelte component props. Attribute names are kebab-case; the internal prop name is camelCase.

Required

Session

Modes

Appearance

Header

Theming

Each prop sets a CSS custom property on the shadow host. If unset the widget falls back to its built-in light/dark token defaults. A pinned brand colour wins over both light and dark defaults, so the colour won’t shift when theme flips.

For finer control, set any --bb-* / --fg-* / --surface-* token directly via an inline style attribute on the host element:

<breeze-buddy-assist
  style="--bb-launcher-glow-color: #6c47ff40"
  tenant="…"
  api-base="…"
></breeze-buddy-assist>

Development

Declarative open

Add the bare open HTML attribute to start the widget open on page load. This is a one-shot read on mount — toggling the attribute after mount has no effect; use the imperative API instead.

<breeze-buddy-assist open tenant="…" api-base="…"></breeze-buddy-assist>

Imperative API

After the widget mounts it exposes three ways to control it from any script on the page. All three support the same actions: open, close, reset.

1 — DOM method (same-page scripts)

The simplest option. Query the element and call the method directly:

const el = document.querySelector('breeze-buddy-assist');

el.open();   // open the panel
el.close();  // close the panel (session + history preserved)
el.reset();  // close and destroy the current session

reset() is client-side only — the server session stays ACTIVE until idle-timeout. Call POST /widget/session/{id}/end for immediate server cleanup.

2 — window.BreezeAssist global

The widget publishes a global so any script — including ones that load before or after the element — can call it without querying the DOM:

window.BreezeAssist.open();
window.BreezeAssist.close();
window.BreezeAssist.reset();
window.BreezeAssist.isOpen(); // returns boolean

This is the recommended option for Shopify theme scripts, GTM custom HTML tags, and third-party snippets that don’t own the element reference.

3 — CustomEvent (GTM / tag managers)

Dispatch a breeze-buddy-assist:command event on document. Works from Google Tag Manager custom HTML tags, Segment, or any tool that can run document.dispatchEvent:

document.dispatchEvent(
  new CustomEvent('breeze-buddy-assist:command', {
    detail: { action: 'open' }   // 'open' | 'close' | 'reset'
  })
);

4 — postMessage (iframes)

If your page embeds the storefront in an iframe, or you need to trigger from a cross-origin context, post a message to the parent window:

// From inside an iframe:
window.parent.postMessage(
  { type: 'breeze-buddy-assist', action: 'open' },  // 'open' | 'close' | 'reset'
  '*'
);

Trigger from a button

The most common use-case — a CTA button elsewhere on the page opens the widget:

<button id="open-chat">Chat with us</button>

<breeze-buddy-assist
  tenant="pk_live_…"
  api-base="https://clairvoyance.breezelabs.app"
></breeze-buddy-assist>
<script src="https://widget.breezebuddy.com/assist.js" async></script>

<script>
  document.getElementById('open-chat').addEventListener('click', () => {
    window.BreezeAssist.open();
  });
</script>

To hide the default launcher FAB when using your own button, listen for ready and then hide it:

document.querySelector('breeze-buddy-assist').addEventListener(
  'breeze-buddy-assist:ready',
  () => document.getElementById('open-chat').style.display = 'none'
);

React / framework usage

import { useEffect } from 'react';

export function ChatButton() {
  return (
    <button onClick={() => (window as any).BreezeAssist?.open()}>
      Chat with us
    </button>
  );
}

Or typed properly:

declare global {
  interface Window {
    BreezeAssist?: {
      open(): void;
      close(): void;
      reset(): void;
      isOpen(): boolean;
    };
  }
}

Custom events

All events are dispatched on the host element (outside the Shadow DOM) with bubbles: true and composed: true, so standard addEventListener on the element or any ancestor catches them.

Event names are prefixed with breeze-buddy-assist:.

Error codes

Example — analytics tap

document.querySelector('breeze-buddy-assist').addEventListener(
  'breeze-buddy-assist:message',
  (e) => {
    analytics.track('chat_message', {
      role: e.detail.role,
      sessionId: e.detail.sessionId
    });
  }
);

Example — intercept link navigation

document.querySelector('breeze-buddy-assist').addEventListener(
  'breeze-buddy-assist:open-url',
  (e) => {
    e.preventDefault(); // stop the widget from calling window.open
    myRouter.push(e.detail.url); // handle with your SPA router
  }
);