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

All options are data-prefixed attributes set on the <rozz-searchbox> tag. Three of them also accept a legacy un-prefixed form, kept for backward compatibility with early embeds: initial-status, positioning-method and chat-open. Prefer the data- form in new installs; if both are present, the data- form wins.

Unrecognised values fall back silently. An attribute set to a value the component does not know (a typo like data-initial-status="chatt") is not an error and produces no console warning — it falls through to that attribute's default behavior. Check spelling if an option appears to have no effect.

Display Configuration

data-initial-status

Controls the initial display state of the component.

Example:

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

data-chat-open

Opens the chat panel on page load instead of waiting for a click on the floating button. Only applies when data-initial-status="chat" — the other display modes ignore it.

A panel that opens by itself starts in the compact layout, sized per breakpoint:

On phones the sheet has a grab handle at the top: drag it up to expand, drag it down to collapse back to the peek, and drag it down again from the peek to close. Tapping the handle toggles between the two sizes, as does the expand control in the header. Opening the panel from the floating button still starts expanded on every viewport.

Example:

<rozz-searchbox
  data-initial-status="chat"
  data-chat-open>
</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.

Only the exact string "true" turns the animation on. Unlike data-chat-open, this option does not accept a bare attribute: <rozz-searchbox data-button-animation> leaves the animation off, as does any other value ("1", "yes", "on").

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

Chat Mode

Component displays as a chatbot panel anchored near the floating button — a 380×520 docked card above 500px, and a bottom sheet on phones. Conversations persist across open/close cycles. The panel is closed by the × button, the floating button, or the Escape key.

Clicking outside the panel does not close it on desktop. On phones, the expanded sheet (88dvh) has a dimming scrim and tapping it closes the panel; the compact peek has no scrim, so the host page stays lit and taps pass through to it.

By default the panel starts closed and the visitor opens it from the floating button. Add data-chat-open to have it already open on page load, in its compact layout — on phones that is a short peek — about a third of the screen — with no backdrop, draggable to full height by its grab handle. Use data-chat-open="desktop" to keep phones on the floating button instead. Closing the panel is remembered for the rest of the visitor’s 24-hour session, so they are never asked twice.

<rozz-searchbox
  data-initial-status="chat"
  data-theme-color="#d60a70"
  data-button-animation="true">
</rozz-searchbox>

<!-- Same panel, already open when the page loads -->
<rozz-searchbox
  data-initial-status="chat"
  data-chat-open
  data-theme-color="#d60a70">
</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. This is the same set accepted by data-greeting-message language maps; a visitor outside this set gets the English strings.

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: ~520KB (minified + obfuscated)
• Gzipped: ~157KB

Loading Strategy

For optimal performance, load the component script asynchronously:

<script src="https://rozzum-bucket.rozz.site/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.