Skip to main content
Use this page to complete prerequisites and jump straight to the right minimal integration path.

​
Prerequisites

Complete these three steps before integrating any web component.
1

Get your API key

Request your Bonsai API key from your Customer Success Manager (CSM).
Use your real API key in api-key="API-KEY" placeholders.
2

Confirm implementation access

Make sure you can edit the page, template, or CMS block where you will add the component <script> tag and markup.
3

Register your origins

Requests are refused unless the page’s origin is allowed for your organization. Send your CSM every origin the components will run on — production, staging, any preview domain, and the localhost port you develop on.
Only three things are allowed without asking: the Bonsai dashboard, https://*.shopifypreview.com previews, and http://localhost:3000 / :3001 against non-production. A local port used against production still has to be registered, and a page opened from disk (file://) never works — serve it over HTTP. Anything unregistered surfaces as Failed to fetch.
4

Install the Bonsai pixel

The pixel establishes the _bonsai_s shopper identifier. Search works without it, but every event reports NOT_SET and nothing can be attributed to a session, campaign or order — only the pixel creates that identifier.
5

Choose your component

Pick the component that matches your use case:

<bonsai-search>

Full Bonsai search experience with AI summary and product results.

<bonsai-searchbar>

Redirecting search bar only, without the full results UI.

<bonsai-chat-bubble>

Conversational shopping assistant, opened from a floating launcher.

React / Next.js

A complete install in an App Router project — script, types, palette, results route.
The search bar and the full search component are commonly used together — a bar in the header, the results page elsewhere. See Pairing with the search bar.

​
Before you style it

If your storefront is dark, read Dark theme before writing any CSS. theme="dark" fixes 21 colour variables that page CSS and the Bonsai dashboard cannot override, and the supported way to control a dark embed is to set theme="light" and supply the palette yourself. This is the single most common integration surprise.