@xpert-ai/chatkit-ui
v0.25.0
Published
ChatKit UI.
Readme
ChatKit UI
This package contains the UI application rendered inside the ChatKit iframe, providing the chat experience and its in-iframe UI shell.
Role in the ChatKit project
- Hosts the web UI that runs inside the embedded ChatKit iframe.
- Implements the chat view, message rendering, and interactive widgets for end users.
- Serves as the iframe-facing surface that communicates with the host app via ChatKit APIs.
Header identity
The inline avatar, title, and status block is hidden by default. Enable it with:
const options = {
header: { identity: { enabled: true } },
};This applies to Assistant and group chats. New conversation and header actions
remain visible independently. The centered character uses the separate
header.character setting; when it is displayed, the inline identity stays
hidden to avoid a duplicate.
Composer while reading history
While the scroll-to-bottom action is visible, the composer fades into a single row and hides the project, file, and resource toolbar. Returning to the bottom restores the full composer. Drafts, multiline text, selections, and input focus are preserved; reduced-motion preferences disable the transition.
Assistant Workbench layout
The chat / Workbench split remembers its chat width, open state and maximized state on this device, scoped by API service, organization and Assistant. Switching conversations keeps the same layout; reopening an Assistant or reloading the frame restores it once compatible Workbench views are available. No server settings or conversation data are written for this preference.
Chat width is stored in CSS pixels and clamped to fit the current window. Temporary window constraints do not overwrite the preferred width. Narrow screens use a temporary drawer layout without changing the saved desktop layout. Corrupt or unavailable browser storage falls back to the default layout.
Browser regression tests
Run corepack pnpm --filter @xpert-ai/chatkit-ui exec playwright install chromium
once, then corepack pnpm --filter @xpert-ai/chatkit-ui test:browser from the
repository root. The command builds the Web Component and iframe application
before testing, so a clean checkout needs no pre-existing dist files. Tests
cover initialization on HTTP and HTTPS origins, plus hosted Workbench navigation
through the Web Component and sandboxed Remote View. No backend or credentials
are required, and Web Crypto is not mocked.
CI uses Ubuntu 26.04, Node.js 24 and the pinned Playwright version in this package.
When updating Playwright or the runner OS, verify that Playwright supports that OS
and rerun browser installation with --with-deps before the regression suite.
UUID generation supports HTTP through crypto.getRandomValues. HTTPS is still
recommended: other browser features, including the clipboard, can require a
secure context independently of UUID generation.
External pet assets (migration)
The UI npm package no longer includes dist/app/pets. Deployments that copied
that directory must provision the optional @xpert-ai/chatkit-assets package and
copy its pets directory to /pets, or host it on a CDN. dist/app, the JS/CSS
assets, and font handling are unchanged.
Set ChatKitPetOptions.assetsBaseUrl to a versioned URL or root-relative resource path.
Set it inside pet: { assetsBaseUrl: ... }. It is scoped per instance and applies to built-in settings choices, Assistant
appearance sprites, and host overlays. The default is /pets; custom sprite URLs
remain unchanged. The resource address is still available to Assistant appearance
sprites when pet.enabled is false. Saved built-in selections keep their IDs when the base changes.
See the offline resource package for deployment and
cache instructions. Local vite development serves that package at /pets
without copying images into the production build. vite preview needs separately
hosted assets, just like a production deployment.
