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

--bonsai-brand-color

default:"#0a5b3b"

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

--bonsai-text-color

default:"#303030"

Primary text color for main content.

--bonsai-input-text-color

default:"#303030"

Text color for input field and search icon.

--bonsai-suggestions-text-color

default:"#303030"

Text color for suggestion items.

--bonsai-results-text-color

default:"#303030"

Text color for AI summary and section headers.

--bonsai-card-text-color

default:"#303030"

Text color for result card content.

--bonsai-muted-color

default:"#9ca3af"

Secondary text color for less prominent content.

--bonsai-input-bg

default:"#f5f5f5"

Background color for input field and dropdown areas.

--bonsai-card-bg

default:"#f5f5f5"

Background color for result cards.

--bonsai-canvas-color

default:"#fafafa"

Background color for the main canvas area.

--bonsai-surface-color

default:"#ffffff"

Background color for elevated surfaces.

--bonsai-border-color

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

Default border color.

--bonsai-border-color-hover

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

Border color on hover state.

--bonsai-hover-bg

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

Background color for hover states.

--bonsai-suggestions-hover-bg

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

Background color when hovering over suggestion items.

--bonsai-error-bg

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

Background color for error states.

--bonsai-error-color

default:"#c82333"

Text color for error messages.

Spacing

--bonsai-space-1

default:"0.25rem"

Smallest spacing unit (4px).

--bonsai-space-2

default:"0.5rem"

Extra small spacing unit (8px).

--bonsai-space-3

default:"0.75rem"

Small spacing unit (12px).

--bonsai-space-4

default:"1rem"

Base spacing unit (16px).

--bonsai-space-5

default:"1.25rem"

Medium spacing unit (20px).

--bonsai-space-6

default:"1.5rem"

Large spacing unit (24px).

Typography

--bonsai-font-heading

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

Font family for headings and section titles.

--bonsai-font-body

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

Font family for body text.

--bonsai-font-mono

default:"ui-monospace, monospace"

Font family for monospace text.

--bonsai-font-size-xs

default:"0.75rem"

Extra small font size (12px).

--bonsai-font-size-sm

default:"0.875rem"

Small font size (14px).

--bonsai-font-size-base

default:"1rem"

Base font size (16px).

--bonsai-font-size-lg

default:"1.125rem"

Large font size (18px).

--bonsai-font-size-xl

default:"1.25rem"

Extra large font size (20px).

Border Radius

--bonsai-radius-none

default:"0"

No border radius.

--bonsai-radius-sm

default:"0.25rem"

Small border radius (4px).

--bonsai-radius-md

default:"0.375rem"

Medium border radius (6px).

--bonsai-radius-lg

default:"0.5rem"

Large border radius (8px).

--bonsai-radius-xl

default:"0.75rem"

Extra large border radius (12px).

--bonsai-radius-full

default:"9999px"

Full border radius for pill-shaped elements.

Animation

--bonsai-duration-fast

default:"150ms"

Fast animation duration for quick transitions.

--bonsai-duration-base

default:"200ms"

Base animation duration for standard transitions.

--bonsai-duration-slow

default:"300ms"

Slow animation duration for emphasized transitions.

--bonsai-easing

timing-function

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

Easing function for smooth animations.

Shadow

--bonsai-shadow-sm

shadow

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

Small shadow for subtle elevation.

--bonsai-shadow-md

shadow

Medium shadow for moderate elevation.

--bonsai-shadow-lg

shadow

Large shadow for prominent elevation.

Layout

--bonsai-search-min-height

default:"3.5rem"

Minimum height for the search bar (56px).

--bonsai-search-max-width

default:"42rem"

Maximum width for the search container (672px).

--bonsai-icon-size

default:"1.25rem"

Standard icon size (20px).

--bonsai-icon-size-sm

default:"1rem"

Small icon size (16px).

--bonsai-results-columns

default:"3"

Number of columns in the results grid layout.

--bonsai-image-object-fit

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

Documentation Index

​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