Widget theming

With no options the widget is a monochrome chat window with Yada’s face in the header. Her face changes with the run. Everything here is opt-in, and nothing depends on the widget’s internal HTML.

A renamed, restyled example

The same element, turned into another product’s assistant. The full source is in examples/browser/moss.ts.

widget.configure({
  client,
  conversationId,
  profileId: "garden",
  name: "Moss",
  subtitle: "Your garden helper",
  fill: true,
  colorScheme: "auto",
  suggestions: ["What can I plant now?", "Book a soil test"],
  labels: { approve: "Yes, book it", decline: "Not now" },
  formatApprovalPreview: (preview) =>
    preview.replace(/^(\w+):/gm, (_, field: string) => `${friendly(field)}:`),
  renderActivity: ({ tool, phase }) =>
    phase === "started" ? `Checking ${tool}…` : null,
  styles: `
    :host {
      --yada-accent: #3a5a1c;
      --yada-button-color: #fffdf5;
      --yada-background: #fffdf5;
      --yada-log-background: #f1efdf;
      --yada-bubble-background: #fffdf5;
      --yada-color: #27331a;
      --yada-title-font: 600 19px/1.2 Georgia, serif;
      --yada-title-size: 19px;
      --yada-face-background: #3a5a1c;
      --yada-face-color: #f5e9b8;
      --yada-face-dot: #f5e9b8;
    }
  `,
});

Options can also come from outside the shadow root:

yada-chat::part(header) {
  background: #ecfccb;
}
yada-chat::part(send) {
  border-radius: 50%;
}
yada-chat[data-state="awaiting-approval"]::part(composer) {
  opacity: 0.6;
}

Options

All are optional and passed to configure, next to client, conversationId and profileId.

Naming

{name} in any label is replaced with the name, which defaults to Yada. Setting a name also switches these default labels to use it:

An explicit label always wins.

Parts

Part names are public API under semver: removing or renaming one is a breaking change. widgetParts exports the list. Style them with yada-chat::part(name).

Inside your own component

If yada-chat sits in another component’s shadow root, forward its parts with exportparts:

import { widgetExportParts } from "@edgaralochi/yada/widget";
chat.setAttribute("exportparts", widgetExportParts);

Then my-shell::part(send) reaches the button.

State

The host carries its state, so CSS can respond to it:

The default face reads data-mood. To use your own faces, slot an image and swap it from this attribute, or set avatar to keep one picture.

CSS variables

Set them on the element or in styles. Dark mode changes the defaults of the colors, and a value you set wins in both modes.

Colors

When you set --yada-accent, set --yada-button-color too. Dark mode’s default button text is dark, to sit on its light accent.

Radius

Spacing and size

Fonts, shadows and opacity

cssVariables exports the list. If you change colors, check their contrast yourself.

Layout

<div style="height: 100vh"><yada-chat fill></yada-chat></div>

With fill the host is height: 100%, the log takes the remaining space and scrolls, and the composer stays in view. A long approval card is capped at half the height and scrolls. Giving the host any height of your own has the same effect. Without either, the log keeps its --yada-log-height.

Slots

<yada-chat>
  <img slot="avatar" src="/moss.png" alt="" />
  <small slot="footer">Moss can make mistakes. Check important details.</small>
</yada-chat>

Slotted content is yours: it lives in your document and takes your styles.

Render hooks

Hooks return DOM nodes or a string, and a string is always shown as text. Returning null or undefined keeps the default. If a hook throws, the widget uses the default and emits yada-error with kind: "render", so a bad hook can’t break a run or blank an approval.

renderMessage: ({ role, text, streaming }, { markdown }) => {
  const box = document.createElement("div");
  box.className = streaming ? "live" : "done";
  box.append(role === "assistant" ? markdown(text) : text);
  return box;
};

helpers.markdown(text) is the widget’s own safe renderer and helpers.text(text) makes a text node.

Model output is untrusted. Build nodes with textContent, append or helpers.markdown. Never pass it to innerHTML: the browser can run an injected onerror while parsing, before the widget sees the node. As a second layer, everything a hook returns is cleaned before it is added. Scripts, frames, embeds, style and template elements, on* attributes and srcdoc are removed, as are URLs that aren’t http, https, mailto, tel, blob or data:image. Listeners you add with addEventListener keep working. There is no way to turn this off.

The widget keeps each message’s role, its part and the hidden “You:” prefix for screen readers. Your node goes inside.

renderApproval gets approval (id, preview, status, expiresAt, remember) and actions:

renderApproval: (approval, actions) => {
  const yes = document.createElement("button");
  yes.textContent = "Book it";
  yes.disabled = actions.disabled;
  yes.addEventListener("click", () => {
    actions.approve({ remember: false });
  });
  const no = document.createElement("button");
  no.textContent = "Not now";
  no.disabled = actions.disabled;
  no.addEventListener("click", actions.decline);
  const box = document.createElement("div");
  box.append(approval.preview, yes, no);
  return box;
};

The card keeps its group role and name. Focus moves to its first focusable element, or to the card if there is none. actions.approve and actions.decline do nothing once a decision can no longer be made. Show users what will really happen: the widget can’t check that your text matches the action.

renderActivity gets { tool, phase: "started" | "finished", failed }. Its output clears when text arrives or the run moves on.

Events

All bubble and cross the shadow boundary. WidgetEventMap has their types.

kind is run, connection, load, cancel, decision, steer or render. A resumed run that no longer exists is not an error and emits nothing.

Accessibility

These hold in every mode, including unstyled:

• The log, status line, alert, group and field keep their roles and names.
• Hidden text stays available to assistive technology: the composer label, “You:” and the status line. An icon-only send button keeps its name, and a hidden header leaves its title on the root.
• Focus moves to an approval when it appears, and back to the composer when a run ends.
• The typing animation stops under prefers-reduced-motion.

If you hide text with your own CSS, hide it visually, not with display: none, or give the control an accessible name through labels.

Content Security Policy

styles strings use constructed stylesheets, like the defaults, so a style-src without 'unsafe-inline' allows them. Avatar images need img-src.