Getting Started with SiteSage Search

The sitesage-search module is a lightweight Web Component that provides a ready-to-use search interface for your application. It supports localization, SPA routing, and custom styling.

Note: If you are looking for the SiteSage Chat, please refer to the Chat documentation.

Quick Start

To add the SiteSage Search to your site, follow the steps in the Getting Started guide.

2. Add the Component

Place the <sitesage-search> tag in your HTML body. You will need your client_id, app_url, and backend_url from your SiteSage Admin.

<sitesage-search
    client_id="YOUR_CLIENT_ID"
    app_url="YOUR_APP_URL"
    backend_url="YOUR_BACKEND_URL"
/>

3. Open the Search Window

The search window is hidden by default and must be opened by calling the show method. This is left up to the developer to decide how to trigger the opening of the window.

The window opens in a modal overlay and will be automatically closed on a light dismissal action (clicking outside the window or pressing the escape key for desktop browsers).

Configuration Properties

The component accepts the following attributes in addition to the general configuration properties:

Attribute	Type	Description
`show`	function	Opens the search window.
`hide`	function	Closes the search window.
`options`	object	The search window options (see below).
`size`	object	The height and width of the search window (see below).

Search Window Options

The following is a list of options that can be set on the options property:

Property	Type	Description
`suggestions`	{title: string, question: string}[]	Array of suggested quick search questions.
`info`	string	Additional information to display in the search window.
`placeholder`	string	Placeholder text for the search input.

OBS: Please note that the info and placeholder properties handles localization by default. If you are overriding the values you must handle localization yourself.

Tip: You can override info and placeholder with empty strings to hide the respective elements.

Search Window Size

The following is a list of options that can be set on the size property:

Property	Type	Description
`height`	string	The height of the search window, e.g. “700px”,
`width`	string	The width of the search window, e.g. “350px”,

Features & Customization

Take a look at the Configuration Properties reference page for a full list of available configuration properties.

Custom Styling

You can customize the search window and widget by adding CSS properties to the sitesage-search element.

sitesage-search {
    --ss-chat-bg-border-radius: 7px;
}

For a full list of CSS variables, refer to the CSS Variables reference page.

Events

The component emits events that you can listen to for custom logic (like analytics tracking or UI changes).

Refer to the Emitted Events reference page for a full list of available events.

Please refer to the widget documentation for more information on how to override the default proxy handler. Overriding the proxy handler allows you to send admin-level requests to the AI.

For a full list of events, refer to the Emitted Events reference page.

Example: Minimal Implementation

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Minimal Implementation Example</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@sitesage/webcomponents@{latest_version}/dist/webcomponents.iife.js"></script>
</head>
<body>
    <button onclick="open_sitesage()" title="Search with AI">
        <svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000000"><path d="M784-120 532-372q-30 24-69 38t-83 14q-109 0-184.5-75.5T120-580q0-109 75.5-184.5T380-840q109 0 184.5 75.5T640-580q0 44-14 83t-38 69l252 252-56 56ZM380-400q75 0 127.5-52.5T560-580q0-75-52.5-127.5T380-760q-75 0-127.5 52.5T200-580q0 75 52.5 127.5T380-400Z"/></svg>
    </button>

    <sitesage-search
        disable_navigation
        client_id="ss-pub-guest"
        app_url="<your app url>"
        backend_url="<your backend url>"
    />
</body>
</html>

<script>
function open_sitesage() {
    const search = document.querySelector("sitesage-search");
    search.show();
}
</script>

<style>
    sitesage-search {
        /* Customize the search window with css variables here... */
    }
</style>

Example: Using a drop-in script

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Minimal Drop-in Example</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@sitesage/webcomponents@{latest_version}/dist/webcomponents.iife.js"></script>
    <script>
        window.addEventListener("DOMContentLoaded", () => {
            const search = window.SiteSage.search({
                client_id: "<your-client-id>",
                app_url: "<your-app-url>",
                backend_url: "<your-backend-url>",
                disable_navigation: true,
                options: {
                    suggestions: [
                        {title: "🗺️ Hello World", question: "What is the meaning of life?"},
                    ],
                },
                style: {
                    "--ss-chat-avatar": "url(https://placehold.co/128x128)",
                }
            });
        });
        function open_sitesage() {
            const search = document.querySelector("sitesage-search");
            search.show();
        }
    </script>
</head>
<body>
    <button onclick="open_sitesage()" title="Search with AI">
        <svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000000"><path d="M784-120 532-372q-30 24-69 38t-83 14q-109 0-184.5-75.5T120-580q0-109 75.5-184.5T380-840q109 0 184.5 75.5T640-580q0 44-14 83t-38 69l252 252-56 56ZM380-400q75 0 127.5-52.5T560-580q0-75-52.5-127.5T380-760q-75 0-127.5 52.5T200-580q0 75 52.5 127.5T380-400Z"/></svg>
    </button>
</body>
</html>