import { Meta } from '@storybook/addon-docs/blocks';
# HTML
The kit ships as standard **custom elements** (`kc-*` tags) — no framework required. Import the
bundle once as a side-effect and every element is registered globally, ready to drop into any HTML
page or templating system.
There are **two ways to build with the kit**, and you can mix them:
1. **``** — the batteries-included shell: a whole chat experience in one tag. Fastest start.
2. **Compose the individual elements** (``, ``, ``, …)
into your own layout when you want full control.
Both are shown below.
## Install & setup
```bash
npm i @kitn.ai/chat
```
Register the custom elements once (a side-effect import), then use the tags anywhere in your HTML:
```js
// Once, near your app entry — registers all elements globally.
import '@kitn.ai/chat/elements';
```
- No CSS to import: each element is styled inside its own Shadow DOM. Only pull in
`@kitn.ai/chat/theme.css` if you want to override design tokens (see **Theming**).
### No-build / CDN option
No bundler? Load the module directly from a CDN and you're done:
```html
```
Every `` element is then available as a global custom element — no install, no build step.
## Quick start — the all-in-one shell
`` is **transport-agnostic**: give it a `messages` array, handle the `submit` event, and
stream your model's reply back into the property. You own the request; the element owns the UI.
```html
```
> **Reactivity:** always assign a **new array** (and a new object for any message you change).
> Mutating an existing object in place will not trigger a re-render.
## Go further — compose the pieces
`` is one option, not the only one. Every element can be placed independently, so you can
assemble your own layout. Here's a multi-conversation shell — a `` sidebar next
to the `` thread:
```html
```
### Make the panels resizable
Want a draggable divider between the sidebar and the thread? Wrap the panels in ``
with one `` each — the handles are inserted for you (up to 3 panels). Each item
takes a `size` (px or `%`) plus optional `min`/`max`; listen for `change` (`detail.sizes`) to
persist the layout.
```html
```
You can also drop **standalone display elements** anywhere in your own page — ``,
``, `` — to render rich AI content without adopting the whole chat.
Each element fills its container and is controlled via properties and events.
> **See it all assembled:** **[Examples → Full Chat App](?path=/story/examples-full-chat-app--default)**
> wires a sidebar, threaded markdown, a model switcher, a context meter, and a rich prompt input
> into one screen — a working reference to crib from.
> **Find every element:** browse the **Components** section in the sidebar. Each element's **API**
> tab lists its props, events, and copy-paste usage for HTML (and every other framework).
## Props & events
The rule for all elements: **rich data goes in as JS properties, interactions come out as events.**
```js
// ✅ Arrays and objects — always set as a JS property
el.messages = [{ id: '1', role: 'assistant', content: 'Hi' }];
el.conversations = myConversations;
// ✅ Events — addEventListener on the element (CustomEvents, they don't bubble)
el.addEventListener('kc-submit', (e) => console.log(e.detail.value));
el.addEventListener('kc-conversation-select', (e) => console.log(e.detail.id));
```
**Scalar attributes** (strings, booleans, numbers) can go directly in HTML markup:
```html
```
Key events by element:
| Element | Event | `detail` |
|---|---|---|
| `kc-chat` | `submit` | `{ value: string }` |
| `kc-conversations` | `conversationselect` | `{ id: string }` |
| `kc-conversations` | `newchat` | — |
| `kc-conversations` | `togglesidebar` | — |
| `kc-resizable` | `change` | `{ sizes: string[] }` |