cloudflare/ai-search-snippet

cloudflare/ai-search-snippet

Description: AI Search embeddable snippet for Cloudflare AI Search

Language: TypeScript

License: MIT

Stars: 11

Forks: 9

Open issues: 8

Created: 2025-12-16T08:16:47Z

Pushed: 2026-06-09T00:29:15Z

Default branch: main

Fork: no

Archived: no

README:

🔍 Search Snippet Library

A production-ready, self-contained TypeScript Web Component library providing both search and chat interfaces with streaming support. Zero dependencies, fully customizable, and framework-agnostic.

✨ Features

• 🎨 Fully Customizable - 20+ CSS variables for complete theme control
• ⚡ Zero Dependencies - Self-contained with everything bundled
• 📱 Responsive Design - Works seamlessly on all devices
• 🎭 Framework Agnostic - Native Web Components work everywhere
• ♿ Accessible - WCAG 2.1 AA compliant with ARIA support
• 🚀 Streaming Support - Real-time streaming responses with low latency
• 🌓 Dark Mode - Automatic theme switching based on system preferences
• 📦 Tiny Bundle - Optimized for minimal size ( Note: This library requires an active AI Search endpoint in your Cloudflare Dashboard. Make sure to enable and configure your AI Search service before using these components.

Installation

npm install @cloudflare/ai-search-snippet
# or
yarn add @cloudflare/ai-search-snippet

Basic Usage

> Note: Replace `` with your Cloudflare AI Search endpoint hash (you can find it in the Cloudflare Dashboard).

/search.ai.cloudflare.com/search-snippet.es.js"
>


/search.ai.cloudflare.com/"
placeholder="Search..."
max-results="50"
max-render-results="10"
show-url="true"
show-date="true"
>


/search.ai.cloudflare.com/"
placeholder="Search documentation..."
max-results="50"
max-render-results="10"
show-url="true"
show-date="true"
>


/search.ai.cloudflare.com/"
placeholder="Type a message..."
>


/search.ai.cloudflare.com/"
placeholder="Type a message..."
>

📖 API Reference

Components

The library provides four Web Components:

| Component | Tag | Description | | -------------------- | ------------------------ | ------------------------------------- | | SearchBarSnippet | ` | Search input with results dropdown | | SearchModalSnippet | | Modal search with Cmd/Ctrl+K shortcut | | ChatBubbleSnippet | | Floating chat bubble overlay | | ChatPageSnippet | ` | Full-page chat with session history |

Common Attributes

These attributes are available on all components:

| Attribute | Type | Default | Description | | --------------- | ----------------------------- | ----------------------- | ------------------------------ | | api-url | string | http://localhost:3000 | API endpoint URL | | placeholder | string | Component-specific | Input placeholder text | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color scheme | | hide-branding | boolean | false | Hide the "Powered by" branding |

Search Components Attributes

Additional attributes for ` and `:

| Attribute | Type | Default | Description | | -------------------- | ------- | ------- | --------------------------------------------------------------------------------- | | max-results | number | 50 | Maximum number of results to request from the API | | max-render-results | number | 10 | Maximum number of results rendered in the UI (drives the "see more" affordance) | | debounce-ms | number | 300 | Input debounce delay in milliseconds | | show-url | boolean | false | Show URL in search results | | show-date | boolean | false | Show result dates when a timestamp is available | | request-options | JSON string | - | Extra headers, query params, and body fields for search requests |

Modal-Specific Attributes

Additional attributes for ``:

| Attribute | Type | Default | Description | | -------------- | ------- | ------- | ------------------------------------------ | | shortcut | string | 'k' | Keyboard shortcut key (with Cmd/Ctrl) | | use-meta-key | boolean | true | Use meta key (Cmd on Mac, Ctrl on Windows) |

Search Request Enrichment

Use request-options on ` and ` to enrich the request sent to the search endpoints.

The JSON object supports:

| Key | Type | Description | | --- | ---- | ----------- | | headers | Record | Extra headers to send with the search request | | queryParams | Record | Extra query params appended to the request URL | | body | Record | Extra JSON fields merged into the request body |

Core request fields still win over conflicts: messages, stream, max_num_results, and the default ai_search_options.retrieval.metadata_only search behavior.

Chat Query Rewrite

and automatically forward the full conversation history on every chat request. Starting from the **second** user message in a session, the client also enables AI Search's [query_rewrite`](https://developers.cloudflare.com/api/resources/ai_search/subresources/namespaces/methods/search/) option so the latest user message is rewritten into a self-contained retrieval query using the prior turns. The first message is sent as-is — there is no history to rewrite against yet.

Configure or disable rewriting via the chat-query-rewrite attribute (a JSON object) or the matching chatQueryRewrite JS property:

| Key | Type | Default | Description | | --------------- | ------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | true (on subsequent turns) | Set to false to skip rewriting on every turn. The first turn never rewrites regardless of this value. | | model | string | "@cf/meta/llama-3.3-70b-instruct-fp8-fast" | Model used by AI Search to rewrite the conversation into a search query. | | rewritePrompt | string | Built-in prompt | System prompt sent as rewrite_prompt. Defaults to a built-in instruction that resolves coreferences and emits a single standalone query. |

JavaScript API

Search Bar (``)

const searchBar = document.querySelector("search-bar-snippet");

// Perform a search programmatically
searchBar.search("query");

Search Modal (``)

const modal = document.querySelector("search-modal-snippet");

modal.open(); // Open the modal
modal.close(); // Close the modal
modal.toggle(); // Toggle open/closed
modal.search("query"); // Open and…