@dotazse/chat-widget
v2.2.0
Published
Dotaz.se inline chat widget web component. Shadow-DOM-encapsulated, self-contained drop-in.
Maintainers
Readme
@dotazse/chat-widget
Inline chat widget web component for Dotaz.se. Shadow-DOM-encapsulated, self-contained — drop one <script> tag and place the element wherever you want the chat to render.
Unlike @dotazse/chat-popup (which anchors itself to the viewport corner), @dotazse/chat-widget renders inline at the position of the custom element.
- No external CSS to load (Tailwind is inlined into the shadow root).
- No font loading required.
- No CSS variables to configure (theme overrides are still supported via CSS custom properties on
:root— they inherit through the shadow boundary by design). - Hostile host-page CSS cannot leak in.
Integration via CDN (recommended)
<!doctype html>
<html>
<head>
<meta charset="UTF-8" />
<title>My site</title>
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@dotazse/chat-widget@2/widget.js"
></script>
</head>
<body>
<div style="max-width: 800px; margin: 10px auto;">
<dotazse-chat-widget baseurl="https://example.dotaz.se"></dotazse-chat-widget>
</div>
</body>
</html>Notes:
type="module"is required — the bundle is an ES module. Native module scripts are supported by every browser shipping since 2018 (Chrome 61+, Firefox 60+, Safari 11+, Edge 16+).- Module scripts are deferred by default — they don't block HTML parsing and
execute after the document is parsed. Custom-element upgrade handles the
case where
<dotazse-chat-widget>appears in the markup before the script defines it.
Attributes
All boolean attributes take the string values "true" / "false" (a bare attribute such as <… show-faq> counts as true). They are read once, when the element is created — changing them later has no effect.
| Attribute | Type | Default | Description |
| ---------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------- |
| baseurl | string | — | Backend gateway URL (e.g. https://example.dotaz.se). |
| show-citations | boolean | true | Render numbered citation badges in answers; clicking one opens the cited source in a dialog. |
| show-faq | boolean | true | Show the owner's FAQs (a numbered list; clicking one sends the question) while the conversation is empty. |
| show-step-duration | boolean | true | Show how long each chain-of-thought step took. |
| expandable-reasoning | boolean | false | Let the user expand the model's reasoning summary (English) inside the chain-of-thought rows. |
| show-rating | boolean | true | Offer thumbs up / thumbs down (with an optional comment) under finished answers. Copy is always on. |
The CPV integration uses <dotazse-chat-widget baseurl="https://cpv.dotaz.se" show-rating="false">.
Features
The conversation inside the widget is rendered by the shared @llm-assistant/ui-agent library, so the popup, the widget and the chat app behave the same:
- Chain-of-thought steps shown while the agent works, then the streamed markdown answer.
- Citations as numbered badges; clicking one opens the source in a dialog (
show-citations). - Action row under every finished answer: copy (markdown with
[n]citations and a "Zdroje" list) and thumbs up / down with an inline comment box (show-rating). Always visible on the latest answer and on touch devices, on hover/focus on older ones. Ratings are stored in the server session and stay highlighted after navigation. - New topic starts a clean conversation (server session included).
- Lazy connect: no connection or server session until the first question (or FAQ click); the question shows as "sending" meanwhile, and turns into an error with Retry / Dismiss if it is rejected.
- Restore after navigation: a live conversation comes back when the visitor opens another page of the same site (per-tab
sessionStorage). - Idle expiry: the server ends a conversation after a period of inactivity (
CHAT_SESSION_IDLE_MIN, default 30 min). The old messages stay readable (copy still works, rating is hidden) under a notice; the next question starts a new conversation. - Connection notices: a "reconnecting…" hint while a dropped connection is restored, and an error banner with Retry when the server refuses the connection or the configuration cannot be loaded.
- Texts, theme and dark mode come from the owner's settings (
layout.texts,theme,layout.useDark/layout.appDarkOverrides.widget) with Czech defaults.
Owner settings used by the widget
Texts come from the owner's layout.texts (non-empty values override the Czech defaults):
| Key | Where |
| ------------------- | ---------------------------------------------- |
| welcomeTitle | Heading of the empty state. |
| welcomeSubtitle | Description under the heading. |
| searchPlaceholder | Placeholder of the question input. |
| faqTitle | Heading above the FAQ list. |
| aiDisclaimer | AI-generated-content disclaimer at the bottom. |
The FAQs themselves are the owner's faqs (shown while the conversation is empty, show-faq). Other keys of layout.texts (botName, welcomeBubble, subtitle) are used by the popup/chat only.
Version pinning
The CDN URL accepts a semver range. Pick the strategy that matches your change-control posture.
The
/widget.jssuffix in the<script src>URL is required — it anchors the bundle's internal asset resolution. The version specifier itself (@2,@2.0.0, …) is what controls update behavior; the table below lists each option without the trailing/widget.jsfor clarity.
| URL | Behavior |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| @dotazse/chat-widget@2 (recommended) | Receives all non-breaking updates (2.x.y) automatically. A future v3 with breaking changes will not ship to you unless you bump the URL. |
| @dotazse/[email protected] | Pin an exact version. Use this if your environment requires change-control sign-off per update. |
| @dotazse/chat-widget (no version, resolves to @latest) | Always newest, including future breaking majors. Not recommended for production — a breaking release will deploy silently to all visitors. |
Alternative integrations
unpkg
<script
type="module"
src="https://unpkg.com/@dotazse/chat-widget@2/widget.js"
></script>Self-host the bundle
npm install @dotazse/chat-widget and serve widget.js (ES module) from your
own infrastructure, or import '@dotazse/chat-widget' from your own bundler
(Vite / webpack / Rollup) — sideEffects: true ensures the custom-element
registration is preserved through tree-shaking.
Themed deployments
The widget renders in a shadow root: the host page's CSS does not reach it, and the old v0.0.x variables
(--color-primary-600, --theme-rounded-base, ...) are not read. The look comes from the owner's theme
(colours as light / dark token sets, radius, fontBody, fontBrand for the question heading), set in the DB -
see db-inputs/cpv/01-theme.sql for a complete example. The host page only has to load the fonts the theme names.
A token the owner theme does not set can still be overridden on the element itself (not :root - the widget's
defaults on :host win over inherited values):
<style>
dotazse-chat-widget {
--primary: oklch(48.9% 0.121 252);
}
</style>