Rozz Box Component API REFERENCE

Source:

Published:

Keywords: Rozz, rozz-searchbox, web component, JavaScript API, Lit

Document ID: https://rozz.site/pages/rozz-chatbot-component-api-specs.html#split1

QUICK START

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

TABLE OF CONTENTS

Overview

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

KEY FEATURES

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.

| Property | Value | | --- | --- | | Type | String | | Options | "closed" (default) - Component starts as a floating button, opens as fullscreen modal "open" - Component opens automatically on page load as fullscreen modal "chat" - Component starts as a floating button, opens as a compact chatbot popup panel "static" - Component is always visible (no close button) "link" - Component is hidden until programmatically opened |

Example: 

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

Styling Attributes

data-theme-color sets the primary theme color for the component.

| Property | Value | | --- | --- | | Type | String (CSS color value) | | Default | "#d60a70" |

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

data-font-family sets the font family for the component.

| Property | Value | | --- | --- | | Type | String (CSS font-family value) | | Default | "Rubik, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" |

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

data-max-width sets the maximum width of the modal.

| Property | Value | | --- | --- | | Type | String (CSS size value) | | Default | "900px" |

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

data-max-height sets the maximum height of the modal.

| Property | Value | | --- | --- | | Type | String (CSS size value) | | Default | "75vh" |

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

data-button-text sets the text displayed on the floating button.

| Property | Value | | --- | --- | | Type | String | | Default | "ASK ANYTHING" |

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

data-button-animation enables or disables the button pulse animation.

| Property | Value | | --- | --- | | Type | Boolean | | Default | false |

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

data-button-background sets a custom background for the floating button.

| Property | Value | | --- | --- | | Type | String (CSS background value) | | Default | "" (uses theme color) |

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

| Property | Value | | --- | --- | | Type | String (CSS color value) | | Default | "black" |

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

| Property | Value | | --- | --- | | Type | String | | Options | "fixed" (default) - Button stays in viewport "standard" - Button positioned relative to document flow |

Position Properties

| Attribute | Purpose | Type |

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

| data-button-top-position | Sets the top position of the floating button | CSS position value |

| data-button-right-position | Sets the right position of the floating button | CSS position value |

| data-button-bottom-position | Sets the bottom position of the floating button | CSS position value |

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

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | domain | String | ✓ | The domain identifier to initialize the session | | queryText | String | ✗ | The query text to auto-submit after opening |

Returns: Promise<void>

BEHAVIOR:

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>

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

Session Behavior

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 input ready.

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

Chat Mode

Component displays as a compact chatbot popup panel (380×520px) anchored near the floating button. The page remains fully interactive — no backdrop overlay. The panel stays open until the user explicitly closes it via the X button, the floating button, or the Escape key. Conversations persist across open/close cycles. On mobile viewports (< 500px), the panel automatically switches to fullscreen.

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

Static Mode

Component is always visible without a close button. Ideal for dedicated 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

Multi-language Support

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

SUPPORTED LANGUAGES:

Follow-up Suggestions

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

Accessibility

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

| 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

Loading Strategy

For optimal performance, load the component script asynchronously:

<script src="/static/rozz-searchbox.js" defer></script>

Network Requirements

Troubleshooting

Component Not Rendering

Connection Issues

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.

> Warning: ● SUPPORT > For issues, questions, or feature requests, please contact rozz@rozz.site

AUTHOR

, Co-Founder & CEO, ROZZ

Serial tech entrepreneur with 10+ years experience building AI systems including Aristotle (conversational AI analytics) and products for eBay and Cartier. Founded Squid Solutions (Big Data analytics).