Loading the web components

There are three ways to get the kai-* web components onto a page. They render the same components — the difference is how their code reaches the browser. Most apps want the first one.

Quick comparison

Strategy	Import	Reach for it when
Register all	@kitn.ai/ui/web-components	The default. You use several web components, or you just want it to work. Works in SSR.
Per-web-component	@kitn.ai/ui/web-components/chat	You use only a couple of web components and your build tree-shakes.
Autoloader	<script> (CDN / static)	No build step and a handful of web components. Loads each on demand.

Register all is the easy default

import '@kitn.ai/ui/web-components' registers every web component in one import and works everywhere, including SSR. Reach for the other two only when you have a specific reason — a build that tree-shakes, or a no-build CDN page.

Register all (default)

import '@kitn.ai/ui/web-components';

One import, every kai-* web component registered. The simplest setup, and the SSR-safe entry point — the import is side-effect-only and doesn’t touch document until the browser runs it, so it won’t throw in a server render.

The same bundle works with no build at all — a single self-contained fetch from a CDN:

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kai.es.js';
</script>

Per-web-component imports

Import a web component by its file basename, and your bundler includes only that web component’s code:

import '@kitn.ai/ui/web-components/chat';
import '@kitn.ai/ui/web-components/code-block';

kai-chat is a complete chat — one import

That single import is everything a chat needs. <kai-chat> already bundles everything it renders — messages, markdown, code highlighting, reasoning, tool calls, attachments, the prompt input, model switcher, scroll button. You do not import those separately, and there is no internal sub-part to forget.

You only add another import for an additional standalone web component you place in your own markup — e.g. a <kai-artifact> beside the chat. That’s one import per web component you write into the HTML.

And it fails loud, not silent: if you place an element but forget its import, that element renders empty (un-upgraded) instead of breaking the rest of the page — and the kai MCP’s debug / component_reference tools name the exact import to add.

(Generative-UI cards — kai-confirm, kai-form, … — are also standalone web components, so add them only if your assistant renders card payloads.)

The import path is the web component’s filename in dist/web-components/ — usually the tag minus the kai- prefix. You only need a row below for a web component you place in your markup yourself; the message / markdown / reasoning / input parts of a chat are already inside kai-chat:

Element	Import
<kai-chat>	@kitn.ai/ui/web-components/chat
<kai-code-block>	@kitn.ai/ui/web-components/code-block
<kai-message>	@kitn.ai/ui/web-components/message
<kai-prompt-input>	@kitn.ai/ui/web-components/prompt-input
<kai-markdown>	@kitn.ai/ui/web-components/markdown
<kai-reasoning>	@kitn.ai/ui/web-components/reasoning
<kai-attachments>	@kitn.ai/ui/web-components/attachments
<kai-artifact>	@kitn.ai/ui/web-components/artifact

Client-only

Per-web-component imports are client-only. In SSR frameworks (Next.js, Nuxt, SvelteKit, etc.) wrap them in a client-side boundary — a 'use client' component in Next.js, an onMount in Svelte, or a <ClientOnly> wrapper in Nuxt.

Autoloader

The autoloader watches the DOM and registers each web component on demand — only the tags present on a given page are ever loaded.

That on-demand loading is paid in requests: each web component’s module and its dependencies arrive as separate fetches. On a page using a few web components — a <kai-markdown> here, a <kai-code-block> there — that’s the cheapest path by far.

A <kai-chat> page is close to its worst case: the chat transitively pulls most of the kit, so the autoloader downloads nearly the same bytes as the register-all bundle across many more requests. For a no-build chat page, load dist/kai.es.js instead — one fetch, everything registered.

It is a CDN / static-file tool: load it from a <script type="module"> tag. It is not importable through a bundler — Vite and webpack relocate it away from the web-component files and its on-demand imports 404. In a bundled app, use per-web-component imports instead.

<script type="module" src="https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/web-components/autoloader.js"></script>

Here it is running live. This iframe loads only the autoloader — watch the panel for the modules it fetches on demand, then add a web component and see it load on the fly:

On import it scans for undefined kai-* elements and starts a MutationObserver. Any kai-* element added to the DOM later — including ones injected by client-side routing — is registered the moment it appears.

<!-- Only kai-chat loads. The others register only if you add them. -->
<kai-chat style="display:block; height:100dvh;"></kai-chat>

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/web-components/autoloader.js';

  const chat = document.querySelector('kai-chat');
  chat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hello!' }] }];
  chat.addEventListener('kai-submit', (e) => console.log(e.detail.value));
</script>

CDN / static-file only — not for bundlers

The autoloader resolves web-component modules relative to its own URL and uses document + MutationObserver. Load it from a <script type="module"> on a CDN or static host. Do not import '@kitn.ai/ui/autoloader' in a bundled (Vite/webpack/Next) app or a server render — the bundler relocates it and the on-demand imports 404.

In a bundled app, use per-web-component imports or the register-all bundle.

Pin versions in production

An unversioned CDN URL tracks the latest release, which is risky on a pre-1.0 package. Pin an exact version: https://cdn.jsdelivr.net/npm/@kitn.ai/ui@0.37.0/dist/web-components/autoloader.js.

Pin a version at or above 0.25.0. Everything from 0.14.1 to 0.24.0 is covered by a critical security advisory and is deprecated on npm — and a CDN fetch, unlike npm install, prints no deprecation warning to tell you.

Code highlighting

Syntax highlighting (Shiki) loads on demand — per language, the first time a code block with that language renders, with no WebAssembly. If you never render a code block, it never loads. This holds for all three strategies above.

SSR notes

Strategy	SSR-safe?
@kitn.ai/ui/web-components	Yes — registration is gated on window; no document on import
Per-web-component (@kitn.ai/ui/web-components/chat)	No — throws window is not defined; use inside a client-only boundary
Autoloader	Imports without throwing, but never use it here — it must resolve relative to its own URL, so it is a CDN <script>, not a bundled import

For SSR meta-frameworks, see the meta-frameworks guide for framework-specific client boundary patterns.