Customize the website widget

The widget is one script that defines a <uare-chat> HTML element. You can configure it two ways:

• On the script tag, with data- attributes. The script then adds a chat bubble to the page by itself:

  <script async src="https://app.uare.ai/embed/v1.js" data-handle="your-handle" data-position="bottom-left"></script>
  

• On a <uare-chat> element you place yourself, which is how you put the chat inside your layout. Load the script once per page:

  <script async src="https://app.uare.ai/embed/v1.js"></script>
  
  <uare-chat handle="your-handle" mode="inline" theme="light" style="height: 640px"></uare-chat>
  

Your website must be on your AI's list of allowed websites, either way. The AI's owner adds it, in their Settings on uare.ai: see Allow your website.

#Attributes

On the script tag, add data- to each name: data-accent-color="#7c3aed". You can change attributes on the element at any time and it updates.

#Colours and fonts

The widget lives in its own shadow DOM, so your site's CSS doesn't leak into it. To restyle it, set these CSS variables on uare-chat:

uare-chat {
  --uare-accent: #7c3aed;     /* bubble (when your AI has no avatar), send button, visitor messages */
  --uare-accent-fg: #ffffff;  /* text on the accent */
  --uare-font: "Inter", system-ui, sans-serif;  /* defaults to your page's font */
  --uare-radius: 20px;        /* corners of the chat panel */
  --uare-bg: #ffffff;         /* panel background */
  --uare-fg: #18181b;         /* text */
  --uare-surface: #f4f4f5;    /* your AI's messages */
  --uare-muted: #6b6b72;      /* secondary text */
  --uare-border: #e4e4e7;     /* lines and outlines */
}

Variables you set apply in both light and dark mode. Leave one unset to keep the widget's default for the visitor's theme.

#JavaScript

Methods on the element:

open is also a property that takes a boolean, the way frameworks such as React 19 set it: chat.open = true opens the bubble and adds the open attribute, chat.open = false closes it and removes the attribute. Reading chat.open still gives the method.

When send() doesn't send, or the reply fails, its promise rejects with an Error whose code says why:

If the visitor stops the reply, or reset() starts a new conversation while it's streaming, the promise resolves.

Events, which bubble up to document. Each one's detail is described here:

For example, open the chat from your own button and send a first question. This works with the one-line snippet, which adds <uare-chat> to the page only once its script has loaded, and with an element you place yourself:

<button id="ask">Ask about pricing</button>

<script>
  document.getElementById("ask").addEventListener("click", () => {
    // Look the element up when it's needed: with the one-line snippet,
    // it isn't on the page yet while this script runs.
    const chat = document.querySelector("uare-chat");
    chat?.send("How does your pricing work?").catch((error) => {
      console.warn(`Not sent (${error.code}): ${error.message}`);
    });
  });

  // The widget's events bubble up to document, so listen there.
  document.addEventListener("uare:message", (event) => {
    console.log(event.detail.role, event.detail.text);
  });
</script>

send() opens the bubble if it's closed. Call it after uare:ready: before your AI has loaded, it rejects with not_ready and sends nothing.

#React and Next.js

React 19 renders custom elements directly. Load the script once with next/script, then use the element like any other:

"use client";

import Script from "next/script";
import { useEffect, useRef } from "react";

export function AiChat() {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    const chat = ref.current;
    if (!chat) return;
    const onMessage = (event: Event) => {
      const { role, text } = (event as CustomEvent<{ role: string; text: string }>).detail;
      console.log(role, text);
    };
    chat.addEventListener("uare:message", onMessage);
    return () => chat.removeEventListener("uare:message", onMessage);
  }, []);

  return (
    <>
      <Script src="https://app.uare.ai/embed/v1.js" strategy="afterInteractive" />
      <uare-chat ref={ref} handle="your-handle" mode="inline" style={{ height: 640 }} />
    </>
  );
}

In JSX, open is a boolean: React 19 sets it on the element as a property, which opens or closes the bubble. For the methods, type your ref as useRef<UareChatElement>(null).

For a chat you design yourself, use the public API with the AI SDK instead.

#Embed with an iframe

Some site builders and platforms only accept an iframe. uare.ai's own pages refuse to be framed by your site, so host a small chat page on a website you allowed, and frame that page wherever you need the chat:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      html, body { height: 100%; margin: 0; font-family: system-ui, sans-serif; }
      uare-chat { display: block; height: 100%; }
    </style>
  </head>
  <body>
    <script async src="https://app.uare.ai/embed/v1.js"></script>
    <uare-chat handle="your-handle" mode="inline"></uare-chat>
  </body>
</html>

The widget uses the page's font, so give chat.html the font you want. The website that has to be on your list is the one serving chat.html. The page holding the iframe can be on any site, because the chat talks to uare.ai from inside the frame. Browsers keep an iframe's storage separate for each website that frames it, so the conversation follows visitors from page to page on one website, and another website framing the same chat.html starts a conversation of its own.

#Content Security Policy

If your site sends a Content-Security-Policy header, allow uare.ai to serve the script and answer the chat:

Content-Security-Policy: script-src 'self' https://app.uare.ai; connect-src 'self' https://app.uare.ai; img-src 'self' https:

img-src needs to cover your AI's avatar. https: allows it wherever it's hosted. The widget's styles need nothing: they're applied from the script, so style-src doesn't have to allow inline styles.

#Privacy

• The widget sends no cookies and sets none. The conversation lives in your site's localStorage, under keys starting with uare-chat:, and leaves when visitors start a new chat or it expires.
• Messages go to uare.ai and your AI answers them in public mode, as on your public profile. uare.ai sees the visitor's IP address, which it uses for rate limits and visitor counts.
• Mention uare.ai in your privacy policy as a service that processes the chat messages visitors send.

#Versions

/embed/v1.js stays compatible: updates add features without breaking the attributes, methods and events above. A breaking change would ship as /embed/v2.js.