Rozz Search Box Component API Reference

Overview

• The <rozz-searchbox> is a web component built with Lit that provides an AI-powered search interface.
• The component supports multiple display modes, real-time streaming responses, and flexible integration options.
• This documentation describes the API, attributes, and usage patterns for Rozz Search Box.

Quick Start

Add AI-powered search to your website in 2 lines of code. No backend required.

<!-- Include the component script -->
<script src="https://rozzum-bucket.rozz.site/rozz-searchbox.js"></script>

<!-- Add the component to your page -->
<rozz-searchbox
  data-initial-status="closed"
  data-theme-color="#d60a70">
</rozz-searchbox>

Basic Usage

• Include the component script.
• Insert the <rozz-searchbox> element with initial status and theme color.

<rozz-searchbox data-initial-status="closed"></rozz-searchbox>

Component Attributes

Display Configuration

| Property | Value | Type | Description |

|---|---|---|---|

| data-initial-status | "closed" (default), "open", "static", "link" | String | Controls the initial display state of the component. |

| Example | <rozz-searchbox data-initial-status="closed"></rozz-searchbox> | — | — |

Styling Attributes

| Property | Value | Type | Default |

|---|---|---|---|

| data-theme-color | CSS color value | String | "#d60a70" |

| data-font-family | CSS font-family value | String | "Rubik, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" |

| data-max-width | CSS size value | String | "900px" |

| data-max-height | CSS size value | String | "75vh" |

Examples

<rozz-searchbox data-theme-color="#28a745"></rozz-searchbox>
<rozz-searchbox data-font-family="'Open Sans', sans-serif"></rozz-searchbox>
<rozz-searchbox data-max-width="1200px"></rozz-searchbox>
<rozz-searchbox data-max-height="75vh"></rozz-searchbox>

Color Customization

| Attribute | Purpose | Default |

|---|---|---|

| data-query-text-color | Text color for user queries | "white" |

| data-query-background | Background color for user query blocks | "#d60a70" |

| data-result-text-color | Text color for AI responses | "#212529" |

Button Configuration

| Attribute | Description | Type | Default |

|---|---|---|---|

| data-button-text | Text displayed on the floating button | String | "ASK ANYTHING" |

| data-button-animation | Enables or disables the button pulse animation | Boolean | false |

| data-button-background | Background for the floating button | String | "" (uses theme color) |

| data-button-hover-color | Color of the button icon and text on hover | String | "black" |

Examples

<rozz-searchbox data-button-text="NEED HELP?"></rozz-searchbox>
<rozz-searchbox data-button-background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"></rozz-searchbox>
<rozz-searchbox data-button-hover-color="#0056b3"></rozz-searchbox>

Alternative via CSS

rozz-searchbox {
  --button-hover-color: #0056b3;
}

Button Positioning

| Attribute | Description | Type | Default |

|---|---|---|---|

| data-button-positioning-method | Sets the positioning method for the floating button | String | "fixed" |

Positioning properties (all CSS values):

• data-button-top-position
• data-button-right-position
• data-button-bottom-position

Examples

<rozz-searchbox
  data-button-positioning-method="fixed"
  data-button-bottom-position="20px"
  data-button-right-position="20px">
</rozz-searchbox>

<rozz-searchbox
  data-initial-status="link"></rozz-searchbox>

<rozz-searchbox
  data-initial-status="open">
</rozz-searchbox>

<rozz-searchbox
  data-initial-status="static"
  data-max-width="100%">
</rozz-searchbox>

Programmatic API

Methods

• openClickLink(domain, queryText)
• Opens the component and optionally auto-submits a query.
• This method is the primary mechanism for programmatic control, especially for initial-status="link".

Parameters

• domain (String) — The domain identifier to initialize the session. Required.
• queryText (String) — The query text to auto-submit after opening. Optional.

Returns

• Promise<void>

Behavior

• Opens the interface.
• Establishes a socket connection to the specified domain.
• If queryText is provided, the query is auto-submitted after opening.
• Maintains session continuity across multiple openClickLink() calls.

Basic Usage

const searchbox = document.getElementById('rozz-searchbox');
searchbox.openClickLink('example-domain.com');

With Auto-Submit Query

const searchbox = document.getElementById('rozz-searchbox');
searchbox.openClickLink('example-domain.com', 'What are your office hours?');

Multiple Links with Different Queries

<rozz-searchbox id="rozz-searchbox" data-initial-status="link"></rozz-searchbox>
<div id="county-links">
  <button data-domain="county-a.gov" data-query="What are your office hours?">County A Hours</button>
  <button data-domain="county-b.gov" data-query="How do I pay property taxes?">County B Taxes</button>
  <button data-domain="county-c.gov" data-query="Where is the DMV located?">County C DMV</button>
</div>
<script>
const searchbox = document.getElementById('rozz-searchbox');
document.getElementById('county-links').addEventListener('click', function(event) {
  const button = event.target.closest('button');
  if (button) {
    const domain = button.dataset.domain;
    const query = button.dataset.query;
    searchbox.openClickLink(domain, query);
  }
});
</script>

Use Cases

• Multi-tenant Systems — Different links for different domains/organizations.
• FAQ Quick Access — Pre-filled queries for common questions.
• Guided Navigation — Context-specific queries from different page sections.
• Product Demos — Multiple demo scenarios with different initial queries.
• Customer Support — Quick access to specific help topics.

Session Behavior

• Session continues across multiple openClickLink() calls.
• Each new query is added to the conversation history.
• Clicking different links builds a multi-turn conversation.
• Session persists in localStorage until cleared.

Display Modes

• Closed Mode — Component starts as a floating button. User clicks to open the search interface.
• Open Mode — Component opens automatically on page load with input ready.
• Static Mode — Component is always visible without a close button. Ideal for dedicated search pages.
• Link Mode — Component is hidden until programmatically opened via openClickLink().

Code examples for each mode are shown in sections within the Display Modes area.

Features

• Real-time Streaming — Responses stream in real-time as the AI generates them.
• Session Management — Conversations are stored in localStorage; sessions persist across page reloads; session expiration configurable (default: 24 hours).
• Multi-language Support — Component detects the user's browser language and displays appropriate placeholders and messages.
• SUPPORTED LANGUAGES:
• English, Spanish, French, German
• Italian, Portuguese, Dutch, Polish
• Russian, Japanese, Chinese (Simplified), Korean
• Arabic, Hindi
• Follow-up Suggestions — After each response, the component may display suggested follow-up questions.
• Accessibility — ARIA labels, keyboard navigation support, focus management, live regions for dynamic updates.

Advanced Examples

Custom Themed Component

<rozz-searchbox
  data-initial-status="closed"
  data-theme-color="#0f7bff"
  data-font-family="'Inter', sans-serif"
  data-button-text="HELP CENTER"
  data-button-animation="true"
  data-max-width="1200px"
  data-query-background="#0f7bff"
  data-result-text-color="#2c3e50">
</rozz-searchbox>

Embedded Page

<rozz-searchbox
  data-initial-status="static"
  data-max-width="100%"
  data-max-height="100vh"
  data-theme-color="#28a745">
</rozz-searchbox>

Multi-Domain Product Catalog

<rozz-searchbox id="product-search" data-initial-status="link"></rozz-searchbox>
<div class="product-grid">
  <div class="product" data-domain="electronics.shop" data-query="Tell me about this laptop">
    <img src="laptop.jpg" alt="Laptop">
    <button class="ask-rozz">Ask about this product</button>
  </div>
  <div class="product" data-domain="electronics.shop" data-query="What are the specs of this phone?">
    <img src="phone.jpg" alt="Phone">
    <button class="ask-rozz">Ask about this product</button>
  </div>
</div>
<script>
const searchbox = document.getElementById('product-search');
document.querySelectorAll('.ask-rozz').forEach(button => {
  button.addEventListener('click', function() {
    const product = this.closest('.product');
    searchbox.openClickLink(
      product.dataset.domain,
      product.dataset.query
    );
  });
});
</script>

Browser Support

| Browser | Version |

|---|---|

| Chrome / Edge | Latest 2 versions |

| Firefox | Latest 2 versions |

| Safari | Latest 2 versions |

| Mobile browsers | iOS Safari, Chrome Mobile |

Performance Considerations

• Bundle Size
• Production build: ~240-320KB (minified + obfuscated)
• Gzipped: ~80-100KB
• Loading Strategy
• Load the component script asynchronously:
• <script src="/static/rozz-searchbox.js" defer></script>
• Network Requirements
• WebSocket connection to Rozz servers
• Fallback to polling if WebSocket unavailable
• Automatic reconnection on connection loss

Troubleshooting

Component Not Rendering

• Ensure the script is loaded before using the component.
• Check the browser console for JavaScript errors.
• Verify the custom element is defined: customElements.get('rozz-searchbox').

Connection Issues

• Check network connectivity.
• Verify server URL configuration.
• Check the browser console for WebSocket errors.

Styling Conflicts

• The component uses Shadow DOM to prevent style conflicts.
• If styling beyond provided attributes is required, modify the component source code.

Author and Support

Note: This section includes contact details and author bios that are part of the original page footer and are excluded from the main content flow in this documentation.

Embedded Examples and References

• Custom Themed Component: See Advanced Examples above.
• Embedded Search Page: See Advanced Examples above.
• Multi-Domain Product Catalog: See Advanced Examples above.