> ## 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.

# Configuration

> Configuration reference for the Bonsai Search web component

## 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.

<Callout color="#0A5B3B" icon="info">
  **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](/project/docs/bonsai-search/styling) for the full CSS variable list.
</Callout>

### 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:

| 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`](#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

<ParamField body="api-key" required>
  Your Bonsai API key. Required for the search component to function and to fetch runtime configuration from the Settings API.

  ```html theme={null}
  <bonsai-search api-key="YOUR_API_KEY_HERE"></bonsai-search>
  ```
</ParamField>

## API Configuration

<ParamField body="base-url" required>
  The base URL for the Bonsai Search API. Required. The Settings API URL is derived from this value automatically.

  ```html theme={null}
  <bonsai-search api-key="API-KEY" base-url="https://api.hibonsai.com/rest/search/v3/"></bonsai-search>
  ```
</ParamField>

## User Experience

<ParamField body="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.

  ```html theme={null}
  <bonsai-search placeholder="Search our products..."></bonsai-search>
  ```
</ParamField>

<ParamField body="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.

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

  <Callout color="#0A5B3B" icon="triangle-alert">
    The suggestions attribute must be a valid JSON array string. Use single quotes around the attribute value and double quotes for the array items.
  </Callout>
</ParamField>

<ParamField body="max-results" default="50">
  The maximum number of search results to display.

  ```html theme={null}
  <bonsai-search max-results="20"></bonsai-search>
  ```
</ParamField>

<ParamField body="timeout-ms" default="30000">
  The request timeout in milliseconds.

  ```html theme={null}
  <bonsai-search timeout-ms="30000"></bonsai-search>
  ```
</ParamField>

## Display Options

<ParamField body="render-price" default="false">
  Boolean attribute that enables price display in search results. Presence of the attribute is sufficient to enable it.

  ```html theme={null}
  <bonsai-search render-price></bonsai-search>
  ```
</ParamField>

<ParamField body="render-price-with-title" default="true">
  Controls whether the price is displayed alongside the product title.

  ```html theme={null}
  <bonsai-search render-price-with-title="false"></bonsai-search>
  ```
</ParamField>

<ParamField body="markdown" default="false">
  Boolean attribute that enables markdown rendering in AI summaries and content.

  ```html theme={null}
  <bonsai-search markdown></bonsai-search>
  ```
</ParamField>

<ParamField body="theme" default="light">
  Color theme for the component. Options: `light`, `dark`, or `auto` (follows the user's system preference).

  ```html theme={null}
  <bonsai-search theme="dark"></bonsai-search>
  ```
</ParamField>

<ParamField body="image-object-fit" default="cover">
  Sets the `--bonsai-image-object-fit` CSS variable. Options: `cover` or `contain`.

  ```html theme={null}
  <bonsai-search image-object-fit="contain"></bonsai-search>
  ```
</ParamField>

<ParamField body="hide-products" default="false">
  Boolean attribute — when present, product results are hidden and only the AI summary is shown. Useful for conversational integrations.

  ```html theme={null}
  <bonsai-search hide-products></bonsai-search>
  ```
</ParamField>

## Results Section Labels

<ParamField body="featured-items-label" default="Featured Items">
  The heading text displayed above AI-recommended products.

  ```html theme={null}
  <bonsai-search featured-items-label="Top Picks"></bonsai-search>
  ```
</ParamField>

<ParamField body="more-items-label" default="More Items">
  The heading text displayed above additional results when AI recommendations are present.

  ```html theme={null}
  <bonsai-search more-items-label="See Also"></bonsai-search>
  ```
</ParamField>

<ParamField body="items-label" default="Items">
  The heading text displayed above results when there are no AI recommendations.

  ```html theme={null}
  <bonsai-search items-label="Products"></bonsai-search>
  ```
</ParamField>

## Callbacks

<ParamField body="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.

  ```html theme={null}
  <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>
  ```
</ParamField>

## 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](/project/docs/bonsai-search/styling) for the full list of CSS variables and override examples.