> ## Documentation Index > Fetch the complete documentation index at: https://docs.hibonsai.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Configuration reference for the Bonsai Concierge chat web components ## How configuration works The Concierge has two configuration sources: 1. **HTML attributes** you set on the tag — everything listed on this page. 2. **Runtime configuration from the Bonsai dashboard** — brand colors, fetched per-tenant at load time using your `api-key` and applied automatically as CSS custom properties. ### Precedence For any given value, the component resolves in this order: 1. Inline CSS custom property set on the tag's `style` attribute 2. Dashboard configuration for this `api-key` 3. Built-in default Inline styles are re-applied after the dashboard response arrives, so a value you pin on the tag is never overwritten by a later dashboard change. HTML attributes listed below have no dashboard equivalent — they are read only from the DOM. ## Components | Tag | Purpose | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `` | Floating launcher button plus the chat panel it opens. The usual embed. | | `` | Opens the chat panel immediately on page load, with no launcher button. | | `` | A scrolling strip of AI-generated questions about the product in context. Clicking one opens the chat on that question. | **`` opens on load — it does not render in place.** It is not an inline chat you can position in your layout; it is the same overlay panel, opened automatically. Use it only where you want the conversation to start unprompted. For a launcher the shopper chooses to press, use ``. `` additionally requires `external-id` (or `sku`) and renders nothing if the product has no generated questions. ## Required attributes Your Bonsai API key. Required on every component. Used to fetch runtime configuration and to authenticate the conversation. ```html theme={null} ``` ## Connection | Attribute | Required | Default | Notes | | ---------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `api-key` | Yes | — | Your Bonsai API key | | `base-url` | No | `https://agent.hibonsai.com` | Agent API base URL. When omitted, it is derived from the origin of the loaded `bonsai-agent` script, falling back to the default | Only set this if you are pointing an embed at a non-production environment. In normal installations, leave it off — the component infers it from the script tag it was loaded from. ## Launcher appearance These apply to `` only. | Attribute | Required | Default | Notes | | --------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `label` | No | `"Ask"` | Visible text on the launcher. Also used as its accessible name unless `launcher-aria-label` is set | | `launcher-variant` | No | `pill` | `pill` (rounded, floating) or `tab` (flush against the viewport edge). `edge-tab` is accepted as a synonym for `tab` | | `launcher-content` | No | `text` | `text`, `text-icon`, or `icon` | | `launcher-side` | No | `right` | `left` or `right` | | `launcher-icon` | No | `mark` | Built-in glyph: `mark` (Bonsai mark), `sparkles`, or `chat` | | `launcher-icon-url` | No | — | URL of your own icon image. Falls back to the built-in `launcher-icon` if the image fails to load | | `launcher-aria-label` | No | — | Explicit accessible name. Required in practice when `launcher-content="icon"`, since there is no visible text | | `icon-only` | No | `false` | **Legacy.** Boolean equivalent to `launcher-content="icon"` with the `chat` glyph. Prefer `launcher-content` | **An unrecognized value falls back to the default rather than erroring.** `launcher-variant="rounded"` renders a pill; `launcher-icon="star"` renders the Bonsai mark. Values are matched case-insensitively and trimmed, so `" TAB "` resolves to `tab`. When `launcher-content` is `text` or `text-icon`, this is only honored if it contains the visible label — otherwise the visible label is used instead, so that a shopper using voice control can say what they see. ```html theme={null} ``` ## Launcher position | Attribute | Required | Default | Notes | | --------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `bubble-bottom` | No | `20px` | Distance from the bottom of the viewport | | `bubble-right` | No | `20px` | Distance from the right edge. Applies when `launcher-side="right"` | | `bubble-left` | No | `20px` | Distance from the left edge. Applies when `launcher-side="left"` | | `bubble-top` | No | `50%` | Vertical position. Applies to the `tab` variant, which is centered on the edge rather than sitting at the bottom | Each of these sets the corresponding CSS custom property, so anything valid in CSS works — `82px`, `4rem`, `calc(20px + env(safe-area-inset-bottom))`. ## Panel content These apply to `` and ``. | Attribute | Required | Default | Notes | | ---------------------- | -------- | ------- | ------------------------------------------------------------------ | | `title` | No | — | Heading shown in the panel header | | `header-icon-url` | No | — | Logo shown in the panel header. **Not** used for the launcher icon | | `header-layout` | No | — | Header arrangement | | `welcome-title` | No | — | Heading of the opening message | | `welcome-message` | No | — | Body of the opening message | | `placeholder` | No | — | Composer input placeholder | | `assistant-label` | No | — | Name shown against assistant replies | | `disclaimer-statement` | No | — | Fine print shown beneath the composer | | `theme` | No | `light` | `light` or `dark`. Any other value resolves to `light` | ## Behavior | Attribute | Required | Default | Notes | | ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------- | | `auto-open` | No | `false` | Boolean. Opens the panel immediately on page load | | `idle-open` | No | — | Number of seconds of shopper inactivity after which the panel opens by itself. Omit to never auto-open on idle | | `mobile-expanded` | No | `false` | Boolean. On phone-sized viewports, present the panel as a full-height sheet | | `clear-on-close` | No | `false` | Boolean. Discard the conversation when the panel is closed, so the next open starts fresh | | `disable-input` | No | `false` | Boolean. Render the conversation read-only | | `disable-search-refine` | No | `false` | Boolean. Stop the Concierge from reacting to on-site search queries | | `handoff` | No | `false` | Boolean. Enable the support handoff affordance — see [Events & API](/project/docs/bonsai-concierge/events) | | `external-id` | No | — | Identifier for the product or entity in context on this page | | `sku` | No | — | Alias for `external-id`, read only when `external-id` is absent | The timer resets on any pointer move, pointer press, key press, scroll, or touch, and pauses while the tab is hidden — so a shopper who leaves a tab open in the background does not return to an opened panel. It fires at most once, and never while the panel is already open. ```html theme={null} ``` Set this on product pages so the conversation knows which product the shopper is looking at. ```html theme={null} ``` ## Sales call-to-action An optional promotional row rendered inside the panel after a set number of exchanges. | Attribute | Required | Default | Notes | | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------- | | `sales-cta` | No | — | The call-to-action text | | `sales-cta-href` | No | — | Destination URL | | `sales-cta-label` | No | — | Text on the action button | | `sales-cta-after` | No | `5` | Number of messages before it appears. A non-numeric or non-positive value falls back to `5` | ## Boolean attributes Every attribute marked Boolean above is **presence-based**, following the HTML convention. The attribute being present enables it, whatever its value: ```html theme={null} ``` `handoff="false"` **enables** handoff. This trips people up — if you are toggling one of these from a template, omit the attribute rather than setting it to a falsy string.