Rozz Search Box Component API REFERENCE

Overview

The <rozz-searchbox> is a web component built with Lit that provides an AI-powered search interface. It supports multiple display modes, real-time streaming responses, and flexible integration options.

Basic Usage

Add the component script and insert the element:

<!-- 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>

Component Attributes

Display Configuration

data-initial-status

Controls the initial display state of the component.

Example:

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

Styling Attributes

data-theme-color

Sets the primary theme color for the component.

<rozz-searchbox data-theme-color="#28a745"></rozz-searchbox>

data-font-family

Sets the font family for the component.

<rozz-searchbox data-font-family="'Open Sans', sans-serif"></rozz-searchbox>

data-max-width

Sets the maximum width of the search modal.

<rozz-searchbox data-max-width="1200px"></rozz-searchbox>

data-max-height

Sets the maximum height of the search modal.

Color Customization

Button Configuration

data-button-text

Sets the text displayed on the floating button.

<rozz-searchbox data-button-text="NEED HELP?"></rozz-searchbox>

data-button-animation

Enables or disables the button pulse animation.

<rozz-searchbox data-button-animation="true"></rozz-searchbox>

data-button-background

Sets a custom background for the floating button.

<rozz-searchbox
  data-button-background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)">
</rozz-searchbox>

data-button-hover-color

Sets the color of the button icon and text on hover.

<rozz-searchbox data-button-hover-color="#0056b3"></rozz-searchbox>

Alternative via CSS:

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

Button Positioning

data-button-positioning-method

Sets the positioning method for the floating button.

Position Properties

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

Programmatic API

Methods

openClickLink(domain, queryText)

Opens the component and optionally auto-submits a query. This is the primary method for programmatic control, especially useful for the initial-status="link" mode.

Returns: Promise<void>

Example - Basic Usage:

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

Example - With Auto-Submit Query:

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

Example - 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>

Session Behavior

• Session continues across multiple openClickLink() calls
• Each new query is added to the conversation history
• Clicking different links builds up 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.

<rozz-searchbox
  data-initial-status="closed"
  data-button-text="ASK ANYTHING">
</rozz-searchbox>

Open Mode

Component opens automatically on page load with search input ready.

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

Static Mode

Component is always visible without a close button. Ideal for dedicated search pages.

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

Link Mode

Component is hidden until programmatically opened via openClickLink(). Perfect for multi-tenant scenarios or context-specific queries.

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

<script>
  // Trigger programmatically
  const searchbox = document.getElementById('rozz-searchbox');
  document.getElementById('help-link').addEventListener('click', () => {
    searchbox.openClickLink('example-domain.com', 'How can I get support?');
  });
</script>

Features

Real-time Streaming

Responses stream in real-time as the AI generates them, providing immediate feedback.

Session Management

• Conversations are stored in localStorage
• Sessions persist across page reloads
• Session expiration configurable (default: 24 hours)

Multi-language Support

Component automatically detects user's browser language and displays appropriate placeholders and messages.

Follow-up Suggestions

After each response, the component may display suggested follow-up questions to help users continue the conversation.

Accessibility

• ✓ ARIA labels for screen readers
• ✓ Keyboard navigation support
• ✓ Focus management
• ✓ Live regions for dynamic content updates

Advanced Examples

Custom Themed Component

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

Embedded Search 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

Performance Considerations

Bundle Size

• Production build: ~240-320KB (minified + obfuscated)
• Gzipped: ~80-100KB

Loading Strategy

For optimal performance, 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 browser console for JavaScript errors
• Verify custom element is defined: customElements.get('rozz-searchbox')

Connection Issues

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

Styling Conflicts

The component uses Shadow DOM to prevent style conflicts. If you need to customize styles beyond the provided attributes, you'll need to modify the component source code.