bonsai-search

v3.1.5

Published

4 months ago

Bonsai Search SDK

0High
0Medium
0Low

Bonsai Search

AI-powered search web components for e-commerce. Drop-in <bonsai-search> and <bonsai-searchbar> custom elements for adding semantic product search to any website.

Quick Start

1. Install

npm install bonsai-search

2. Create an HTML file

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Bonsai Search</title>
    <script type="module">
      import "bonsai-search";
    </script>
    <style>
      .search-container {
        width: 100%;
        max-width: 42rem;
        margin: 4rem auto;
        min-height: 350px;
      }
    </style>
  </head>
  <body>
    <div class="search-container">
      <bonsai-search
        api-key="your-api-key"
        base-url="https://api.hibonsai.com/rest/search/v3/"
        placeholder="Describe what you're looking for..."
        suggestions='["What are your best sellers?", "Do you offer free shipping?"]'
        max-results="20"
        render-price
        markdown
        brand-color="#0A5B3B"
        text-color="#303030"
        muted-color="#9CA3AF">
      </bonsai-search>
    </div>
  </body>
</html>

3. Run with any dev server

npx vite

Open http://localhost:5173 and you're done.

Note: The import "bonsai-search" is an ESM module import that requires a bundler (Vite, webpack, etc.) to resolve. For a no-bundler setup, use the CDN option below.

CDN (no bundler needed)

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Bonsai Search</title>
    <script
      src="https://assets.hibonsai.com/sdk/bonsai-search-webcomponent-3.1.5.js"
      defer>
    </script>
    <style>
      .search-container {
        width: 100%;
        max-width: 42rem;
        margin: 4rem auto;
        min-height: 350px;
      }
    </style>
  </head>
  <body>
    <div class="search-container">
      <bonsai-search
        api-key="your-api-key"
        base-url="https://api.hibonsai.com/rest/search/v3/"
        placeholder="Describe what you're looking for..."
        suggestions='["What are your best sellers?", "Do you offer free shipping?"]'
        max-results="20"
        render-price
        markdown
        brand-color="#0A5B3B"
        text-color="#303030"
        muted-color="#9CA3AF">
      </bonsai-search>
    </div>
  </body>
</html>

Searchbar Only (CDN)

<script src="https://assets.hibonsai.com/sdk/bonsai-searchbar-webcomponent-3.1.5.js" defer></script>

<bonsai-searchbar
  api-key="your-api-key"
  base-url="https://api.hibonsai.com/rest/search/v3/"
  placeholder="Search products..."
  suggestions='["suggestion 1", "suggestion 2"]'>
</bonsai-searchbar>

Exports

| Import | Registers | |--------|-----------| | import "bonsai-search" | <bonsai-search> | | import "bonsai-search/searchbar" | <bonsai-searchbar> |

Attributes

| Attribute | Description | Default | |-----------|-------------|---------| | api-key | (Required) API key for authentication | -- | | base-url | API endpoint URL | https://api.hibonsai.com/rest/search/v3/ | | placeholder | Search input placeholder text | "Describe what you're looking for..." | | suggestions | JSON array of suggestion strings | [] | | max-results | Maximum number of results to display | 50 | | timeout-ms | Request timeout in milliseconds | 30000 | | render-price | Show product prices (boolean attribute) | false | | markdown | Enable markdown in recommendation text (boolean attribute) | false | | image-object-fit | Image fit mode: "cover" or "contain" | "cover" | | featured-items-label | Label for featured/recommended items section | "Featured Items" | | more-items-label | Label for additional items section | "More Items" | | items-label | Label for items when no recommendations | "Items" | | theme | Color theme: "light", "dark", or "auto" | "light" |

Theming

| Attribute | Description | |-----------|-------------| | brand-color | Primary brand color | | text-color | Main text color | | suggestions-text-color | Suggestions dropdown text color | | input-text-color | Search input text color | | results-text-color | Results section text color | | card-text-color | Card text color | | suggestions-hover-bg | Suggestions hover background | | muted-color | Muted/secondary text color | | input-bg | Search input background | | card-bg | Result card background | | surface-color | Surface background | | canvas-color | Canvas/page background | | results-columns | Number of grid columns for results |

Events

const el = document.querySelector("bonsai-search");

el.addEventListener("search", (e) => console.log("Query:", e.detail.query));
el.addEventListener("results", (e) => console.log("Results:", e.detail.results));
el.addEventListener("ai", (e) => console.log("AI data:", e.detail));
el.addEventListener("error", (e) => console.log("Error:", e.detail.error));

Development

npm install
npm run dev               # Watch mode (SDK)
npm run dev:webcomponents # Dev server (web components)
npm run build             # Build SDK
npm run build:webcomponents       # Build web components (IIFE for CDN)
npm run build:webcomponents:esm   # Build web components (ESM for npm)
npm run test              # Run tests
npm run typecheck         # Type check