Skip to main content
Where styling lives. The Concierge renders in a closed shadow DOM, so your page’s CSS cannot reach inside it and its styles cannot leak out. Everything is customized through CSS custom properties, set two ways:
  1. From the Bonsai dashboard (preferred) — your brand colors are fetched per-tenant at load time and applied automatically.
  2. Inline on the element — set any variable in the tag’s style attribute to override it for that embed.
Because the shadow root is closed, an inline style on the tag is the only way page-side CSS can reach the component. A stylesheet rule like bonsai-chat-bubble { --bonsai-agent-brand: red } will not take effect.

​
Setting variables

Inline values are re-applied after the dashboard response arrives, so anything you pin here survives a later dashboard change.

​
Color reference

​
Conversation

​
Panel and shape

​
Launcher reference

The launcher has its own token set, so you can restyle the button without touching the panel.
Minimum sizes are accessibility floors, not suggestions. --bonsai-agent-bubble-min-height and --bonsai-agent-bubble-min-width default to 44px because that is the smallest reliably tappable target. A design that specifies a shorter button will render at 44px unless you lower these explicitly — and lowering them makes the launcher harder to hit on a phone.

​
Responsive behavior

The launcher adapts to the viewport at two breakpoints. Both apply automatically — there is nothing to enable. 380px is the threshold so that an iPhone SE (375px wide) goes compact while an iPhone 12 through 16 (390px) keeps its full launcher.

​
The compact tab

At 380px and narrower, every launcher — pill or tab, on either side — renders the same way:
  • Position is forced to the viewport edge and vertically centered. bubble-bottom, bubble-right, bubble-left, and bubble-top no longer apply; the compact tab uses --bonsai-agent-bubble-compact-top instead.
  • Shape is a tab with its outer corners rounded 8px, whichever launcher-variant you set.
  • Text is launcher-compact-label, not label. An icon-only launcher is unaffected, but it also stops being a 56px square and becomes the same compact tab.
  • The icon is always shown, including when launcher-content="text".
  • It hides itself while the panel is open, since at that width the panel covers the screen.
It never shrinks below 44px in either dimension — --bonsai-agent-bubble-min-height and --bonsai-agent-bubble-min-width still apply.

​
Pin the compact twin, not just the base variable

On tablets, a value you pin on the tag wins — the tier only adjusts variables you have not set. The 380px tier is different: it reads its own variables, so pinning the base one has no effect there.
The same pairing applies to padding, gap, radius, and icon size. Switching to the compact label and showing the icon are not variable overrides — they change which elements are visible — so they apply whatever you have pinned.

​
Which icon the compact tab shows

  1. launcher-icon-url, if set
  2. Otherwise the built-in glyph named by launcher-icon — sparkles (the default), chat, or mark (the Bonsai mark)
The default glyph is unbranded, so a text-only launcher does not put the Bonsai mark on your storefront. Set launcher-icon-url to use your own.
header-icon-url is not reused here. It supplies the logo inside the opened panel only — set launcher-icon-url explicitly even if it points at the same file.
If launcher-icon-url points at an image that fails to load, the component falls back to the built-in glyph rather than rendering an empty button.

​
Dark mode

Set theme="dark" to use the dark palette. It adjusts the background, foreground, muted, border, surface, input, card, and hover variables; brand and launcher colors are unchanged, since those are yours.
Any value other than dark resolves to the light palette. The component does not follow the operating system setting on its own — to do that, set the attribute from your own theme switcher.