Skip to main content

​
Getting Started

Before getting started, ensure that you’ve had a chance to review the Quickstart prerequisites. Once you have your API key, you can integrate Bonsai AI search into any website in just a few minutes using our web component.
If you only need the redirecting search bar (not the full results UI), use the
Bonsai Search Bar Web Component instead.

​
Quick Installation

Use this minimal 2-step setup to render Bonsai Search on your website.
Theming is managed in the Bonsai dashboard. When the component loads, it fetches your tenant’s theme and behavior settings from the Settings API using your api-key and applies them automatically. You can also override values per-embed via CSS custom properties on the <bonsai-search> element — see Advanced Styling.Building a dark embed? Read Dark theme first. theme="dark" fixes 21 colour variables that neither the dashboard nor your page CSS can change, and the supported way to control a dark embed is to set theme="light" and supply the palette yourself — not to drop the attribute, which adopts the dashboard theme.
1

Install the script

Add the Bonsai Search <script> tag to your HTML page. Place this in the <head> section, or before the closing </body> tag. This ensures the script is loaded before the component is rendered.
2

Add the Web Component

Add the <bonsai-search> web component where you want search to appear. Only api-key is required — the component fetches its placeholder text, suggestion chips and API path from the Settings API using your api-key.
Important: Replace API-KEY with your actual API key provided by your CSM.
Most content and behavior come from the Settings API. Placeholder text, suggestions, result count, price rendering, markdown rendering, the API path and theming are configured per-tenant in the Bonsai dashboard and returned by /rest/search-component-config/ when the component loads, so a tag carrying only api-key is a complete install.If you need to override a specific value for a single embed you can still pass the corresponding attribute — it takes precedence over the Settings API response — but prefer the dashboard so every embed stays in sync.
3

Test the search experience with a query

Not working? Check the Troubleshooting guide for common issues.
A common layout puts a <bonsai-searchbar> in the site header and the full <bonsai-search> on a dedicated results page. The two are wired by a URL parameter:
  1. The search bar navigates to `${search-path}?q=${query}` on submit — /ai-search?q=day+pass by default.
  2. <bonsai-search> on that page reads q on load, prefills the input and runs the search.
So the only thing to keep in sync is that the search bar’s search-path points at the page hosting <bonsai-search>. Nothing else is required on either tag. One script tag covers both: either bundle registers both <bonsai-search> and <bonsai-searchbar>, so there is no need to load two. Using React? React & Next.js walks the whole install — script placement, the TypeScript declaration, the palette, and the results route.

​
Next Steps

Customize your component to match your site’s layout and design. For expanded installation guides and pre-styled templates see Examples.

Configuration

Full attribute reference and default values.

Advanced Styling

CSS variables, shadow parts, and themes.

Events Reference

Event lifecycle reference.

Examples

Expanded integration templates.