Configuration

How configuration works

Starting with SDK v3.2, the <bonsai-search> component has two configuration sources:

HTML attributes you set on the tag — the commonly used ones are listed below, with the rest under Additional attributes.
Runtime configuration from the Settings API — theming (colors, layout, max width, alignment), default labels, default placeholder, default suggestions, and feature toggles (markdown, price rendering, autocomplete, etc.). These are fetched per-tenant by the component at load time from /rest/search-component-config/ using your api-key, and they are applied automatically.

Where theming lives now. Colors, borders, alignment, and width are not HTML attributes anymore. They are either returned by the Settings API (preferred — managed per tenant from the Bonsai dashboard) or overridden locally via CSS custom properties on the host element. See Advanced Styling for the full CSS variable list.

Precedence

For any given value, the component resolves in this order:

HTML attribute on the tag (if set)
Settings API response for this api-key (if provided)
Built-in default

So you can leave the tag minimal (just api-key) and let the dashboard drive the rest, or override a specific value on the tag when you need to.

Colours are the exception. Under theme="dark" (or theme="auto" on a dark-preference machine) 21 colour and shadow variables are fixed by the theme and cannot be overridden by page CSS or by the Settings API. See Dark theme.

Attributes

The most commonly used attributes on <bonsai-search>:

Attribute	Required	Default	Notes
`api-key`	Yes	—	Required for all requests and for fetching runtime config
`base-url`	No	`https://api.hibonsai.com`	API origin. The path is supplied by your organization’s configured search version, not by this value — see below
`disable-search-path-override`	No	—	Boolean attribute — pins the path in `base-url` instead of taking your organization’s configured search version
`placeholder`	No	`"Describe what you're looking for..."`	Input placeholder. Overrides Settings API `content.placeholder`
`suggestions`	No	`[]`	JSON array string. Overrides Settings API `content.suggestions`
`max-results`	No	`50`	Max results rendered. Overrides Settings API `behavior.max_results`
`timeout-ms`	No	`30000`	Request timeout (ms)
`render-price`	No	`false`	Boolean attribute — presence enables prices. Overrides Settings API `behavior.render_price`
`render-price-with-title`	No	`true`	Whether price is rendered alongside the title
`markdown`	No	`false`	Boolean attribute — enables markdown rendering in AI summaries
`theme`	No	`light`	`light`, `dark`, or `auto`. Overrides Settings API `behavior.theme`
`image-object-fit`	No	`cover`	`cover` or `contain`. Sets the `--bonsai-image-object-fit` CSS variable
`featured-items-label`	No	`"Featured Items"`	Header for recommendations. Overrides Settings API `labels.featured_items_label`
`more-items-label`	No	`"More Items"`	Header when recommendations exist. Overrides Settings API `labels.more_items_label`
`items-label`	No	`"Items"`	Header when no recommendations. Overrides Settings API `labels.items_label`
`hide-products`	No	`false`	Boolean attribute — hides product results (AI summary only)
`on-price`	No	—	Name of a global function used to format prices before rendering. See `on-price`

Legacy colour attributes (brand-color, text-color, input-bg, card-bg, …) were removed in v3.2.0 and are ignored. Use CSS custom properties or the Settings API instead — see Advanced Styling.

Additional attributes

Less common, but read by the component:

Attribute	Default	Notes
`autocomplete`	Settings API	Enable the autocomplete dropdown. `autocomplete="false"` disables it
`filters`	Settings API	Fetch catalog filters and render the filter panel
`pre-search-mode`	`filters-only` when filters are on	Pre-query behaviour: `none`, `filters-only`, or `browse`
`filter-fields`	Settings API	JSON array or comma-separated allowlist of filter dimensions to show
`initial-filters`	—	JSON filter object applied on first render
`sync-filters-to-url`	follows `filters`	Read/write `filters` and `browse` URL params
`enable-sort`	Settings API	Show the sort control
`default-sort`	`relevance`	Initial sort key
`hide-missing-images`	Settings API	Drop results with no usable image instead of showing a placeholder
`missing-image-url`	—	Image to show instead of the “Image unavailable” placeholder
`hide-description`	Settings API	Hide the card description line
`secondary-image-on-hover`	—	Boolean attribute — swap to the alternate product image on hover
`skip-scoring`	`false`	Skip LLM relevancy scoring
`ctr` / `client-ctr`	`false` / `true`	Click-through tracking
`disable-agent-handoff`	—	Boolean attribute — ignore Concierge handoff events
`market` · `country` · `currency` · `market-root` · `cookie-domain`	—	Multi-market and cookie scoping
`on-filter-panel-render` · `on-filter-group-render` · `on-filter-control-render`	—	Names of global functions that replace the default filter rendering

Required Attributes

required

Your Bonsai API key. Required for the search component to function and to fetch runtime configuration from the Settings API.

<bonsai-search api-key="YOUR_API_KEY_HERE"></bonsai-search>

API Configuration

default:"https://api.hibonsai.com"

The API origin. Optional — omit it and the component uses the production origin. The Settings API URL is derived from this value automatically.

<bonsai-search api-key="API-KEY"></bonsai-search>

The path is not yours to choose. Whatever path you write here is replaced at load time by the search version configured for your organization (api.search_path in the Settings API response), so .../rest/search/v3/ on the tag does not mean v3 is what gets called. Set the origin only, or pin it deliberately:

<bonsai-search
  api-key="API-KEY"
  base-url="https://api.hibonsai.com/rest/search/v4/"
  disable-search-path-override
></bonsai-search>

Boolean attribute. Keeps the path you wrote in base-url instead of adopting your organization’s configured search version. Use it when an embed must stay on one specific version regardless of dashboard changes.

Requests are rejected unless the page’s origin is allowed for your organization. Three things are allowed automatically: the Bonsai dashboard, any https://*.shopifypreview.com preview, and — on non-production environments only — http://localhost:3000, http://localhost:3001 and the matching 127.0.0.1 ports.Everything else, including every localhost port you develop against production, has to be registered per organization. Send your CSM the full list of origins you need — production, staging, preview, and the local port you work on — before you start. A page whose origin is not on that list fails the CORS preflight, and the component reports Failed to fetch.Pages opened directly from disk (file://) send an origin of null and are never allowed; serve your test page over HTTP instead.

User Experience

default:"Describe what you're looking for..."

The placeholder text displayed in the search input field. If omitted, the value from the Settings API is used; otherwise the built-in default.

<bonsai-search placeholder="Search our products..."></bonsai-search>

default:"[]"

A JSON array of suggested search queries that appear below the search input. If omitted, the Settings API content.suggestions list is used.

<bonsai-search suggestions='["Which product is best for my space?", "What features does this product have?"]'></bonsai-search>

The suggestions attribute must be a valid JSON array string. Use single quotes around the attribute value and double quotes for the array items.

default:"50"

The maximum number of search results to display.

<bonsai-search max-results="20"></bonsai-search>

default:"30000"

The request timeout in milliseconds.

<bonsai-search timeout-ms="30000"></bonsai-search>

Display Options

default:"false"

Boolean attribute that enables price display in search results. Presence of the attribute is sufficient to enable it.

<bonsai-search render-price></bonsai-search>

default:"true"

Controls whether the price is displayed alongside the product title.

<bonsai-search render-price-with-title="false"></bonsai-search>

default:"false"

Boolean attribute that enables markdown rendering in AI summaries and content.

<bonsai-search markdown></bonsai-search>

default:"light"

Color theme for the component. Options: light, dark, or auto (follows the user’s system preference).

<bonsai-search theme="dark"></bonsai-search>

default:"cover"

Sets the --bonsai-image-object-fit CSS variable. Options: cover or contain.

<bonsai-search image-object-fit="contain"></bonsai-search>

default:"false"

Boolean attribute — when present, product results are hidden and only the AI summary is shown. Useful for conversational integrations.

<bonsai-search hide-products></bonsai-search>

Results Section Labels

default:"Featured Items"

The heading text displayed above AI-recommended products.

<bonsai-search featured-items-label="Top Picks"></bonsai-search>

default:"More Items"

The heading text displayed above additional results when AI recommendations are present.

<bonsai-search more-items-label="See Also"></bonsai-search>

default:"Items"

The heading text displayed above results when there are no AI recommendations.

<bonsai-search items-label="Products"></bonsai-search>

Callbacks

Name of a globally-accessible function used to format prices before they are rendered. The function receives (result, price, parent) and must return the string to display.

<script>
  window.formatPrice = (result, price) => {
    const n = Number(price)
    return Number.isFinite(n) ? `$${n.toFixed(2)}` : (price || "")
  }
</script>
<bonsai-search api-key="..." render-price on-price="formatPrice"></bonsai-search>

Styling

All visual customization (colors, borders, alignment, max width, hover states) is done via either:

The Settings API — preferred. Configure per-tenant in the Bonsai dashboard; the component picks up the values automatically.
CSS custom properties on the host element — to override per-embed.

See Advanced Styling for the full list of CSS variables and override examples.

Get Started

Web Components

Support

How configuration works

Precedence

Attributes

Additional attributes

Required Attributes

API Configuration

User Experience

Display Options

Results Section Labels

Callbacks

Styling

​How configuration works

​Precedence

​Attributes

​Additional attributes

​Required Attributes

​API Configuration

​User Experience

​Display Options

​Results Section Labels

​Callbacks

​Styling

How configuration works

Precedence

Attributes

Additional attributes

Required Attributes

API Configuration

User Experience

Display Options

Results Section Labels

Callbacks

Styling