Props

CSS Variables

Live Preview

Generated Code

index.html
App.tsx
App.vue

Quick Start Guide

Add search and chat to your website in minutes.

index.html
<!-- Import the library -->
<script type="module" src="https://<hash>.search.ai.cloudflare.com/assets/v0.0.35/search-snippet.es.js"></script>

<!-- 1. Chat Bubble Widget (Fixed bottom-right) -->
<chat-bubble-snippet 
    api-url="https://api.example.com">
</chat-bubble-snippet>

<!-- 2. Search Bar Widget -->
<search-bar-snippet 
    api-url="https://api.example.com"
    placeholder="Search..."
    max-results="10"
    show-url="true"
    show-date="true">
</search-bar-snippet>

<!-- 3. Search Modal (Cmd/Ctrl+K to open) -->
<search-modal-snippet 
    api-url="https://api.example.com"
    placeholder="Search documentation..."
    shortcut="k"
    show-url="true"
    show-date="true">
</search-modal-snippet>

<!-- 4. Full Page Chat (use in dedicated page) -->
<chat-page-snippet 
    api-url="https://api.example.com">
</chat-page-snippet>

<!-- Customize with CSS Variables -->
<style>
    chat-bubble-snippet {
        --search-snippet-primary-color: #F6821F;
        --search-snippet-border-radius: 12px;
    }
</style>
App.tsx
import "@cloudflare/ai-search-snippet";

// Usage in your app
export default function App() {
  return (
    <div>
      <search-bar-snippet 
        apiUrl="https://api.example.com"
        placeholder="Search..."
        maxResults={10}
        show-url="true"
        show-date="true"
      />

      {/* Chat Bubble - works directly as Web Component */}
      <chat-bubble-snippet 
        apiUrl="https://api.example.com"
        style={{ '--search-snippet-primary-color': '#F6821F' } as React.CSSProperties}
      />

      {/* Search Modal with keyboard shortcut */}
      <search-modal-snippet 
        apiUrl="https://api.example.com"
        placeholder="Search documentation..."
        shortcut="k"
        show-url="true"
        show-date="true"
      />
    </div>
  );
}

// TypeScript declarations see example here: https://github.com/cloudflare/ai-search-snippet/blob/main/demos/react/index.d.ts
App.vue
<script setup lang="ts">
import "@cloudflare/ai-search-snippet";
import { ref } from 'vue';

const apiUrl = 'https://api.example.com';
const searchPlaceholder = ref('Search...');
const maxResults = ref(10);

// Handle custom events from components
function onSearchComplete(event: CustomEvent) {
  console.log('Search results:', event.detail);
}

function onChatMessage(event: CustomEvent) {
  console.log('Chat message:', event.detail);
}
</script>

<template>
  <div>
    <!-- Search Bar with v-bind -->
    <search-bar-snippet
      :api-url="apiUrl"
      :placeholder="searchPlaceholder"
      :max-results="maxResults"
      show-url="true"
      show-date="true"
      @search-complete="onSearchComplete"
    />

    <!-- Chat Bubble Widget -->
    <chat-bubble-snippet
      :api-url="apiUrl"
      placeholder="Ask me anything..."
      @chat-message="onChatMessage"
    />

    <!-- Search Modal (Cmd/Ctrl+K) -->
    <search-modal-snippet
      :api-url="apiUrl"
      placeholder="Search documentation..."
      shortcut="k"
      show-url="true"
      show-date="true"
    />

    <!-- Full Page Chat -->
    <chat-page-snippet
      :api-url="apiUrl"
      class="chat-container"
    />
  </div>
</template>

<style>
/* Customize with CSS Variables */
search-bar-snippet,
chat-bubble-snippet {
  --search-snippet-primary-color: #F6821F;
  --search-snippet-border-radius: 12px;
}

.chat-container {
  height: 500px;
}
</style>

<!-- vite.config.ts - Configure Vue to recognize custom elements -->
<!--
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.includes('-snippet')
        }
      }
    })
  ]
});
-->

Why AI Search?

Everything you need to add intelligent search to your applications.

Deploy in minutes

Production-ready components out of the box. Just import and use.

Always up-to-date

Continuously indexes your data so responses reflect the latest information.

Edge-based inference

Runs at the edge, closer to users for reduced latency.

Framework agnostic

Works with React, Vue, Angular, or vanilla JavaScript.

Zero dependencies

Self-contained Web Components with everything bundled.

Fully customizable

50+ CSS variables for complete theme control.

Component API Reference

HTML attributes (props) and JavaScript methods available for each component.

Common Props (All Components)

AttributeTypeDefaultDescription
api-urlstringRequiredAI Search API endpoint URL
placeholderstring"Search..." / "Type a message..."Input placeholder text
theme"light" | "dark" | "auto""auto"Color scheme (auto follows system preference)
hide-brandingbooleanfalseHide "Powered by Cloudflare" branding

<search-modal-snippet> Props

AttributeTypeDefaultDescription
max-resultsnumber10Maximum number of search results to display
debounce-msnumber300Input debounce delay in milliseconds
show-urlbooleanfalseShow URL in search results
show-datebooleanfalseShow result dates when a timestamp is available
hide-thumbnailsbooleanfalseHide result thumbnails/images
request-optionsJSON string-Extra search request configuration with headers, query params, and body fields
shortcutstring"k"Keyboard shortcut key (used with Cmd/Ctrl)
use-meta-key"true" | "false""true"Use Cmd/Ctrl modifier for keyboard shortcut
see-morestring-URL template for "See more" link. The search query is appended URL-encoded (e.g. "https://example.com/search?q=")
Methods
MethodParametersReturnsDescription
open()-voidOpen the search modal
close()-voidClose the search modal
toggle()-voidToggle the modal open/closed
search(query)query: stringPromise<void>Open modal and perform search
getResults()-SearchResult[]Get current search results
isModalOpen()-booleanCheck if modal is currently open

<chat-bubble-snippet> Props

Uses common props only (api-url, placeholder, theme, hide-branding).

Methods
MethodParametersReturnsDescription
clearChat()-voidClear all chat messages
sendMessage(content)content: stringPromise<void>Programmatically send a message
getMessages()-Message[]Get all chat messages

<chat-page-snippet> Props

Uses common props only (api-url, placeholder, theme, hide-branding). Includes session history with localStorage persistence.

Methods
MethodParametersReturnsDescription
clearChat()-voidClear current chat session
sendMessage(content)content: stringPromise<void>Programmatically send a message
getMessages()-Message[]Get messages from current session
getSessions()-ChatSession[]Get all chat sessions
getCurrentSession()-ChatSession | nullGet the current active session

Search Request Options

Use the `request-options` attribute on search components or the `request` option on `AISearchClient.search()` and `searchStream()` to enrich search requests.

KeyTypeDescription
headersRecord<string, string>Extra headers to send with search requests
queryParamsRecord<string, string | number | boolean>Extra query params appended to the request URL
bodyRecord<string, unknown>Extra JSON fields merged into the request body
Notes
BehaviorDetails
Conflict resolutionCore request fields still win over conflicts: `messages`, `stream`, `max_results`, and the default search `ai_search_options.retrieval.metadata_only` value.

AISearchClient

Methods
MethodParametersReturnsDescription
search(query, options?)query: string, options?: { maxResults?, signal?, request? }Promise<SearchResult[]>Perform a search request with optional request enrichment
searchStream(query, options?)query: string, options?: { maxResults?, signal?, request? }AsyncGenerator<SearchResult | SearchError>Perform a streaming search request with optional request enrichment
chat(query, options?)query: string, options?: { signal? }AsyncGenerator<ChatTypes>Perform a chat completion request

Custom Events

EventComponentsDetailDescription
readyAllundefinedFired when component is initialized
opensearch-modalundefinedFired when modal opens
closesearch-modalundefinedFired when modal closes
result-selectsearch-modal{ result, index }Fired when a search result is selected

CSS Variables Reference

Customize every aspect of the components using CSS custom properties. All variables use the --search-snippet- prefix.

Colors

VariableDefaultDescription
--search-snippet-primary-color#2563ebPrimary brand color
--search-snippet-primary-hover#0f51dfPrimary hover state
--search-snippet-background#ffffffMain background color
--search-snippet-surface#f8f9faSurface/card background
--search-snippet-text-color#212529Primary text color
--search-snippet-text-secondary#6c757dSecondary/muted text
--search-snippet-text-description#495057Search result description text (higher contrast)
--search-snippet-border-color#dee2e6Border color
--search-snippet-hover-background#f1f3f5Hover state background
--search-snippet-focus-ring#0066cc40Focus ring color (with opacity)

State Colors

VariableDefaultDescription
--search-snippet-error-color#dc3545Error text color
--search-snippet-error-background#f8d7daError background color
--search-snippet-success-color#28a745Success text color
--search-snippet-success-background#d4eddaSuccess background color
--search-snippet-warning-color#ffc107Warning text color
--search-snippet-warning-background#fff3cdWarning background color

Message Colors (Chat)

VariableDefaultDescription
--search-snippet-user-message-bg#0066ccUser message bubble background
--search-snippet-user-message-text#ffffffUser message text color
--search-snippet-assistant-message-bg#f1f3f5Assistant message bubble background
--search-snippet-assistant-message-text#212529Assistant message text color
--search-snippet-system-message-bg#fff3cdSystem message background
--search-snippet-system-message-text#856404System message text color

Typography

VariableDefaultDescription
--search-snippet-font-family-apple-system, BlinkMacSystemFont, ...Primary font family stack
--search-snippet-font-family-mono'SFMono-Regular', Consolas, ...Monospace font family stack
--search-snippet-font-size-base14pxBase font size
--search-snippet-font-size-sm12pxSmall font size
--search-snippet-font-size-lg16pxLarge font size
--search-snippet-font-size-xl18pxExtra large font size
--search-snippet-line-height1.5Line height
--search-snippet-font-weight-normal400Normal font weight
--search-snippet-font-weight-medium500Medium font weight
--search-snippet-font-weight-bold600Bold font weight

Spacing

VariableDefaultDescription
--search-snippet-spacing-xs4pxExtra small spacing
--search-snippet-spacing-sm8pxSmall spacing
--search-snippet-spacing-md12pxMedium spacing
--search-snippet-spacing-lg16pxLarge spacing
--search-snippet-spacing-xl24pxExtra large spacing
--search-snippet-spacing-xxl32pxDouble extra large spacing

Sizing

VariableDefaultDescription
--search-snippet-width100%Component width
--search-snippet-max-width100%Maximum width
--search-snippet-min-width320pxMinimum width
--search-snippet-max-height600pxMaximum height (results area)
--search-snippet-input-height44pxInput field height
--search-snippet-button-height36pxButton height
--search-snippet-icon-size20pxIcon size

Border

VariableDefaultDescription
--search-snippet-border-width1pxBorder width
--search-snippet-border-radius18pxBorder radius

Shadows

VariableDefaultDescription
--search-snippet-shadow-sm0 1px 2px 0 rgba(0,0,0,0.05)Small shadow
--search-snippet-shadow0 2px 8px rgba(0,0,0,0.1)Default shadow
--search-snippet-shadow-md0 4px 12px rgba(0,0,0,0.15)Medium shadow
--search-snippet-shadow-lg0 8px 24px rgba(0,0,0,0.2)Large shadow
--search-snippet-shadow-innerinset 0 2px 4px 0 rgba(0,0,0,0.06)Inner shadow
--search-snippet-result-item-shadow0 1px 2px 0 rgba(0,0,0,0.05)Search result item hover shadow

Animation & Transitions

VariableDefaultDescription
--search-snippet-transition-fast150ms easeFast transition timing
--search-snippet-transition200ms easeDefault transition timing
--search-snippet-transition-slow300ms easeSlow transition timing
--search-snippet-animation-duration0.2sAnimation duration

Z-Index Layers

VariableDefaultDescription
--search-snippet-z-dropdown1000Dropdown z-index
--search-snippet-z-modal1050Modal z-index
--search-snippet-z-popover1060Popover z-index
--search-snippet-z-tooltip1070Tooltip z-index

Chat Bubble Specific

VariableDefaultDescription
--chat-bubble-button-size60pxBubble button size
--chat-bubble-button-radius50%Bubble button radius
--chat-bubble-button-bottom20pxButton bottom position
--chat-bubble-button-right20pxButton right position
--chat-bubble-positionfixedBubble position type
--chat-bubble-button-shadow0 8px 24px rgba(0,0,0,0.2)Button shadow
--chat-bubble-window-shadow0 8px 24px rgba(0,0,0,0.2)Chat window shadow
--chat-bubble-button-icon-size28pxButton icon size
--chat-bubble-button-icon-colorwhiteButton icon color
--chat-bubble-button-z-index9999Button z-index