> ## 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 Bar web component

## How configuration works

Starting with SDK v3.2, the `<bonsai-searchbar>` 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, alignment, max width), default placeholder, default suggestions, and feature toggles (theme, autocomplete). 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, width, and opacity 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-searchbar/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-searchbar>` web component observes only the following attributes:

| Attribute      | Required | Default                                 | Notes                                                               |
| -------------- | -------- | --------------------------------------- | ------------------------------------------------------------------- |
| `api-key`      | Yes      | —                                       | Required for fetching runtime config and for autocomplete           |
| `base-url`     | Yes      | —                                       | API base URL. Also used to derive the Settings API URL              |
| `search-path`  | No       | `"/ai-search"`                          | Redirect destination on submit                                      |
| `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`     |
| `theme`        | No       | `light`                                 | `light`, `dark`, or `auto`. Overrides Settings API `behavior.theme` |
| `close-button` | No       | `false`                                 | Boolean attribute — presence enables the close action               |

Any other attribute (including legacy color attributes like `brand-color`, `text-color`, `input-bg`, `results-columns`, `input-opacity`, 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 fetching runtime configuration from the Settings API and for autocomplete.

  ```html theme={null}
  <bonsai-searchbar api-key="YOUR_API_KEY_HERE"></bonsai-searchbar>
  ```
</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-searchbar
    api-key="YOUR_API_KEY_HERE"
    base-url="https://api.hibonsai.com/rest/search/v3/">
  </bonsai-searchbar>
  ```
</ParamField>

## Redirect and UX

<ParamField body="search-path" default="/ai-search">
  The path the component redirects to after query submission.

  ```html theme={null}
  <bonsai-searchbar search-path="/ai-search"></bonsai-searchbar>
  ```
</ParamField>

<ParamField body="placeholder" default="Describe what you're looking for...">
  The placeholder text shown before the user enters a query. If omitted, the value from the Settings API is used.

  ```html theme={null}
  <bonsai-searchbar placeholder="Describe what you're looking for..."></bonsai-searchbar>
  ```
</ParamField>

<ParamField body="suggestions" default="[]">
  A JSON array of suggested queries shown in the dropdown. If omitted, the Settings API `content.suggestions` list is used.

  ```html theme={null}
  <bonsai-searchbar suggestions='["What is your return policy?", "Do you offer gift cards?"]'></bonsai-searchbar>
  ```

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

## Theme

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

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

## Display controls

<ParamField body="close-button" default="false">
  Boolean attribute — when present, enables the close action button.

  ```html theme={null}
  <bonsai-searchbar close-button></bonsai-searchbar>
  ```
</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-searchbar/styling) for the full list of CSS variables and override examples.