Configuration - Bonsai

How configuration works

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

HTML attributes you set on the tag — the small set listed below. These are the only values the component reads from the DOM.
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.

Attributes

The <bonsai-search> web component observes only the following attributes:

Attribute	Required	Default	Notes
`api-key`	Yes	—	Required for all requests and for fetching runtime config
`base-url`	Yes	—	API base URL. Also used to derive the Settings API URL
`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`

Any other attribute (including legacy color attributes like brand-color, text-color, input-bg, etc.) is ignored. Use CSS custom properties or the Settings API instead.

Required Attributes

api-key

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

base-url

required

The base URL for the Bonsai Search API. Required. The Settings API URL is derived from this value automatically.

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

User Experience

placeholder

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>

suggestions

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.

max-results

default:"50"

The maximum number of search results to display.

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

timeout-ms

default:"30000"

The request timeout in milliseconds.

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

Display Options

render-price

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>

render-price-with-title

default:"true"

Controls whether the price is displayed alongside the product title.

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

markdown

default:"false"

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

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

theme

default:"light"

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

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

image-object-fit

default:"cover"

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

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

hide-products

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

featured-items-label

default:"Featured Items"

The heading text displayed above AI-recommended products.

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

more-items-label

default:"More Items"

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

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

items-label

default:"Items"

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

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

Callbacks

on-price

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.

​How configuration works

​Precedence

​Attributes

​Required Attributes

​API Configuration

​User Experience

​Display Options

​Results Section Labels

​Callbacks

​Styling

How configuration works

Precedence

Attributes

Required Attributes

API Configuration

User Experience

Display Options

Results Section Labels

Callbacks

Styling