Chat Web Components

Classification: API reference with partial embedding examples. The HTML and JavaScript blocks assume a hosted child where the chat element shell is available, a valid session UUID or agent start token, and application-owned mount and teardown code.

The Wippy chat UI is available as composable custom elements in contexts where the Host injects the chat shell. A srcdoc iframe child can embed live chat by tag without Vue imports or registration. The elements use the same chat components and ChatTransport → SessionManager data layer as the host.

These are host-provided elements to consume. Unlike a Web Component that you build yourself, you do not author or register them. The srcdoc iframe injector makes them available by tag. The Web Fragment gateway in the pinned Framework release deliberately omits chat.js, so a Fragment page cannot assume these tags exist; use the host chat controls there instead (see How they load).

Use these when you want a chat surface inside your own page or panel. To open the host's own chat panel imperatively instead, use host.startChat(token) / host.openSession(sessionUUID) from @wippy-fe/proxy (see Proxy API).

The elements

Tag	Renders	Key attributes	Events
`<wippy-chat>`	Full chat — header + messages + input	`session-id`, `start-token`, `agent`, `show-selector`, `hide-header`	`session-started`, `error`
`<wippy-chat-messages>`	Message list only	`session-id`	—
`<wippy-chat-input>`	Composer only	`session-id`	—
`<wippy-session-selector>`	Session picker	`active-session-id`	`select`

Every element also accepts two per-instance theming attributes — custom-css and css-variables — covered in Theming.

How they load

The chat elements ship like <wippy-loading>: a small @wippy-fe/chat.js shell auto-registers all four tags. The srcdoc iframe injector includes it in the host scripts array alongside loading.js and proxy.js, so iframe-delivered pages do not install a package or call customElements.define().

The Framework's Web Fragment gateway injects loading.js and proxy-fragment.js, but not chat.js. Fragment-delivered pages should use host.startChat() or host.openSession() unless a later platform contract adds an explicit chat-shell opt-in. Direct web components mounted in the host document must likewise not assume that another child realm registered the tags.

The implementation dependencies are code-split into a separate chat-internals.[hash].js chunk and lazy-loaded on first mount. While the chunk downloads, the element shows a <wippy-loading> placeholder; if the load fails it shows <wippy-error>. Pages that never mount a chat tag do not load the internals.

`<wippy-chat>`

Reactive session control requires Web Host 1.0.51 or newer. The element shell is a Host-injected asset rather than a public @wippy-fe/chat package; older Host releases only support the initial mount reliably.

The full chat surface: header, scrollable message list, and composer.

Attribute	Type	Default	Description
`session-id`	string	—	Render this existing session (a session UUID).
`start-token`	string	—	Agent start token; starts a new session on mount when no `session-id` is set.
`agent`	string	—	Agent name (or title) to pre-select in the empty state, shown when no session is open.
`show-selector`	boolean	`false`	Render the built-in session selector in the header.
`hide-header`	boolean	`false`	Hide the agent/model header bar (for compact embeds).

Events (dispatched as CustomEvents on the element; read event.detail):

Event	`detail`	When
`session-started`	`{ sessionId: string }`	A session is started — from `start-token` on mount, or by user action.
`error`	`{ message: string }`	Session initialization fails (e.g. an invalid `start-token`).

<!-- Start a new session from an agent start token -->
<wippy-chat start-token="agent-start-token" agent="researcher"></wippy-chat>

<!-- Pin an existing session -->
<wippy-chat session-id="019eb2ae-1234-5678-abcd-ef1234567890"></wippy-chat>

<!-- Built-in selector, no header bar -->
<wippy-chat show-selector hide-header></wippy-chat>

document.querySelector('wippy-chat')
  .addEventListener('session-started', (e) => {
    console.log('session:', e.detail.sessionId)
  })

Reactive control without remounting

Keep one <wippy-chat> element mounted and update its attributes. A changed session-id opens that session in place. Setting session-id="" or removing a previously controlled attribute is an explicit New Chat transition: it clears both the pinned and shared active session. An element that never had a session-id remains selector-driven instead; absence on first mount is not a clear command.

When a start-token is present, clearing session-id starts from that token again. Changing the token also starts in place. The element consumes a token once per custom-element host, so reconnecting or moving the same element does not replay a live start. If a newer token, controlled session, manual selection, or disconnect supersedes an in-flight start, the stale result cannot replace the current session; any late-created session is closed.

const chat = document.querySelector('wippy-chat')

chat.setAttribute('session-id', existingSessionId)

// New Chat with an agent. No element replacement is required.
chat.setAttribute('start-token', agentStartToken)
chat.removeAttribute('session-id')

Managed-layout component resolvers update and remove props on the existing custom element. They remount only when tagName changes, preserving the chat input, scroll position, and element-owned lifecycle state across panel updates.

`<wippy-chat-messages>` and `<wippy-chat-input>`

The message list and the composer as separate elements, so you can lay them out yourself. Each takes a single session-id; with no explicit session-id they follow the shared active session set by a <wippy-session-selector>. Neither emits events.

<!-- Custom layout: messages above, composer below -->
<div style="display:flex; flex-direction:column; height:100%;">
  <wippy-chat-messages session-id="019eb2ae-…"></wippy-chat-messages>
  <wippy-chat-input    session-id="019eb2ae-…"></wippy-chat-input>
</div>

`<wippy-session-selector>`

A session picker. It drives the shared active session that other elements follow.

Attribute	Type	Default	Description
`active-session-id`	string	—	Highlight this session as active.

Event:

Event	`detail`	When
`select`	`{ sessionId: string }`	The user picks a session. The picked session becomes the shared active session.

<wippy-session-selector></wippy-session-selector>

document.querySelector('wippy-session-selector')
  .addEventListener('select', (e) => {
    console.log('picked:', e.detail.sessionId)
  })

Composition and shared session

Elements with no explicit session-id follow the <wippy-session-selector>'s pick via the manager's shared activeSessionId. So a selector plus a chat (or a selector plus a separate messages + input) on one page stay in sync — pick a session in the selector and the others update. Elements that do carry an explicit session-id (or start-token) are pinned and ignore the selector.

<!-- Selector + chat: the chat follows the picked session -->
<wippy-session-selector></wippy-session-selector>
<wippy-chat></wippy-chat>

<!-- Selector + split message list / composer, all following the selector -->
<wippy-session-selector></wippy-session-selector>
<wippy-chat-messages></wippy-chat-messages>
<wippy-chat-input></wippy-chat-input>

<!-- Pinned chat alongside a selector-driven one -->
<wippy-chat session-id="019eb2ae-…"></wippy-chat>  <!-- ignores the selector -->
<wippy-chat></wippy-chat>                            <!-- follows the selector -->

Theming

Each element renders in a shadow root, so host page styles do not leak in or out. Two mechanisms apply theme:

Inherited CSS variables. Theme custom properties (--p-primary-*, --p-text-color, …) inherit across the shadow boundary from the host theme, so the chat follows the active palette and dark/light mode. Selector-based styles (PrimeVue, markdown, Tailwind) are bundled into a chat-elements.css sheet and injected into the shadow root. PrimeVuePlugin redirects the default body/null Portal target to a pinned overlay layer inside the owning shadow root. Do not set appendTo: 'self' routinely: that is an explicit inline-placement opt-in and can clip inside scrolling Dialog or Drawer content. Toasts are delegated to the host's native toast over the proxy rather than rendered in-shadow.
Per-instance overrides. Every element accepts two attributes:

Attribute	Type	Effect
`custom-css`	string	Raw CSS appended last into the element's shadow root, so it wins by order.
`css-variables`	object (JSON)	Per-instance CSS variable overrides applied to `:host`. Keys may omit the leading `--`.

Treat both attributes as trusted application configuration. Do not copy untrusted user input into raw CSS or variable values; CSS can alter or obscure the embedded interface and can initiate external resource requests.

<wippy-chat
  session-id="019eb2ae-…"
  custom-css=".message-item { max-width: 80%; }"
></wippy-chat>

Omitting css-variables is the normal facade-respecting path. Per-instance color overrides are for deliberate embedding isolation, not routine restyling.

For the full theming model — semantic variables, dark/light flipping, and how the host injects shadow-DOM CSS — see Theming: Web Components.

Runtime wiring

Inside a srcdoc iframe child, the elements require no additional setup. Auth and config come from the injected proxy runtime; REST and WebSocket use the config's environment URLs. When a chat tag mounts, the already-registered shell loads the internals on demand and connects with the child's existing session. Web Fragment and direct-host contexts have the availability limits described in How they load.