ChatWidget UI surface

Every element the chat widget renders, with the classes a site can style, the states each can be in, and the tokens that change it. Styled by the widget's own stylesheet, so what is here is what ships.

These are static replicas. This page loads no widget JavaScript and calls no API: nothing here sends a message, opens a session or reaches a model. Use it to build and check a stylesheet. To see the widget behave, embed the loader on a page, or open the fixtures in fixtures/.

Class names are a public contract: renaming one ships as a new loader major version. The theming guide is docs/THEMING.md.

Launcher and live regions

Built in widget/loader.ts

Chat

The only element a visitor sees before opening the chat, and the only one the first script adds. It sits in a labelled region beside two screen-reader-only live regions that carry status (polite) and errors (assertive).

data-position is bottom-right or bottom-left. The root also carries hidden until the stylesheet has loaded, so no unstyled button flashes.

Classes
.bcw-root .bcw-region .bcw-launcher .bcw-sr-only
Attributes
data-position, data-busy, aria-expanded, aria-controls
Minimum target
44 by 44 pixels, the AAA size rather than the 24 pixel AA floor. A site that restyles the launcher keeps it.
  • Idle: the label a site sets, or "Ask a question".
  • Busy (data-busy="true"): while the panel bundle loads. Dimmed, cursor progress.
  • Expanded (aria-expanded="true"): while the panel is open.

Panel, header and close

Built in widget/panel-dom.ts

The panel is a dialog by role but not a modal: no aria-modal and no focus trap. WCAG 2.2 names chat widgets and says trapping the tab ring is inequitable for keyboard users. Escape closes it and focus returns to the launcher.

The log scrolls, and the panel scrolls too rather than clipping, so a host page with an aggressive reset cannot cut the composer or the legal copy out of reach.

Classes
.bcw-panel .bcw-header .bcw-title .bcw-close .bcw-log
Attributes
data-state="open|closed", role="dialog", role="log"
Size
Width 380px and height 560px by default, both capped to the viewport on a phone.
  • Closed (data-state="closed"): display none. The element stays in the DOM.
  • Open (data-state="open"): a flex column, and on first open it rises 120ms unless the visitor asked for reduced motion.

Remember this chat

Built in widget/panel-dom.ts

A toggle button rather than a checkbox: it announces its own state, takes the 44 pixel target without fighting a host reset on input[type=checkbox], and cannot be styled away by one.

It sits under the composer, above the legal copy, with the other always-visible notice. Between the header and the log it took 97 pixels of a 562 pixel panel and left the transcript 241, which is too much room for a setting a visitor touches once.

Visibility is the hidden attribute, never a style property, because a strict style-src blocks inline styles.

Classes
.bcw-remember-row .bcw-remember .bcw-remember-notice
Attributes
aria-pressed, aria-describedby, hidden
Copy
The notice is editor-settable; the label is not.
  • Hidden: the row carries the hidden attribute until consent is known. This page shows it anyway.
  • Off (aria-pressed="false"): the transcript lives for the tab only.
  • On (aria-pressed="true"): kept on this device for 30 days, or 50 messages.

Messages

Built in widget/render.ts

Two roles, one class. The visitor's messages use the brand colour and the assistant's the muted surface, so a site theming the widget changes both with two tokens.

The text itself is a .bcw-text paragraph inside the message, and links found in an assistant's own words become .bcw-inline-link anchors. Links and cards are siblings of that paragraph.

Classes
.bcw-message .bcw-text .bcw-inline-link
Attributes
data-role="visitor|assistant", data-reason, tabindex="-1"
Text handling
Every string is set as text, never markup. Phone numbers and URLs become links afterwards.
  • Visitor (data-role="visitor"): brand surface, aligned to the end.
  • Assistant (data-role="assistant"): muted surface, and focusable so a new answer can take focus.
  • data-reason carries the turn reason, for a site that wants to style a fallback differently.

Built in widget/render.ts

Links appear under the answer they support, only on a content answer, and only for results the turn actually received. A URL that is not http or https is dropped rather than rendered.

Classes
.bcw-links .bcw-link-item .bcw-link
Attributes
target="_blank", rel="noopener noreferrer"
Source
Only pages this turn's own search returned, named by the model by index.
  • Absent when the turn cited nothing. The list is never empty.

Cards: row layout

Built in widget/render.ts

The whole card is one link, with nothing interactive inside it: a nested control would give a screen reader two stops for one destination and a thumb two ways to miss.

An unknown data-type still renders. Its chip is title-cased from the value, so a future kind reads as words rather than as a blank.

Classes
.bcw-cards .bcw-card .bcw-card-body .bcw-card-kind .bcw-card-name .bcw-card-meta .bcw-card-cta .bcw-card-arrow
Attributes
data-type, data-layout="row", data-field on each meta line
Count
At most two cards, always from this turn, in the order the model named.
  • Two cards, or one without a picture: rows.
  • data-type drives the accent stripe: event, ride, attraction, dining, offer, parking, and a fallback.
  • At most two meta lines, chosen by type: an event leads with when, a shop with where.

Cards: banner layout

Built in widget/render.ts

One card is a recommendation and the picture is most of what makes it one, so a single card with an image gets the banner. Two banners would push the answer they belong to off the top of a 560 pixel panel, so a list is always rows.

Classes
.bcw-card-image .bcw-card-summary, plus the row classes
Attributes
data-layout="banner" on the card, the image and the body
Image
alt="" on purpose: the name is beside it, so a storefront photo announced first is noise.
  • One card with a usable picture: banner.
  • The summary line appears on a banner only, clamped in CSS.
  • A picture that fails to load leaves the body intact.

Typing indicator

Built in widget/render.ts

Decoration, deliberately hidden from assistive technology: the polite live region already says that the answer is coming, and two announcements for one event is worse than none.

Classes
.bcw-status .bcw-typing .bcw-dot
Attributes
aria-hidden="true"
Motion
The dots pulse only when the visitor has not asked for reduced motion.
  • Present while a turn is in flight, and replaced by the error box or removed when it ends.

Error and retry

Built in widget/panel.ts

A real focusable button, outside every live region, so a visitor can retry with the keyboard and the message is announced once by the assertive region rather than twice.

The retry resends the last message. It appears in the status slot, which is cleared first, so an error and a typing indicator can never be on screen together.

budget_exhausted and spend_cap_reached show no retry: no message can succeed until the budget resets, so the box holds only the line of copy and the composer stays disabled until the page reloads.

Classes
.bcw-error .bcw-error-text .bcw-retry
Attributes
data-code
Vocabulary
Closed. An unrecognised code renders the generic line, never text that arrived over the network.
  • unavailable: The chat is unavailable right now. Please try again in a moment.
  • timeout: That took longer than expected. Please try again.
  • network: The connection dropped. Please check your connection and try again.
  • rate_limited: That was a lot of questions at once. Please wait a moment, then try again.
  • budget_exhausted: This chat has reached its limit for now. Please contact Guest Services.
  • spend_cap_reached: This chat has reached its limit for now. Please contact Guest Services.
  • unauthorized: This chat session ended. Please try again.
  • challenge_failed: The security check did not complete. Please try again.

Challenge slot

Built in widget/challenge.ts

The container sits above the composer so a challenge appears next to the thing it is gating. A site styling the panel should leave its width alone: Turnstile sizes its own frame.

Classes
.bcw-challenge
Contents
Cloudflare Turnstile, rendered by their script. Nothing of ours goes in it.
Height
Zero until a challenge is demanded, so the panel does not jump.
  • Invisible: the usual case. The challenge runs when a session is minted, not when the panel opens.
  • Visible: Cloudflare demanded interaction, and the widget shows it rather than failing silently.

Composer

Built in widget/panel-dom.ts

A textarea rather than an input, because questions wrap. The id and name are not decoration: without them Chrome reports the field as unlabelled for autofill.

No maxlength (WEM Inn QA E-03, 2026-11-16): it cut a long paste with no notice, so the end of the question was lost and the visitor never knew. The demo shows the counter in its over-limit state.

Classes
.bcw-composer .bcw-input .bcw-send .bcw-counter
Attributes
id="bcw-input", name="message", aria-label, aria-describedby="bcw-counter"
Keyboard
Enter sends, Shift and Enter makes a new line.
  • Idle: Send is enabled once there is text.
  • Sending: the input is disabled for the turn, so one question cannot be asked twice.
  • The field grows to two rows and then scrolls.
  • From 1,800 characters the counter shows the count. Over 2,000 it says by how much, in bold, and Send keeps the draft instead of sending it.

FAQ capture

Built in widget/panel-dom.ts

For testers on a development site: when an answer misses, they write the FAQ that should have answered it and the site publishes it. The demo shows the form in place of the panel it covers.

Classes
.bcw-faq-add .bcw-faq-overlay .bcw-faq-title .bcw-faq-intro .bcw-faq-form .bcw-faq-label .bcw-faq-field .bcw-faq-error .bcw-faq-check .bcw-faq-verbatim .bcw-faq-actions .bcw-faq-save .bcw-faq-cancel .bcw-faq-status
Shown when
The init call sets faqCapture: true, which a site does only while its Chat Settings allow it.
Keyboard
Tab cycles through the form, and Escape closes the form, not the chat. The rest of the panel is inert while the form is open, except the security check, which sits above the form when Cloudflare asks for a click.
  • Closed: an Add FAQ button under each answer that has a question directly before it.
  • Editing: the question is prefilled from the visitor, cut at a word to 150 characters. Each field is checked on blur and on Save.
  • Saving: the fields and Save are locked.
  • Saved: the fields stay locked and only Close is offered, so one FAQ is not saved twice.
  • Error: the site's reason, or a closed set of lines for a timeout, a dropped connection or capture turned off.

Built in widget/panel-dom.ts

The AI disclosure sits under the input and stays there, and the same sentence is the first message in the log, so it is read by a visitor who never scrolls.

Classes
.bcw-legal .bcw-legal-link
Attributes
target="_blank", rel="noopener noreferrer"
Copy
Editor-settable, with the text above as the default. The links appear only when a site sets them.
  • Always visible while the input is, never behind a disclosure.

Theming tokens

Set these on :root or on .bcw-root in the site's own stylesheet. Every one is a custom property with a default, so a site sets only what it wants to change. The full guide, including what a host page can break, is docs/THEMING.md.

The defaults are West Edmonton Mall's palette, read from that site's styles/variables.scss: black text, a black pill for the primary action, $offWhite behind an assistant's message, and $blue for links and focus rings. Every pair was measured for contrast rather than eyeballed, and the ratios are beside the tokens below. A second site sets its own and changes nothing else.

Colour

TokenDefaultUsed for
--bcw-surface#ffffffPanel and card backgrounds ($white)
--bcw-surface-muted#f2f2f2Header, assistant messages, the error box ($offWhite)
--bcw-text#000000Body text ($textColor)
--bcw-text-muted#353c40Legal copy, card detail lines ($nearBlack), 11.2:1
--bcw-brand#000000Launcher and Send, WEM's black pill call to action
--bcw-on-brand#ffffffText on those, 21:1
--bcw-accent#30709cFocus rings and links ($blue), 5.4:1
--bcw-border#c9c9c9Panel, card and header edges ($greyLight)
--bcw-field-border#8e8e8eThe message field's boundary ($grey), 3.3:1 for WCAG 1.4.11
--bcw-visitor-surfacevar(--bcw-brand)The visitor's own messages
--bcw-visitor-textvar(--bcw-on-brand)Text on those

Shape, type and layout

TokenDefaultUsed for
--bcw-radius20pxPanel, cards, the error box (WEM's .rounded-corners)
--bcw-launcher-radius999pxThe launcher alone
--bcw-shadow0 12px 32px rgba(0, 0, 0, 0.22)The panel
--bcw-launcher-shadow0 2px 10px rgba(0, 0, 0, 0.18)The launcher
--bcw-font-size16pxThe typeface is inherited from the host page, which on WEM is Inter
--bcw-font-size-small13pxLegal copy, card detail, the remember-me notice
--bcw-space12pxThe spacing unit
--bcw-offset20pxDistance from the viewport edge
--bcw-z-index999999Clears page furniture, loses to a site modal
--bcw-panel-width380px
--bcw-panel-height560px
--bcw-panel-offset84pxHow far the panel sits above the launcher