Skip to main content

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.

​
How configuration works

Starting with SDK v3.2, the <bonsai-search> component has two configuration sources:
  1. HTML attributes you set on the tag — the small set listed below. These are the only values the component reads from the DOM.
  2. 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:
  1. HTML attribute on the tag (if set)
  2. Settings API response for this api-key (if provided)
  3. 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:
AttributeRequiredDefaultNotes
api-keyYes—Required for all requests and for fetching runtime config
base-urlYes—API base URL. Also used to derive the Settings API URL
placeholderNo"Describe what you're looking for..."Input placeholder. Overrides Settings API content.placeholder
suggestionsNo[]JSON array string. Overrides Settings API content.suggestions
max-resultsNo50Max results rendered. Overrides Settings API behavior.max_results
timeout-msNo30000Request timeout (ms)
render-priceNofalseBoolean attribute — presence enables prices. Overrides Settings API behavior.render_price
render-price-with-titleNotrueWhether price is rendered alongside the title
markdownNofalseBoolean attribute — enables markdown rendering in AI summaries
themeNolightlight, dark, or auto. Overrides Settings API behavior.theme
image-object-fitNocovercover or contain. Sets the --bonsai-image-object-fit CSS variable
featured-items-labelNo"Featured Items"Header for recommendations. Overrides Settings API labels.featured_items_label
more-items-labelNo"More Items"Header when recommendations exist. Overrides Settings API labels.more_items_label
items-labelNo"Items"Header when no recommendations. Overrides Settings API labels.items_label
hide-productsNofalseBoolean attribute — hides product results (AI summary only)
on-priceNo—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.