@lumifyai/widget

A self-contained, zero-config AI search widget for any website. Add intelligent search to your site with a single script tag.

Quick Start

Add this script tag to your website:

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID">
</script>

That's it! A search button will appear in the bottom-right corner of your page.

Installation

CDN (Recommended)

<script src="https://www.lumify.ai/api/v1/js/lumify-widget.js"></script>

npm

npm install @lumifyai/widget

unpkg

<script src="https://unpkg.com/@lumifyai/widget"></script>

jsdelivr

<script src="https://cdn.jsdelivr.net/npm/@lumifyai/widget"></script>

Configuration

All configuration is done via data-* attributes on the script tag:

Required

| Attribute | Description | |-----------|-------------| | data-api-key | Your Lumify API key | | data-app-id | Your application ID |

Display Options

| Attribute | Default | Description | |-----------|---------|-------------| | data-mode | "floating" | "floating" | "inline" | "trigger" | | data-theme | "auto" | "light" | "dark" | "auto" | | data-position | "bottom-right" | "bottom-right" | "bottom-left" | "top-right" | "top-left" | | data-accent-color | "#6366f1" | Any CSS color value | | data-z-index | 9999 | CSS z-index for the widget |

Button Options

| Attribute | Default | Description | |-----------|---------|-------------| | data-button-icon | "search" | "search" | "chat" | "help" | "none" | | data-button-text | "" | Optional text next to the button |

Text Customization

| Attribute | Default | Description | |-----------|---------|-------------| | data-modal-title | "Search" | Title in the modal header | | data-placeholder | "Ask anything..." | Input placeholder text | | data-empty-text | "Ask a question to get started" | Empty state message |

Behavior Options

| Attribute | Default | Description | |-----------|---------|-------------| | data-keyboard-shortcut | "true" | Enable Cmd/Ctrl+K shortcut | | data-show-branding | "true" | Show "Powered by Lumify" footer |

Popular Questions

Show commonly asked questions when users focus on the search input:

| Attribute | Default | Description | |-----------|---------|-------------| | data-popular-questions | "false" | Enable popular questions | | data-popular-questions-max | 5 | Maximum questions to show (1-10) | | data-popular-questions-cache | "localStorage" | "localStorage" | "sessionStorage" | "none" | | data-popular-questions-ttl | 86400 | Cache lifetime in seconds | | data-popular-questions-fallback | [] | JSON array of fallback questions |

Mode-Specific Options

| Attribute | Description | |-----------|-------------| | data-trigger-selector | CSS selector for trigger mode | | data-container-selector | CSS selector for inline mode container |

Examples

Floating Button (Default)

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID">
</script>

Dark Theme with Custom Color

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID"
  data-theme="dark"
  data-accent-color="#10b981">
</script>

Documentation Site

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID"
  data-modal-title="Search Docs"
  data-placeholder="Search documentation..."
  data-empty-text="Type a question to search the docs">
</script>

Trigger Mode (Attach to Existing Button)

<button id="my-search-btn">Search</button>

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID"
  data-mode="trigger"
  data-trigger-selector="#my-search-btn">
</script>

Inline Mode

<div id="search-container"></div>

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID"
  data-mode="inline"
  data-container-selector="#search-container">
</script>

With Popular Questions

<script 
  src="https://www.lumify.ai/api/v1/js/lumify-widget.js"
  data-api-key="YOUR_API_KEY"
  data-app-id="YOUR_APP_ID"
  data-popular-questions="true"
  data-popular-questions-max="5">
</script>

Live Examples

Visit lumify.ai/api/v1/examples to see interactive demos.

Platform Guides

• Webflow Integration Guide docs.lumify.ai/webflow-guide
• Wordpress Integration Guide docs.lumify.ai/wordpress-guide

API Reference

For programmatic control, the widget exposes a global LumifyWidget object:

// Open the search modal
LumifyWidget.open();

// Close the search modal
LumifyWidget.close();

// Toggle the search modal
LumifyWidget.toggle();

// Perform a search
LumifyWidget.search('your query');

// Destroy the widget
LumifyWidget.destroy();

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT © Lumify

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: docs.lumify.ai