Advanced Styling

Where styling lives as of SDK v3.2+. Colors, borders, layout, and shadows are driven by CSS custom properties — not by HTML attributes. These variables can be set two ways:

From the Settings API (preferred) — theming is configured per-tenant in the Bonsai dashboard and injected into the component’s shadow DOM automatically at load time.
From your page’s CSS — override any variable on the <bonsai-search> host element (or its container) to customize per-embed. Page CSS wins over the Settings API because Settings-API variables are injected at :host low specificity.

Legacy HTML attributes like brand-color, text-color, input-bg, card-bg, etc. are no longer supported — use the variables on this page instead.

Outer Container

If you want to customize the layout and positioning, wrap the component in a container and add custom CSS.

Example:

<style>
  .bonsai-search-outer-container {
    width: 100%;
    max-width: 42rem;
    margin: 4rem auto;
    min-height: 350px;
  }

  bonsai-search {
    --bonsai-brand-color: #0A5B3B;
    --bonsai-text-color: #303030;
    --bonsai-muted-color: #9CA3AF;
  }
</style>

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

CSS Variables

The web component uses a closed shadow root, but CSS custom properties still pass through. You can set any --bonsai-* variables directly on the <bonsai-search> element if you prefer CSS-only customization.

Example:

<bonsai-search
  style="
    --bonsai-font-body: 'Space Grotesk', sans-serif;
    --bonsai-font-heading: 'Space Grotesk', sans-serif;
    --bonsai-font-mono: 'IBM Plex Mono', monospace;
    --bonsai-search-max-width: 100%;
    --bonsai-text-color: #111111;
    --bonsai-muted-color: #6b7280;
    --bonsai-input-bg: #ffffff;
    --bonsai-input-text-color: #111111;
    --bonsai-suggestions-text-color: #111111;
    --bonsai-suggestions-hover-bg: rgba(0, 0, 0, 0.06);
    --bonsai-results-text-color: #eaeaea;
    --bonsai-card-text-color: #111111;
  "
  api-key="API-KEY"
  base-url="https://api.hibonsai.com/rest/search/v3/"
  theme="dark"
></bonsai-search>

Reference Table

Defaults shown are for the light theme. The dark theme automatically overrides color and shadow variables.

Variable	Default	Purpose
`--bonsai-brand-color`	`#0a5b3b`	Accent color for focus, buttons, and highlights
`--bonsai-text-color`	`#303030`	Primary text
`--bonsai-suggestions-text-color`	`#303030`	Suggestions text
`--bonsai-input-text-color`	`#303030`	Input text + icon
`--bonsai-results-text-color`	`#303030`	Summary + section headers
`--bonsai-card-text-color`	`#303030`	Result card text
`--bonsai-muted-color`	`#9ca3af`	Secondary text
`--bonsai-input-bg`	`#f5f5f5`	Input + dropdown background
`--bonsai-card-bg`	`#f5f5f5`	Result card background
`--bonsai-canvas-color`	`#fafafa`	Page/canvas background
`--bonsai-surface-color`	`#ffffff`	Surface background
`--bonsai-border-color`	`rgba(0, 0, 0, 0.06)`	Default border
`--bonsai-border-color-hover`	`rgba(0, 0, 0, 0.12)`	Hover border
`--bonsai-hover-bg`	`rgba(0, 0, 0, 0.04)`	Hover background
`--bonsai-suggestions-hover-bg`	`rgba(0, 0, 0, 0.04)`	Suggestions hover
`--bonsai-error-bg`	`rgba(220, 53, 69, 0.1)`	Error background
`--bonsai-error-color`	`#c82333`	Error text
`--bonsai-space-1`	`0.25rem`	Spacing token
`--bonsai-space-2`	`0.5rem`	Spacing token
`--bonsai-space-3`	`0.75rem`	Spacing token
`--bonsai-space-4`	`1rem`	Spacing token
`--bonsai-space-5`	`1.25rem`	Spacing token
`--bonsai-space-6`	`1.5rem`	Spacing token
`--bonsai-font-heading`	`system-ui, -apple-system, sans-serif`	Heading font
`--bonsai-font-body`	`system-ui, -apple-system, sans-serif`	Body font
`--bonsai-font-mono`	`ui-monospace, monospace`	Mono font
`--bonsai-font-size-xs`	`0.75rem`	Text size
`--bonsai-font-size-sm`	`0.875rem`	Text size
`--bonsai-font-size-base`	`1rem`	Text size
`--bonsai-font-size-lg`	`1.125rem`	Text size
`--bonsai-font-size-xl`	`1.25rem`	Text size
`--bonsai-radius-none`	`0`	Radius token
`--bonsai-radius-sm`	`0.25rem`	Radius token
`--bonsai-radius-md`	`0.375rem`	Radius token
`--bonsai-radius-lg`	`0.5rem`	Radius token
`--bonsai-radius-xl`	`0.75rem`	Radius token
`--bonsai-radius-full`	`9999px`	Full radius
`--bonsai-duration-fast`	`150ms`	Animation timing
`--bonsai-duration-base`	`200ms`	Animation timing
`--bonsai-duration-slow`	`300ms`	Animation timing
`--bonsai-easing`	`cubic-bezier(0, 0, 0.2, 1)`	Animation easing
`--bonsai-shadow-sm`	`0 1px 2px 0 rgb(0 0 0 / 0.05)`	Shadow token
`--bonsai-shadow-md`	`0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)`	Shadow token
`--bonsai-shadow-lg`	`0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)`	Shadow token
`--bonsai-search-min-height`	`3.5rem`	Search bar height
`--bonsai-search-max-width`	`42rem`	Max container width
`--bonsai-icon-size`	`1.25rem`	Icon size
`--bonsai-icon-size-sm`	`1rem`	Small icon size
`--bonsai-results-columns`	`3`	Results grid columns
`--bonsai-image-object-fit`	`cover`	Image sizing mode

Color

default:"#0a5b3b"

Accent color used for focus states, buttons, and highlights throughout the component.

default:"#303030"

Primary text color for main content.

default:"#303030"

Text color for input field and search icon.

default:"#303030"

Text color for suggestion items.

default:"#303030"

Text color for AI summary and section headers.

default:"#303030"

Text color for result card content.

default:"#9ca3af"

Secondary text color for less prominent content.

default:"#f5f5f5"

Background color for input field and dropdown areas.

default:"#f5f5f5"

Background color for result cards.

default:"#fafafa"

Background color for the main canvas area.

default:"#ffffff"

Background color for elevated surfaces.

default:"rgba(0, 0, 0, 0.06)"

Default border color.

default:"rgba(0, 0, 0, 0.12)"

Border color on hover state.

default:"rgba(0, 0, 0, 0.04)"

Background color for hover states.

default:"rgba(0, 0, 0, 0.04)"

Background color when hovering over suggestion items.

default:"rgba(220, 53, 69, 0.1)"

Background color for error states.

default:"#c82333"

Text color for error messages.

Spacing

default:"0.25rem"

Smallest spacing unit (4px).

default:"0.5rem"

Extra small spacing unit (8px).

default:"0.75rem"

Small spacing unit (12px).

default:"1rem"

Base spacing unit (16px).

default:"1.25rem"

Medium spacing unit (20px).

default:"1.5rem"

Large spacing unit (24px).

Typography

default:"system-ui, -apple-system, sans-serif"

Font family for headings and section titles.

default:"system-ui, -apple-system, sans-serif"

Font family for body text.

default:"ui-monospace, monospace"

Font family for monospace text.

default:"0.75rem"

Extra small font size (12px).

default:"0.875rem"

Small font size (14px).

default:"1rem"

Base font size (16px).

default:"1.125rem"

Large font size (18px).

default:"1.25rem"

Extra large font size (20px).

Border Radius

default:"0"

No border radius.

default:"0.25rem"

Small border radius (4px).

default:"0.375rem"

Medium border radius (6px).

default:"0.5rem"

Large border radius (8px).

default:"0.75rem"

Extra large border radius (12px).

default:"9999px"

Full border radius for pill-shaped elements.

Animation

default:"150ms"

Fast animation duration for quick transitions.

default:"200ms"

Base animation duration for standard transitions.

default:"300ms"

Slow animation duration for emphasized transitions.

timing-function

default:"cubic-bezier(0, 0, 0.2, 1)"

Easing function for smooth animations.

Shadow

shadow

default:"0 1px 2px 0 rgb(0 0 0 / 0.05)"

Small shadow for subtle elevation.

shadow

Medium shadow for moderate elevation.

shadow

Large shadow for prominent elevation.

Layout

default:"3.5rem"

Minimum height for the search bar (56px).

default:"42rem"

Maximum width for the search container (672px).

default:"1.25rem"

Standard icon size (20px).

default:"1rem"

Small icon size (16px).

default:"3"

Number of columns in the results grid layout.

default:"cover"

CSS object-fit value for product images. Options: cover or contain.

Shadow Parts

The web component uses a closed shadow root, but it exposes stable part hooks for external styling. This lets you style specific inner elements with ::part(...) from outside the component. ::part(...) is supported in modern evergreen browsers. For older browsers, prefer CSS variables or wrapper styling. Example (full part customization):

<style>
  bonsai-search::part(search-wrapper) {
    padding: 1.5rem;
    border: 1px solid #262626;
    border-radius: 18px;
    background: linear-gradient(180deg, #0b0b0b 0%, #0f0f0f 100%);
  }

  bonsai-search::part(search-bar) {
    border-radius: 14px;
    border: 1px solid #303030;
    background: #111111;
    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
  }

  bonsai-search::part(search-icon) {
    color: #c9a77a;
  }

  bonsai-search::part(search-input) {
    color: #f7f3ee;
    letter-spacing: 0.01em;
  }

  bonsai-search::part(search-actions) {
    gap: 0.25rem;
  }

  bonsai-search::part(submit-button) {
    background: #c9a77a;
    color: #111111;
    border-radius: 10px;
  }

  bonsai-search::part(loading-state) {
    background: #161616;
    border-radius: 10px;
  }

  bonsai-search::part(loading-text) {
    color: #c9a77a;
  }

  bonsai-search::part(loading-text-inner) {
    font-weight: 600;
  }

  bonsai-search::part(spinner) {
    color: #c9a77a;
  }

  bonsai-search::part(done-state) {
    background: #142218;
    border-radius: 10px;
  }

  bonsai-search::part(done-text) {
    color: #a7f3d0;
  }

  bonsai-search::part(done-icon) {
    color: #34d399;
  }

  bonsai-search::part(reset-button) {
    border-radius: 10px;
    border: 1px solid #2a2a2a;
  }

  bonsai-search::part(reset-text) {
    color: #e5e7eb;
  }

  bonsai-search::part(reset-icon) {
    color: #9ca3af;
  }

  bonsai-search::part(suggestions) {
    background: #101010;
    border: 1px solid #2a2a2a;
  }

  bonsai-search::part(suggestion-item) {
    border-radius: 10px;
  }

  bonsai-search::part(suggestion-text) {
    color: #f3f4f6;
  }

  bonsai-search::part(suggestion-arrow) {
    color: #c9a77a;
  }

  bonsai-search::part(powered-by) {
    color: #9ca3af;
  }

  bonsai-search::part(results) {
    padding: 1rem 0 0 0;
  }

  bonsai-search::part(results-section) {
    border-top: 1px dashed #2a2a2a;
    padding-top: 1.25rem;
  }

  bonsai-search::part(results-header) {
    color: #c9a77a;
  }

  bonsai-search::part(results-grid) {
    gap: 1.25rem;
  }

  bonsai-search::part(summary) {
    padding: 1rem 1.25rem;
    border-radius: 14px;
    background: #0f0f0f;
    border: 1px solid #262626;
  }

  bonsai-search::part(summary-text) {
    color: #e5e7eb;
  }

  bonsai-search::part(recommendation-products) {
    margin-top: 1rem;
  }

  bonsai-search::part(recommendation-products-header) {
    color: #c9a77a;
    letter-spacing: 0.06em;
  }

  bonsai-search::part(result-card) {
    background: #111111;
    border: 1px solid #262626;
    border-radius: 16px;
    overflow: hidden;
  }

  bonsai-search::part(result-image-wrapper) {
    background: #0b0b0b;
  }

  bonsai-search::part(result-image) {
    filter: saturate(0.95);
  }

  bonsai-search::part(result-content) {
    padding: 0.75rem 0.9rem;
  }

  bonsai-search::part(result-title) {
    color: #f9fafb;
  }

  bonsai-search::part(result-price-container) {
    gap: 0.35rem;
  }

  bonsai-search::part(result-price) {
    color: #c9a77a;
  }

  bonsai-search::part(result-compare-at) {
    color: #6b7280;
  }

  bonsai-search::part(result-caption) {
    color: #d1d5db;
  }

  bonsai-search::part(recommendations-loading) {
    border: 1px dashed #2a2a2a;
    border-radius: 12px;
  }

  bonsai-search::part(recommendations-loading-spinner) {
    color: #c9a77a;
  }

  bonsai-search::part(recommendations-loading-text) {
    color: #e5e7eb;
  }

  bonsai-search::part(empty-state) {
    color: #9ca3af;
    background: #0f0f0f;
    border-radius: 12px;
    padding: 1rem;
  }

  bonsai-search::part(error) {
    background: #2a0f12;
    border: 1px solid #7f1d1d;
    color: #fecaca;
    padding: 0.75rem 1rem;
    border-radius: 10px;
  }
</style>

Reference Table

Group	Part	Description
Search	`search-wrapper`	Outer wrapper
Search	`search-bar`	Input container
Search	`search-icon`	Left icon
Search	`search-input`	Input field
Search	`search-actions`	Action button container
Search	`submit-button`	Submit action
Search	`loading-state`	Loading pill
Search	`loading-text`	Loading text
Search	`loading-text-inner`	Emphasized loading text
Search	`spinner`	Loading spinner
Search	`done-state`	Done pill
Search	`done-text`	Done text
Search	`done-icon`	Done icon
Search	`reset-button`	Reset action
Search	`reset-text`	Reset text
Search	`reset-icon`	Reset icon
Suggestions	`suggestions`	Suggestions container
Suggestions	`suggestion-item`	Suggestion row
Suggestions	`suggestion-text`	Suggestion text
Suggestions	`suggestion-arrow`	Suggestion icon
Footer	`powered-by`	Powered by footer
Results	`results`	Results container
Results	`results-section`	Results section
Results	`results-header`	Results header
Results	`results-grid`	Results grid
Results	`summary`	AI summary container
Results	`summary-text`	AI summary text
Results	`recommendation-products`	Recommendations block
Results	`recommendation-products-header`	Recommendations header
Cards	`result-card`	Result card
Cards	`result-image-wrapper`	Result image wrapper
Cards	`result-image`	Result image
Cards	`result-content`	Result content
Cards	`result-title`	Result title
Cards	`result-price-container`	Price wrapper
Cards	`result-price`	Price
Cards	`result-compare-at`	Compare-at price
Cards	`result-caption`	Description
States	`recommendations-loading`	Recommendations loading container
States	`recommendations-loading-spinner`	Recommendations spinner
States	`recommendations-loading-text`	Recommendations text
States	`empty-state`	Empty state
States	`error`	Error state

Customization Tips

Theme Defaults vs. Overrides

theme="light" (default) and theme="dark" set a full palette of sensible defaults for surfaces, borders, shadows, and text. Any CSS custom properties you set (like --bonsai-text-color, --bonsai-input-bg, or --bonsai-card-bg) override those defaults. theme="auto" uses the visitor’s system preference (prefers-color-scheme) and still respects any explicit overrides.

Where styling values come from

Precedence, highest to lowest:

Your page CSS — any --bonsai-* variable set on the <bonsai-search> host element, on an ancestor, or in a :root rule.
Settings API — values configured per-tenant from the Bonsai dashboard; the component injects a low-specificity :host { ... } block of CSS variables into its shadow DOM at load time.
Built-in theme defaults — the palette for the active theme (light / dark / auto).

Set defaults once in the Settings API to theme all embeds for a tenant; only write page CSS when you need to override a specific embed.

Wrapper Styling

The example includes a wrapper <div> with custom CSS to control the component’s width and positioning. You can modify these styles to match your site’s layout:

.bonsai-search-outer-container {
  width: 100%;
  max-width: 42rem; /* Adjust maximum width */
  margin: 4rem auto; /* Adjust vertical and horizontal spacing */
  min-height: 350px; /* Ensure minimum height for layout stability */
}

Color Scheme

Choose colors that match your brand identity. The component uses your specified colors throughout the interface:

--bonsai-brand-color: Used for primary actions and highlights
--bonsai-text-color: Used for main content text
--bonsai-muted-color: Used for secondary information
Background colors: Control the overall appearance
- --bonsai-input-bg affects the input and the dropdown background
- --bonsai-card-bg affects result cards
- --bonsai-surface-color and --bonsai-canvas-color control larger surfaces

Suggestions Best Practices

Create suggestions that:

Address common customer questions
Highlight popular products or features
Use natural, conversational language
Are specific to your product catalog

Get Started

Web Components

Support

Advanced Styling

Outer Container

CSS Variables

Reference Table

Color

Spacing

Typography

Border Radius

Animation

Shadow

Layout

Shadow Parts

Reference Table

Customization Tips

Theme Defaults vs. Overrides

Where styling values come from

Wrapper Styling

Color Scheme

Suggestions Best Practices

​Outer Container

​CSS Variables

​Reference Table

​Color

​Spacing

​Typography

​Border Radius

​Animation

​Shadow

​Layout

​Shadow Parts

​Reference Table

​Customization Tips

​Theme Defaults vs. Overrides

​Where styling values come from

​Wrapper Styling

​Color Scheme

​Suggestions Best Practices

Outer Container

CSS Variables

Reference Table

Color

Spacing

Typography

Border Radius

Animation

Shadow

Layout

Shadow Parts

Reference Table

Customization Tips

Theme Defaults vs. Overrides

Where styling values come from

Wrapper Styling

Color Scheme

Suggestions Best Practices