inline-chat-kit
v0.63.2
Published
An inline AI chat experience for React. The input is the message: it morphs into the bubble, the answer streams beneath it, and the parts around it — tool calls, reasoning, questions, artifacts, dictation — come with it.
Maintainers
Readme
inline-chat-kit
An inline AI chat experience for React. The input is the message: when you send, the pill you typed into morphs into the bubble that holds your text, and the answer streams in below it. No separate composer, no jump cut.
Ships the surrounding pieces too — a turn row, a header for the conversation, hover actions on each bubble, copy and feedback under every answer, markdown answers you can draw on with a marker, syntax-highlighted code blocks, a scroll container that keeps up with an answer, and reply-in-thread popups.
New here? Getting started is one file, ten minutes, and a chat that runs with no backend. The rest of this page is the reference.
Where it is meant to run
Desktop and tablet. That is what this is designed for, tuned for, and what the checks measure.
It runs on a phone and does not break. The artifact pane becomes a bottom
sheet, so does a reply thread; every control is reachable by a thumb; nothing
zooms when a field takes focus; the type scale rises so reading text is 16px
and the icons rise with it. There are guards for each of those, in two engines,
at 390×844 — npm run zoom-check and npm run reach-check.
But it is not tuned for a phone, and the inline idea itself is weaker there. Worth saying plainly rather than leaving you to discover it.
The argument for an inline composer is that you see your question and its answer at once, because the thing you type into is the message. A phone gives you about half a screen once the keyboard is up — and the browser will not tell you how much. So the platform takes away the one thing the design exists for.
Four more that no amount of CSS reaches:
| | | | --- | --- | | the keyboard's height | the browser does not report it reliably; a native scroll view is simply told | | text selection | the system's own selection UI fights a marker drawn in prose — this kit ships a selection-mode toggle because of that | | scroll physics | rubber-banding and momentum belong to the browser, not to you | | haptics | no API at all on iOS Safari |
If you need a phone-first chat, treat this as a specification for one rather
than an implementation of one. The parts that would carry over are the ones
with no DOM in them — useChatTurns, turnParts, placePanel — and they are
plain TypeScript on purpose.
Desktop applications are a different story: an Electron or Tauri renderer is a browser, so this works there today with nothing changed.
Install
npm install inline-chat-kit motion lucide-reactreact, react-dom, motion and lucide-react are peer dependencies — the
kit uses whatever copy your app already has.
Use
import { useState } from "react";
import { ChatInput, type ChatInputState } from "inline-chat-kit";
import "inline-chat-kit/styles.css";
function Composer() {
const [value, setValue] = useState("");
const [state, setState] = useState<ChatInputState>("idle");
return (
<ChatInput
state={state}
value={value}
onChange={(v) => {
setValue(v);
setState(v ? "typing" : "idle");
}}
onSubmit={async (v) => {
setState("responding");
await send(v);
setState("resting");
}}
onStop={() => setState("resting")}
placeholder="Ask me anything…"
/>
);
}The stylesheet import is required — the components are CSS Modules and the bundled sheet carries every class they reference.
Wiring it to your model
ChatInput renders one turn. useChatTurns owns the conversation — the turn
list, the request in flight, and the reveal — and asks your app for the answers.
import { useChatTurns } from "inline-chat-kit";
const { turns, setDraft, submit, stop } = useChatTurns({
onSend: async function* (message, { signal }) {
const response = await fetch("/api/chat", {
method: "POST",
body: JSON.stringify({ message }),
signal,
});
for await (const chunk of response.body!.pipeThrough(new TextDecoderStream())) {
yield chunk;
}
},
});onSend may return a string, a promise of one, or an async iterable of deltas.
Return a string and the kit reveals it at a readable pace; return deltas and it
shows them as they land. signal aborts when the reader presses stop.
The kit never invents an answer. There is no canned fallback anywhere in the package — if your handler returns nothing, nothing is what appears.
Rendering the turns
{turns.map((turn, i) => {
const isActive = i === turns.length - 1 && (turn.state === "idle" || turn.state === "typing");
return (
<ChatTurnRow
key={turn.id}
turn={turn}
isActiveInput={isActive}
onDraft={setDraft}
onSubmit={submit}
onStop={stop}
onEdit={beginEdit}
onCancelEdit={cancelEdit}
/>
);
})}ChatTurnRow is already memoised, and that memo is load-bearing. The hook
leaves untouched turns referentially identical when it rewrites one of them,
but that only pays off if the rows act on it — otherwise every turn re-renders
on every frame of every answer, and the cost grows with the conversation.
Measured before the memo existed: streaming one answer produced 366 DOM
mutations inside an unrelated, already-finished turn. With it, zero.
Which is why the callbacks take the turn's id rather than being closed over per row. Pass the hook's own functions straight through — they are stable. An arrow created during render is not, and hands the memo a new prop every time.
renderPart is a callback like the others and follows the same rule: define
it outside the component, or wrap it in useCallback / useMemo. A renderer
written inline is a new function every render, which is a changed prop on every
row — so every finished answer re-renders on every frame of the one arriving,
exactly the cost the memo exists to remove. What a card needs to change (it was
applied, it was sent) belongs in the part's data, written back with
updatePart; then only the row that owns it re-renders.
If you write your own row instead, wrap it in React.memo and do the same.
The four states
ChatInput is fully controlled. You own state and drive the whole
choreography by moving between these values:
| state | What the input looks like |
| --- | --- |
| idle | Empty pill, placeholder showing |
| typing | Text in the pill, send glyph revealed |
| responding | Pill has become a glass bubble, glyph is a stop square |
| resting | Settled bubble, hover actions available |
API
<ChatInput>
| Prop | Type | Notes |
| --- | --- | --- |
| state | ChatInputState | Required. See table above |
| value | string | Required. Controlled value |
| onChange | (value: string) => void | Required |
| onSubmit | (value: string) => void | Required. Fires on Enter (Shift+Enter inserts a newline) |
| onStop | () => void | Stop button while responding |
| onAdd | () => void | The + button; opens the radial attachment fan |
| onCopy | (value: string) => void | Hover action on a resting bubble |
| onEdit | (value: string) => void | Hover action; put the turn back into typing |
| onCancelEdit | () => void | Paired with isEditing |
| isEditing | boolean | Shows save/cancel instead of send |
| placeholder | string | |
| animationConfig | InlineAnimConfig | Spring and stagger overrides — see below |
| style | React.CSSProperties | |
ref exposes focus(), setValue(v) and getValue() via ChatInputHandle.
<ChatTurnRow>
One turn: the question as a composer that has become a bubble, and the answer
beneath it. Not Message, because it is not one — the user half is a live
input that morphs into its own bubble rather than a record of what was typed.
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| turn | ChatTurn | | Required. Straight from useChatTurns |
| isActiveInput | boolean | false | This row owns the live composer |
| inputRef | Ref<ChatInputHandle> | null | For focus() |
| placeholder | string | | |
| animationConfig | InlineAnimConfig | | Passed to the input |
| entranceDelay | number | 0 | Stagger, in seconds |
| entrance | "rise" \| "fade" | "rise" | How the row arrives — a docked composer fades in place |
| answerAfterTravel | boolean | false | The answer waits until the sent question has landed — docked, set by ChatExperience |
| selectionMode | "marker" \| "precise" | "marker" | Passed to the highlighter |
| questionAlign | "end" \| "stretch" | "end" | Where the composer sits — see below |
| onDraft | (id, value) => void | | |
| onSubmit | (id, value) => void | | |
| onStop | () => void | | |
| busy | boolean | | An answer is arriving elsewhere: the composer offers a stop, not a send |
| onEdit | (id) => void | | |
| onCancelEdit | (id) => void | | |
| onCopy | (value) => void | writes to the clipboard | |
| onHighlight | (turnId, text) => void | | A passage was marked |
| onReplyInThread | (text, rect) => void | | Open a thread on the marked passage |
| onBookmark | (turnId, text) => void | | Offers "Bookmark" in the highlight's menu; called again to take it back |
| bookmarked | readonly string[] | | This turn's kept passages. Keep the array stable |
| onRegenerate | (id) => void | | Draws the regenerate button |
| onFeedback | (id, verdict) => void | | Draws the thumbs |
| feedback | "up" \| "down" \| null | null | Which one is lit |
| answerActions | boolean | true | Leave the row out |
| renderPart | (part, { turnId }) => ReactNode | | Draws custom parts — see below. Keep it stable |
| composerMenu | ComposerMenuItem[] \| false | built-in three | The composer's "+" menu; false removes the "+" |
| labels | ChatLabels | English | Every word the row says — see Labels |
The live row carries data-active-input, so a page can style the composer
without knowing which turn it is. The case it exists for: a gradient fading the
conversation off the bottom edge cannot tell the answer from the box you type
in, and a washed-out composer reads as one you are not allowed to use. Lift it
over the fade:
.feed [data-active-input] { position: relative; z-index: 6; }questionAlign is end by default, because the composer is about to become
the reader's own bubble and those sit right. stretch fills the row instead,
which is what an opening composer wants: on an empty conversation it is not a
message on its way, it is the box under the openers — and a pill floating at
the right edge of a centred block reads as unrelated to the block.
Every callback is optional; a row with none of them renders and can be marked.
The row carries id="turn-<id>" so a host can scroll to one, and aria-busy
while its answer is arriving.
The composer at the bottom
The kit's argument is that the input is the message: it stands at the end of the conversation and becomes the bubble where you typed it. Some products want the shape every other chat has instead — the box at the bottom, the conversation stacking above it. That is one prop, not a second kit:
<ChatExperience onSend={send} composer="docked" />What changes, and what does not:
- The box stays at the bottom.
Conversationpins its last child there — pushed down by an auto margin while the conversation is shorter than the view, held byposition: stickyonce it is longer. Both put its bottom on the same edge, so nothing moves when the conversation crosses from one to the other. - It still becomes the bubble. The live input is the last turn, as it
always was, so the morph is the one the kit already has. What is new is the
travel: a fresh composer takes the last place, the sent one is no longer
last and no longer sticky, and its
layoutanimation carries it up into the conversation where it now belongs. - The next question can be typed while this one is answered.
useChatTurnsopens the next input at send rather than at settle (nextTurn: "at-send"), the composer isbusywhile the answer arrives — Enter does nothing and the send glyph is a stop — and a send while an answer is in flight is refused rather than started on top of it. Queueing it is a separate thing. - A sent message still goes to the top. The same anchor the inline
composer uses: your question is brought to the top of the view and held
there while its answer is written underneath. The composer does not move
with it — it is
sticky, so the room the anchor scrolls into passes behind it. The room itself goes above the dock rather than below:stickyonly ever pulls an element up, so room underneath would leave the composer stranded in the middle of the view. - The keyboard is allowed for. On a phone the software keyboard comes up
over the bottom edge; the workspace gives up what
visualViewportsays is covered, so the composer rides on the keyboard's top edge. - Everything else is the same: the parts, the pane, the highlighter, editing
a sent message in place,
labels,surface="panes".
With a chat of your own, give its hook nextTurn: "at-send". Assembling the
rows by hand, the same shape is <Conversation dock> with the live row last,
busy={isStreaming} on it, and onStop on it rather than on the bubble being
answered.
Two rules everything follows
Surfaces nest in three steps. A ground is what a group of things sits
on, a card is an opaque panel raised on it, and an inset is a row set
into the card. --ick-ground, --ick-card, --ick-inset — a question group,
a tool call and an approval all use the same three.
The card is paper and opaque, which matters more than it sounds: a
translucent panel picks up whatever it is sitting on, which is how a tool call
inside an approval came out pale green, back when the approval was tinted. In the dark the card is a lifted grey,
because --ick-surface there is the page itself and a card painted with it
would sink into the ground rather than sit on it — and that grey is mixed,
not washed. It was nine percent white for a while, which looks identical on
the page and olive over a tint. The rule held in the light,
where the card is #fff, and was quietly false in the dark. An inset is mixed
from the card for the same reason. A test now reads the values rather than the
wiring: an alpha channel on either is the fault, whatever the number.
The ground stays a wash, deliberately. It is the bottom of the stack, so there is nothing under it to pick up but the page.
Stacked boxes are separated by surface and gap, not by a rule. A row is an inset panel with space around it, and nothing is underlined. A tool call used to draw a line under its header and a code block one under its label, which with two sections open made three stacked rules in a component the size of a paragraph — each saying again what the surface had already said.
All three steps, every time. A question is a group (ground) holding a card holding rows; a tool call is a ground holding a card holding its input and output; an approval is a ground holding a card holding what it is asking about. The tool used to be one box, and the box was the grey one — the same three surfaces stacked backwards, which on its own reads fine and beside a question card reads as a different system.
The approval had the same shape of fault from the other end: it was a tinted box and the only thing on paper was the tool call, so the title and the buttons sat straight on the ground. A question card puts its header and its Next button on the card, and this now does the same.
And the tint is gone, which is worth its own paragraph. An approval is a question — "may I run this" is the same species as "who else lives in the household": the assistant asking, blocking, with an answer. It should look like one. The tint was there on the reasoning that this is the one thing in an answer allowed to look like a box that stops you; the reasoning is real and colour was the wrong instrument. Everywhere else the marker is a small mark pointed at one thing and means this one — the badge on the option you picked, the stroke you drew, a citation, a source's number. A wash across a whole box meaning "this kind of box" is a second job for the one accent, and at 8% it was too weak to be an alarm and too strong to be nothing. In the dark it came out olive, which is not in the palette at all.
What says "this is unanswered" is that the box has buttons in it, and nothing else in a turn does. They leave when it settles, the way a question card's rows leave when it folds — and like a folded question, the approval keeps its paper and its shadow rather than changing into something else.
A component that is given a surface takes the next step down rather than
repeating one. Inside an <Approval> the tool call is a row on its card —
inset, at the row corner, no ground of its own and no shadow. Two grounds is
one more than there is depth for, and so is two cards.
A rule down the side is a different device and stays: <Reasoning> uses one
to mark an aside, and <ChainOfThought>'s says each step follows from the one
above it.
Corners are concentric, on one chain. A box's corner is the corner of the thing inside it plus the gap between them, and there are four steps for the whole kit:
--ick-nest-inner 8 a badge, a chip, a fenced value
--ick-nest-row 16 an inset panel: an option, a field, a block of output
--ick-nest-card 24 paper, lifted off the ground
--ick-nest-ground 40 what the paper stands on
gaps: --ick-nest-pad 8 inside a card and a row, --ick-nest-ground-pad 16 around
a card on its groundGet it wrong and the two curves sit at different insets with the same radius,
leaving a crescent between them — the thing that reads as "not quite fitting"
without anybody being able to name it. It is written as calc() off a seed
rather than as a list of numbers, so changing a padding moves the corners with
it, and a test does the same sum for every nesting in the kit.
A component picks a step rather than deriving its own. Each used to derive: a tool call was a 6px block in a 14px card on a 22px ground, beside a question's 8 / 16 / 24 / 40. Both were internally concentric, and the two were nothing like each other — the same three surfaces at two scales, which reads as two systems rather than as one object holding different things. So a tool call and a question folded shut are now the same row, to the pixel: 40 tall, 16 in from the left, the glyph riding in the box a badge sits in. There is a story that stacks the two on one ground, and a test that compares every step of the two chains.
An answer's words start on the cards' edge. Everything in an answer's flow
— the prose, the actions under it, <Reasoning>, <ChainOfThought>,
<TaskList>, <Sources>, and a <SystemMessage> between turns — begins on
--ick-answer-column, which is --ick-nest-ground-pad (16): the left edge of
the white card of a tool call, an approval, a question or an artifact. The grey
grounds hang that padding outside it, and a card's own words are indented inside
the card the way a card's content always is. The prose ends on the mirror of
it, so on a phone it stops at the card's right edge too. A host card in
turn.parts, or hand-written prose beside the kit's, lines up by reading the
same token.
A short box takes the corner it can. A row folded shut is 40px tall and a 24px corner on it clamps to a pill — both of them, equally, which is the point.
A <CodeBlock> reads --ick-code-radius, so a box that nests one repoints it
at the step its own corner implies — the way <Tool> hands it the row's. It
reads --ick-code-pad the same way, for its inner padding: <Tool> takes that
down to 8 so a panel's label lands on the column its header's glyph is in, and
every section of a tool call — code or text — starts on that one column.
<Tool>
One tool call on the way to an answer: what was run, what with, what came back.
<Tool
name="search_web"
state="done"
summary="3 results"
duration={412}
input={{ query: "weather in Belgrade", limit: 3 }}
output={results}
/>| Prop | Type | Notes |
| --- | --- | --- |
| name | string | Set in mono: it is an identifier, not prose |
| state | "pending" \| "running" \| "done" \| "error" | Default "done" |
| summary | ReactNode | A sentence for what it did |
| input / output | unknown | See below |
| error | ReactNode | Drawn instead of the output |
| duration | number | In ms. Shown once it has finished |
| open / defaultOpen / onOpenChange | | Controlled or not |
| labels | Partial<Record<…, string>> | input, output, error, and a word per state |
Shut by default, because most of the time nobody cares — and open when it failed, because an error nobody can see has not been reported. That is derived from the state rather than forced by an effect, so a call that fails later opens itself, while one somebody deliberately shut stays shut.
What you give it decides how it is drawn. A string is text — wrapping
"Belgrade, 24°C" in a fence puts it in quotes with its newlines spelled out,
which is worse than reading it. An object is JSON, in a CodeBlock with its
copy button. An element is left alone, so anything you want drawn some other
way you draw yourself.
The state is never carried by colour alone: the glyph changes shape, and the row says which state it is in in words only a screen reader hears.
What a turn carries: TurnPart
An answer used to be one string, and everything the agent tier draws had
nowhere to live. A turn now carries parts alongside ai, and a SendHandler
streams them in among the prose:
const send: SendHandler = async function* (message) {
yield { kind: "reasoning", id: "r", text: "Two numbers matter here.", state: "thinking" };
yield { kind: "tool", id: "t", name: "search_web", state: "running", input: { query } };
yield { kind: "tool", id: "t", name: "search_web", state: "done", output, duration: 412 };
yield { kind: "reasoning", id: "r", state: "done" };
yield "The Higgs weighs about 125 GeV."; // a delta of the answer's prose
};A streamed item is either a string — appended to ai, as before — or a
TurnPart, merged into turn.parts by its id. The merge is shallow
and that is the point: send the state change on its own and the text that
arrived before it is still there. <ChatTurnRow> draws each kind with the
component that owns it.
| kind | Drawn as | Carries |
| --- | --- | --- |
| reasoning | <Reasoning> | text, state, duration |
| tool | <Tool> | name, state, summary, input, output, error, duration |
| tasks | <TaskList> | title, tasks, collapsible |
| chain | <ChainOfThought> | steps, state, duration |
| sources | <Sources> | sources, title, collapsible |
| approval | <Approval> | title, description, tool, decision, choices |
| question | <QuestionGroup> | title, questions, answers, activeIndex, collapsible |
| notice | <SystemMessage> | text, tone |
| artifact | <ArtifactCard> | title, meta, preview, lang, content, state |
| custom | whatever renderPart returns | type, data — the host's own card |
reasoning and chain are the same job at two grains — a block of prose, or
steps that follow from one another. Sending both for one stretch of thinking
says it twice.
Where a part sits in the prose
The answer is drawn in the order the stream sent it. A part remembers how much
prose had arrived when it did — at, in characters of ai — and is drawn at
that point, so a sentence that introduces a card comes before the card:
yield "I suggest this change:"; // prose
yield { kind: "custom", id: "change", type: "plan-diff", data }; // at: 22
yield " Tell me if it looks right."; // prose, after the carduseChatTurns stamps at on a part's first appearance and nothing moves it
afterwards: an update to a part is not a new part, and a card a host adds with
updatePart after the answer lands at the end. Give at yourself to place a
part — at: 0 puts it before all the prose. A part with no at sits before the
prose, which is where every part sat before this existed, so turns built by
hand look as they always have.
The prose is still one string: ai is what Copy copies, what a screen reader
hears and what a version keeps. Only the drawing is cut, at the points the
parts arrived — each run is its own block of markdown, and a highlight cannot
cross a card. The row of actions goes after whatever the answer ends with, so an
answer made only of parts has one too, without a Copy of nothing.
Your own cards: custom
Every other kind is a component in this package. custom is the host's: type
says which of your cards it is, data is whatever that card needs, and
renderPart draws it — in its place among the other parts, inside the answer
and its entrance.
import type { CustomPart } from "inline-chat-kit";
// Streamed like any part…
yield { kind: "custom", id: "plan", type: "plan-diff", data: { changes, status: "proposed" } };
// …drawn by the host. Outside the component, so it is stable.
const renderPart = (part: CustomPart, { turnId }: { turnId: string }) =>
part.type === "plan-diff" ? <PlanDiff turnId={turnId} id={part.id} {...(part.data as PlanDiffData)} /> : null;
// …and changed after the answer has finished, by id. Only `data` is replaced.
updatePart(turnId, { kind: "custom", id: "plan", data: { changes, status: "applied" } });Without renderPart, or when it returns null, the part draws nothing — no
placeholder, no error. A type the host does not recognise is a type it chose
not to draw. data is replaced whole on an update, not merged: it is yours,
and the kit does not guess its shape.
ChatExperience calls useChatTurns itself, so a host using it passes its own
instead — chat={useChatTurns({ onSend })} — to hold updatePart.
The second argument to renderPart is { turnId, openArtifact, closeArtifact }
(CustomPartContext), so a card can open the pane — see
Drawing the pane yourself.
Citing a source from the prose
[^1] in the answer is a citation marker, and the number is a position in
the turn's sources part:
yield { kind: "sources", id: "s", sources: [atlas, pdg] };
yield "The combined figure is 125.25 GeV[^1], to a fifth of a percent[^2].";It draws as an <InlineCitation> carrying the source's title, and the marker
is left out of the tokens — so a highlight drawn across the sentence, and the
text a thread quotes back, do not contain a stray [1].
This is the kit's one extension to the markdown grammar. GFM spells footnotes
the same way but wants a [^1]: … definition in the document; a model streams
the marker and sends the list beside the text, never below it. Without it a
citation could only be written by hand in JSX — which a stream cannot do, so
the component existed and no real conversation could reach it.
Send the list before the prose that cites it. Sent after, the markers draw bare and fill in later, which works and looks like a bug.
A question is answered by the person reading it, not by the stream — so
useChatTurns also returns updatePart(turnId, part), and ChatTurnRow
reports through onAnswerQuestion / onEditQuestion. The row never keeps the
answer; the parts are yours.
Parts are cleared when a turn is answered again: the tool calls that produced the old answer are not evidence for the new one.
One header for everything that folds
<Tool>, <Reasoning>, <ChainOfThought>, <TaskList> and <Sources> all
open the same way, so they share DisclosureHeader and DisclosureBody
— internals, not exports. The header owns the button-or-heading switch, the
aria-expanded / aria-controls wiring, the chevron, the shimmer under a
pending label, and the guard that stops a click on the row from starting a
marker on the highlighter underneath. The body owns the always-present
container and the height reveal.
Two fits, and the difference is real rather than decorative:
| | Fit | Why |
| --- | --- | --- |
| Tool, TaskList, Sources | band | A full-width row. It has a right edge, so the meta and the chevron are pushed to it. |
| Reasoning, ChainOfThought | inline | A label that hugs its own words. These sit in the flow of an answer as asides; a chevron pushed to a right edge 500px away floats alone in white space. |
A component that means something different by its label repoints a token
from its own root rather than passing a class in — two .label rules from two
stylesheets have equal specificity, and which one wins is import order.
--ick-disclosure-label, -font, -weight, -size, -glyph, -meta.
<QuestionGroup> folds too and does not use this, for a reason worth stating:
its shut state is a card, and opening it is a FLIP morph between two layouts
rather than a box growing from zero height under a row. A test holds that
exemption, and the exemption stays honest — the day it stops being a morph, it
owes an answer.
<Reasoning>
What the model worked through before it answered.
<Reasoning state={thinking ? "thinking" : "done"}>{thoughts}</Reasoning>| Prop | Type | Notes |
| --- | --- | --- |
| children | ReactNode | The thinking. Prose — see Tool for structure |
| state | "thinking" \| "done" | Default "done" |
| duration | number | In ms. Left out, the block times itself |
| open / defaultOpen / onOpenChange | | Controlled or not |
| labels | Partial<Record<…, string>> | thinking, thought, thoughtFor |
Open while it thinks, folded away once the answer starts. That is the one detail every kit shipping this has converged on, and it is right: thinking is worth watching while it happens and worth almost nothing afterwards — but it has to stay reachable, because the times it matters are exactly the times the answer looks wrong.
Folding is the block's preference, not something done to the reader. Open it and it stays open, however many times the state changes underneath.
Without a duration it times itself, from the moment it starts thinking to the
moment it stops. Pass one when you already know — replaying a transcript, where
the thinking did not happen just now.
While it thinks the word shimmers, which is how this kit says "provisional"
everywhere. It is a real word in the button rather than a <Loader>: the loader
is decorative and marks itself aria-hidden, and hiding this one would leave a
control with nothing to call it.
<Context>
How full the context window is.
<ChatHeader title="Higgs boson" subtitle="14 turns">
<Context used={840_000} total={1_000_000} label={false} />
</ChatHeader>| Prop | Type | Notes |
| --- | --- | --- |
| used / total | number | In tokens, or whatever unit you count in |
| warnAt | number | Fraction. Default 0.8 |
| label | ReactNode \| false | The percentage by default; false for the ring alone |
| labels | Partial<Record<…, string>> | name, of, tokens, nearlyFull |
Small on purpose. It is a gauge, not a feature, and it earns its place for one reason: it is the only honest way to explain why a long conversation starts forgetting. Without it the forgetting looks like the model being stupid rather than the window being full.
Which is why the warning says what happens next rather than only that a
number is high — "82%" tells somebody nothing they can act on. The whole
sentence is the meter's accessible name and its title, so it reaches a
pointer and a screen reader alike.
Two colours, not three: quiet until warnAt, then the danger colour. A gauge
with an amber in the middle makes somebody learn a scale to read a number they
can already see.
<Approval>
"It wants to do this. Is that all right?"
<Approval
title="Run a command in your shell"
description="It removes the generated screenshots. Nothing else is touched."
decision={decision}
onDecide={setDecision}
>
<Tool name="bash" state="pending" input={{ command: "rm -rf Shots/" }} defaultOpen />
</Approval>| Prop | Type | Notes |
| --- | --- | --- |
| title | ReactNode | What is being asked. Names the region |
| description | ReactNode | Why, or what it will touch |
| children | ReactNode | The thing itself — usually a <Tool> or a <CodeBlock> |
| decision | "once" \| "always" \| "denied" \| null | null while it is still asking |
| onDecide | (decision) => void | |
| readOnly | boolean | A record of a decision made elsewhere |
| choices | ("once" \| "always" \| "deny")[] | Which answers are offered. All three by default |
Three answers, not two. "Yes" and "yes forever" are not the same answer, and a UI offering one button for both collects the wrong one. Allow once is the primary: the narrow permission is the one that should be easiest to give, and the standing one should cost a moment's thought. Deny sits alone on the left with the two that say yes pushed right — a destructive choice flush against an affirmative one is a mis-click waiting to happen — and it is first in the DOM too, so a keyboard reaches the safe answer without tabbing past the other two. It turns red only under the pointer, because a permanently red button is the first thing the eye lands on.
Two answers, where "forever" means nothing. Applying one change to a plan
happens once; choices={["once", "deny"]} leaves "Always allow" out. Nothing
else moves: Allow once is still the primary, Deny is still first in the DOM and
alone on the left, and the record it settles into says only what was decided.
<Approval title="Apply the change to your plan" choices={["once", "deny"]} onDecide={decide} />Give it something to show. An approval with nothing under it is asking for a signature on a blank page.
Decided, it stops being a set of buttons and becomes a record of what was decided. Live controls under a decision already made invite a second one that contradicts the first.
As a TurnPart it is { kind: "approval", id, title, description?, tool?,
decision?, choices? } — data, like every part, so the tool it names is drawn for it
rather than passed in as an element. <ChatTurnRow> reports through
onDecideApproval.
<Sources> and <InlineCitation>
A numbered marker in the text, and the list underneath.
<p>
The Higgs is a point particle, so{" "}
<InlineCitation index={1} source={sources[0]} onSelect={(_, s) => setActive(s.id)}>
it has no measurable spatial extent
</InlineCitation>.
</p>
<Sources sources={sources} activeId={active} />| Sources | Type | Notes |
| --- | --- | --- |
| sources | Source[] | { id, title, url?, origin?, quote? } |
| title | ReactNode | Defaults to labels.title |
| collapsible | boolean | false |
| activeId | string \| null | The one arrived at from a marker |
| onSelect | (source, index) => void | |
| InlineCitation | Type | Notes |
| --- | --- | --- |
| index | number | 1-based, and it has to match the entry's place |
| source | Source | Named in the marker's accessible name |
| children | ReactNode | The passage this citation speaks for — marked, if given |
| onSelect | (index, source?) => void | Without one the marker is not a control |
The citation marker and the highlight marker are the same interaction seen
twice. The kit already had a way of saying this run of words is picked out
— the marker somebody draws over an answer to ask about it. A citation is that
same statement made by the answer rather than by the reader, so it is drawn the
same way rather than in a second visual language nobody has learned. Give
InlineCitation the passage as children and the passage is marked; give it
none and the marker stands on its own after whatever precedes it.
Pressing a marker marks the entry it points at rather than scrolling to it. The list is already under the answer, and moving the page under somebody who clicked a marker in a sentence they were reading loses them the sentence.
The list is open by default. Sources are the difference between an answer somebody can check and one they have to trust, and folding that away by default says the opposite of what a citation is for.
<ChainOfThought>
How the answer was arrived at, step by step.
<ChainOfThought
state={thinking ? "thinking" : "done"}
duration={4200}
steps={[
{ id: "a", label: "The question is about size, not mass", body: "A point particle has none." },
{ id: "b", label: "Checked the measured value", body: <Tool name="search_web" … /> },
]}
/>| Prop | Type | Notes |
| --- | --- | --- |
| steps | Thought[] | { id, label, body?, state? } |
| state | "thinking" \| "done" | thinking holds it open and narrates the running step |
| duration | number | In ms, for the whole chain |
| open / defaultOpen / onOpenChange | | Controlled or not |
| labels | Partial<Record<…, string>> | through, step, steps, thinking |
Three components in this kit draw a sequence, and the line between them is the only reason there are three:
| | What it is | Shape |
| --- | --- | --- |
| Reasoning | The model talking to itself | Prose, unstructured |
| TaskList | A plan | Known up front, fixed order, items change state |
| ChainOfThought | A derivation | Grows; each step follows from the one above |
That last word is what the line down the glyph column draws. A task list has no line between its items, because a plan's items do not follow from each other — they are a set, in an order somebody chose.
A step's body is whatever you put there: prose, or a <Tool> if the step was
a tool call. While the chain is thinking its header carries the running step's
label rather than a count — that is the question somebody watching is asking,
and the reason to look at a folded chain at all.
<TaskList>
What the agent means to do, what it is doing, and what it has finished.
<TaskList
title="Plan"
collapsible
tasks={[
{ id: "read", label: "Read the care plan", state: "done", detail: "42 lines" },
{ id: "gaps", label: "Find the gaps in the weekly cover", state: "running" },
{ id: "draft", label: "Draft the questions for the family" },
]}
/>| Prop | Type | Notes |
| --- | --- | --- |
| tasks | Task[] | { id, label, state?, detail? } |
| title | ReactNode | Gives it a row to fold into. Without one there is no row |
| collapsible | boolean | false |
| open / defaultOpen / onOpenChange | | Controlled or not |
| labels | Partial<Record<…, string>> | The four states, and progress ("{done} of {total}") |
A task is pending, running, done or error — the same four as a tool
call, and the same glyphs, because they are the same four states and naming
them differently in two places buys nothing.
The order never changes. A list that sorted itself as work progressed would move the line somebody is reading out from under them, and the sequence is half of what the list is saying — these steps, in this order. Only the glyphs change.
collapsible folds it away once every task is done: a plan is worth watching
while it runs and worth little afterwards. Anybody reading it can overrule
that, in either direction, for good.
The one being worked on carries aria-current="step", so a screen reader can
jump to "where is it up to" rather than counting down the list.
<QuestionCard> and <QuestionGroup>
A structured question inside a conversation: the assistant asks something with a shape to it, and the answer is picked or typed rather than written out.
<QuestionGroup
id="about-them"
title="Setting up the run"
questions={questions}
answers={answers}
activeIndex={activeIndex}
collapsible={done && questions.length >= FOLDABLE_FROM}
onCommit={(id, answer) => setAnswers((all) => ({ ...all, [id]: answer }))}
onEdit={setEditing}
/>A Question is one of three shapes — inputs (type something), single (pick
one), multi (pick several, optionally with a "something else" field). Each
carries a shortTitle, which is what it is called once it folds into a row.
A card is in one of three states, and morphs between them:
| state | what it is |
| --- | --- |
| upcoming | one dim row, waiting its turn |
| active | the question, open, being answered |
| collapsed | one row: the short title, the answer as chips, and a way back in |
QuestionGroup holds a step's worth. title names the step, at the top,
and is also the fold control when there is one — which is the point of putting
it there. A control at the top does not move when the body under it changes, so
folding stops being two shapes swapping places and becomes one header with two
bodies. Left out on a foldable group, the count stands in so the control still
has a name; left out on one that cannot fold, there is no header at all.
Folded, the body is a single summary row — not a peek at the list, because a peek costs more height than the answers it shows.
Two decisions carried over from the original, both worth keeping: single
waits a beat after a choice before committing, or the card is gone before
anyone sees what they picked; and the "something else" row is a <label>, not
a button, because an input inside a button is not reliably focusable.
Two changed. The collapsed row is a single <button> naming what it does
("Edit answer: Household") rather than a click handler on a <div> with
another button inside it — that could be clicked but not tabbed to. And the
letter badges are aria-hidden: the letter is a visual index, and left in the
tree it turns a field called "Their name" into one called "a Their name".
Composing a fourth kind of question
Three shapes are not the only three. The parts a card is built from are exported, so a shape the kit does not ship is a composition rather than a fork — and it arrives already wearing the same tokens, focus behaviour and ARIA as the ones that do.
<QuestionShell
number={3}
title="How soon do they need this?"
subtitle="Roughly is fine"
footer={<Button variant="secondary" size="m" onClick={commit}>Next</Button>}
>
{levels.map((level, i) => (
<QuestionOptionRow
key={level.id}
letter={"abc"[i]}
title={level.title}
description={level.description}
selected={picked === level.id}
onClick={() => setPicked(level.id)}
/>
))}
<QuestionFieldRow
letter="d"
label="Anything we should know"
value={note}
onChange={setNote}
/>
</QuestionShell>| Part | What it is |
| --- | --- |
| QuestionShell | The card: header, the column the rows sit in, a right-aligned footer |
| QuestionOptionRow | A row that picks. A <button> with aria-pressed |
| QuestionFieldRow | A row that is typed into. A <label>, so the whole row focuses the input |
| QuestionOtherRow | The "something else" row: reads as an option, is a text field |
| QuestionBadge | The 24px square with the letter or the number |
Each takes a className that is added to its own rather than replacing it,
spreads the rest of its props onto the element it ends in, and forwards its ref
to the thing worth having one for — the input, in the two rows that have one.
On the two rows that take one, className styles the row and everything else
goes to the input.
QuestionShell paints the card — background, radius, shadow — unless you pass
card={false}, which is what QuestionCard does: the box that morphs between
the three states is its own, and two would nest.
letter is optional on all three rows. Left out, the row starts at its title.
onEnter fires on Enter unless your own onKeyDown called preventDefault
first, which is how a handler says it has dealt with the key.
<EmptyState> and <Loader>
The two ends of a conversation that has not happened yet: what is on screen before anybody asks, and the gap between sending and the first word.
| EmptyState | Type | Notes |
| --- | --- | --- |
| icon / title / description | ReactNode | Each optional; nothing is drawn in place of what you leave out |
| suggestions | string[] | Openers |
| onSuggestion | (text: string) => void | Without it, no openers are drawn |
| suggestionsLabel | string | Names the group. Default "Suggestions" |
title renders as text, not a heading. This sits inside a conversation the
host already owns, and claiming a level in their document is not ours to do —
pass <h2>…</h2> if it should be one.
| Loader | Type | Notes |
| --- | --- | --- |
| variant | "dots" \| "shimmer" | Default "dots" |
| children | ReactNode | The words the shimmer runs through |
| label | string \| null | Default null — see below |
The loader is silent by default. useChatTurns already announces that a
response is coming, and a second live region saying the same thing means
hearing it twice. Pass label only when nothing else is speaking for you.
ChatTurnRow shows it between the question being sent and the first word
landing, so a sent question is never a blank space.
<AnswerActions>
Copy, regenerate and a verdict, under a settled answer. ChatTurnRow renders
it for you; it is exported for anyone composing their own row.
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| text | string | | Required. What copy takes |
| onCopy | (text: string) => void | writes to the clipboard | |
| onRegenerate | () => void | | Omit and the button is not drawn |
| onFeedback | (verdict: "up" \| "down" \| null) => void | | Omit and the thumbs are not drawn |
| feedback | "up" \| "down" \| null | null | Controlled |
| busy | boolean | false | While regenerating |
| reveal | boolean | false | Invisible until hovered or focused |
| labels | Partial<Record<…, string>> | | |
| children | ReactNode | | Your own controls, after the built-in ones |
Only what has somewhere to report is drawn: no onRegenerate, no regenerate
button. A control that calls nothing looks like a feature and behaves like a
dead end.
Pressing the verdict already given reports null — that is how somebody takes
it back.
Inside a turn they appear when the answer settles. Offering to copy a half-written answer, or to rate one, is offering the wrong thing.
<Conversation>
The scroll container. It keeps up with an answer as it arrives and stops the instant the reader scrolls away, with a button offering the way back.
<Conversation>
{turns.map((turn) => <ChatTurnRow key={turn.id} turn={turn} … />)}
</Conversation>| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| anchorId | string | | Hold this element at the top instead of following the end |
| anchorOffset | number | 0 | How far below the top edge it sits — leave room for a fixed header |
| threshold | number | 64 | How close still counts as following |
| scrollButton | boolean | true | The way back |
| scrollButtonLabel | string | "Jump to the latest" | |
| follow | boolean | true | false makes it a plain scroll container |
| dock | boolean | false | The last child is pinned to the bottom edge — see The composer at the bottom |
| className | string | | Goes on the root, which is the box you lay out |
| viewportClassName | string | | Goes on the element that scrolls — padding belongs here |
ref is forwarded to the viewport, not the root: anyone reaching for a ref
here wants to scroll something, and the root does not scroll.
Three things worth knowing.
anchorId is the one that changes the feel. Without it the view follows
the end of the content, which is what a chat that stacks downwards wants. With
it, the named element is brought to the top and held there while the answer
grows underneath — so a reader sees their question and its answer, and not the
whole conversation pushed up from below with the composer ending past the fold.
Point it at the turn that was just submitted:
const [anchor, setAnchor] = useState<string | null>(null);
const send = (id: string, value: string) => { setAnchor(id); submit(id, value); };
<Conversation anchorId={anchor ? `turn-${anchor}` : undefined} anchorOffset={100}>This needs room to scroll into — an element cannot be brought to the top of a
container that ends just below it. A large padding-bottom on the viewport is
what provides it.
Without an anchor it follows the end of the content, not the bottom of the container, and those are only the same when nothing is padded below. A chat with a screen-height pad beneath it would otherwise scroll the answer off the screen to sit in front of a blank space.
And it reads the reader's intent from the input, not from the scroll event. A component that watches scrolling cannot tell its own from theirs, and ends up either dragging them back down mid-sentence or never following at all. A wheel upwards, a page key, a drag away from the end: any of those and it lets go.
<ArtifactCard>, <ArtifactPane>, <ChatLayout>, useArtifacts
What the answer produced, when it is bigger than the answer — a plan, a document, a file. Three pieces and one decision.
const artifacts = useArtifacts();
<ChatLayout
pane={({ narrow }) =>
artifacts.openId ? (
<ArtifactPane title="5k training plan" meta="8 weeks" modal={narrow} onClose={artifacts.close}>
<YourPlan />
</ArtifactPane>
) : null
}
>
<Conversation>
<ChatTurnRow turn={turn} openArtifactId={artifacts.openId} onOpenArtifact={(_, id) => artifacts.toggle(id)} />
</Conversation>
</ChatLayout>The kit decides where the pane goes. On the right, with the conversation
making room; below <ChatLayout>'s width it covers the conversation instead. A
preview pane is one of the few patterns every AI chat now has, and the worth of
a pattern is that it is the same every time — ask for a plan, get a card, press
it, the plan opens on the right. A kit that let each host place it would be
shipping four chats that behave differently and calling it flexibility.
The kit does not decide what is in it. <ArtifactPane> takes children: a
plan, a table, a document, a diagram. That is the part that actually differs
between products, and the only part.
| Prop | Type | Notes |
| --- | --- | --- |
| <ArtifactCard> id | string | What the pane opens. The card and the pane share nothing else |
| title, meta | ReactNode | |
| kind | "code" \| "text" | How the preview is drawn |
| content | string | Absent while it is being written, which is how one usually arrives |
| lines | number | How much shows before the cut. Default 8 |
| open | boolean | True while its pane is the one on screen |
| onOpen | (id: string) => void | Without one the card is a record, not a control |
| <ArtifactPane> modal | boolean | See below |
| <ChatLayout> pane | ({ narrow }) => ReactNode | |
| <ChatLayout> surface | "flush" \| "panes" | One surface, or two. See below |
modal is the one prop that changes behaviour, and it is not about
position. Covering the conversation changes what the pane is: focus has to
be held inside it and Escape has to close it, because there is nothing usable
behind it. Beside the conversation both would be wrong — trapping focus would
lock a reader out of the chat they are still reading. <ChatLayout> sets it
from its own width, so you only pass it yourself if you are placing the pane
without one.
That is the part worth having in a library rather than the box. On open, focus moves to the pane's heading — not into its first control, which would skip what the thing is — and it is not trapped unless the pane is covering the chat.
Two panes, not one page split in half
By default the conversation fills the layout and the pane is the only card on
it — which is what a chat that owns the whole window wants. surface="panes"
makes the conversation a card of its own instead:
<ChatExperience onSend={send} surface="panes" artifact={artifact} />Both surfaces are drawn from the same tokens — --ick-chat-pane-surface is
--ick-artifact-pane-surface, and the radius follows — because two panes side
by side have to be the same kind of thing, or the chat reads as the
background and the pane as a dialog over it. One number,
--ick-chat-pane-inset, is the ring of space around both and the gap between
them, so the frame is even the whole way round. No divider: the gap is what
says there are two of them.
Below <ChatLayout>'s breakpoint the corners and the inset go: the pane is a
sheet over the conversation there, and a card inside a card with a sheet over
both is three surfaces for one screen.
Inside the card, --ick-page is the card — so the header's tint and the fades
at both ends end in the colour they are standing on rather than in the ground
outside it.
Drawing the pane yourself
ChatExperience places the pane beside the conversation. A host with a layout
of its own — its own column, a drawer, a route — holds which artifact is open
and tells the kit to keep out of the way:
const [openId, setOpenId] = useState<string | null>(null);
const open = openId ? findArtifact(openId) : null;
<div className="workspace">
<ChatExperience
chat={chat}
pane="none" // no pane here, and no room made for one
openArtifactId={openId} // the cards still show which one is open
onOpenArtifactChange={setOpenId} // a card pressed, or a custom card's openArtifact
renderPart={renderPart}
/>
{open && (
<aside className="my-column">
<ArtifactPane key={openId} title={open.title} onClose={() => setOpenId(null)}>
{open.body}
</ArtifactPane>
</aside>
)}
</div>openArtifactId/onOpenArtifactChangehold the state outside. Left out,ChatExperiencekeeps its own, as before.nullis a held "nothing open"; onlyundefinedmeans "not held".onOpenArtifactChangeis called either way, so a host can listen without holding.pane="none"draws noArtifactPane, makes no room for one and never callsartifact. Pressing a card reports the id (pressing the open one again reportsnull).- A custom card opens one too.
renderPart's second argument carriesopenArtifact(id)andcloseArtifact(), next toturnId: a caregiver in your card opens her profile the way anArtifactCardopens a plan. surface="panes"goes with it. The conversation becomes a card, your pane is the second one, and the two match without your having to copy the kit's radius and shadow.<ArtifactPane>stands on its own. OutsideChatLayoutleavemodaloff: it is a region, focus moves to its title when it mounts, and it neither traps focus nor takes Escape. Key it by the artifact's id, so opening a different one is a new pane — and focus moves to the new title.
<SystemMessage>
The conversation saying something about itself — not the reader, not the agent.
<SystemMessage>The oldest messages are dropping out of the window.</SystemMessage>
<SystemMessage tone="danger">Lost the connection. Nothing since your last message was saved.</SystemMessage>| Prop | Type | Notes |
| --- | --- | --- |
| children | ReactNode | The sentence. Say what happens next, not that a state changed |
| tone | "notice" \| "danger" | Two, because <Context> already settled that three is one too many |
Reachable from a stream as well, as a part of kind notice, which is the only
way anything gets into a conversation without the host placing it by hand.
It has no icon, and that is the component rather than an omission from it. Every picture in this kit carries a state the words beside it also carry — queued, running, failed, allowed — so a reader the picture does not reach loses nothing. An icon here would say "something is being announced" beside a sentence announcing it.
No dismiss and no action. It is a line of the transcript, not a toast: dismissing one would be editing what happened. A host that wants a button under it composes one, which costs them a line and costs this component an API.
No live region. The kit has one — see announce — written to on a later
tick. A second one says everything twice, which is the fault that region exists
to have fixed. A host streaming a notice should announce it.
<Branch>
Which answer you are looking at, and how to reach the others.
<Branch total={turn.versions?.length ?? 0} index={turn.versionIndex ?? 0} onSelect={show} />| Prop | Type | Notes |
| --- | --- | --- |
| total | number | How many answers this turn has had |
| index | number | Which is on screen, from zero. Out of range is clamped |
| onSelect | (index: number) => void | |
| labels | Partial<{ previous, next, position }> | position fills in {index} and {total} |
It draws nothing at all when total is under two. A control reading "1 of
1" offers to take you nowhere, so a turn answered once looks exactly as it did
before there were versions.
Regenerating keeps the old answer. It used to overwrite ai and parts,
which threw away the answer being compared against — and comparing is the only
reason to press regenerate. A turn now carries versions: TurnVersion[] and
versionIndex, useChatTurns returns showVersion(id, index), and
<ChatTurnRow> draws the control beside the answer actions when you give it
onShowVersion.
ai and parts stay what they were — the answer on screen. They are kept
equal to versions[versionIndex] by one function that both writers (the
batched stream flush and the turn patcher) go through; two writers for one fact
is how they drift, and a test compares them after a stream.
Both fields are optional, so a turn a host built by hand still renders — the
same tolerance parts has.
<Attachments>
What goes along with a message.
<Attachments attachments={files} onRemove={(id) => drop(id)} />| Prop | Type | Notes |
| --- | --- | --- |
| attachments | Attachment[] | Required. Nothing to show draws nothing at all |
| onRemove | (id: string) => void | Leave it out and they are a record rather than a control |
| labels | Partial<{ remove }> | |
An Attachment is { id, name, url?, type?, size? }. An image with a url
shows itself; everything else shows a glyph, its name and its size — a
thumbnail of a PDF at 64px is a grey rectangle with a corner turned down and
tells you less than the filename does.
The same row draws them in the composer and under the message once it has been
sent. onRemove is the whole difference between a control and a record, and
<ChatInput> stops passing one the moment the message goes.
In the composer. <ChatInput> opens the picker from its + and keeps what
comes back, unless you take over:
| Prop | Type | Notes |
| --- | --- | --- |
| attachments | Attachment[] | Controlled. Left out, the composer keeps its own |
| onAttach | (files: File[]) => void | Given, the composer hands the files over instead of attaching them — for uploading first and attaching the URL you get back |
| onRemoveAttachment | (id: string) => void | |
| accept | string | Passed to the picker. Defaults to image/* |
| multiple | boolean | Off |
onSubmit is (value, attachments). That second argument is the point: before
it, a file could be picked, shown in the composer, and then quietly dropped on
send — the message went and the picture did not, which is worse than not
offering the button. A picture on its own is a message, so an empty box with
something attached still sends.
The object URLs the composer makes are revoked — when one is removed, when
one replaces another, and on unmount. createObjectURL pins the file in memory
until it is; nothing was revoking, so attaching and removing ten times leaked
ten of them.
They arrive at your SendHandler on the context: (message, { signal, turnId,
attachments }). And they live on the turn as turn.attachments, which is what
<ChatTurnRow> hands back to the composer so a sent message still shows what
went with it.
<CodeBlock>
A fenced block: the language, a copy button, and code that scrolls sideways rather than widening the answer. The markdown renderer uses it for every fence, and it is exported for use on its own.
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| code | string | | Required |
| lang | string | | The fence's language. Unknown ones render unhighlighted |
| label | string \| false | the language | false drops the caption |
| copyable | boolean | true | false with label={false} removes the bar entirely |
| onCopy | (code: string) => void | writes to the clipboard | |
| copiedFor | number | 1600 | How long the button stays confirmed, in ms |
Eleven languages are registered: TypeScript, JavaScript, HTML/XML, CSS,
JSON, YAML, Bash, Python, SQL, Markdown and diff — plus the aliases people
actually type (ts, tsx, js, sh, py, yml, …). lowlight/common is
37 languages and 51.6 KB gzipped; these cost half of that and cover what a chat
actually shows. A language outside the list renders unhighlighted rather than
throwing.
And they are not in your bundle until something needs them. The grammars
are a 25 kB gzip chunk behind a dynamic import() — most conversations
never show a fence, and 25 kB is 42% of what the package used to weigh. The
first block on a page paints its code plain and colours in when the chunk
lands; every block after that is coloured on its first paint, because the
loaded highlighter is kept. There is no layout shift either way: the text is
the same, only the colour arrives late.
If that trade is wrong for you — a docs tool where every answer is code —
import { loadHighlighter } from "inline-chat-kit" and call it once at
start-up. It is idempotent and concurrent callers share the one fetch.
canHighlight(lang) answers whether a language is one of the eleven without
loading anything, for a caller deciding what to draw.
The scheme is ink at four weights rather than a syntax palette — this kit is
ink, paper and one acid yellow, and twelve colours dropped into it read as
somebody else's component. Six tokens (--ick-code-keyword, -string,
-comment, -name, -number, -attr) turn it into whatever palette you
already own.
A block is not markable. Preformatted text split into word tokens stops being preformatted, so the highlighter skips it; copy is what people want from code anyway.
<ChatHeader>
The chrome above the conversation: who you are talking to, what about, and the handful of things you can do to the whole thread.
<ChatHeader
title={firstQuestion}
subtitle="Claude Opus 5"
backHref="/"
actions={[
{ id: "bookmarks", label: "Saved highlights", icon: <Bookmark size={16} />, count: 3, pinned: true },
{ id: "share", label: "Share", icon: <Share2 size={16} />, onClick: share },
]}
>
<YourModelPicker />
</ChatHeader>| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| title | ReactNode | | What the conversation is about |
| subtitle | ReactNode | | Second line — the model, a count, a state |
| avatar | ReactNode | | Drawn before the title |
| headingLevel | 1–6 | false | 2 | The level belongs to your document |
| truncate | boolean | true | Long titles get an ellipsis, not a second line |
| onBack | () => void | | Renders a back button |
| backHref | string | | Renders a back link instead |
| backLabel | string | "Back" | |
| actions | ChatHeaderAction[] | [] | The managed actions. These are what collapse |
| overflowLabel | string | "More actions" | |
| variant | "plain" \| "glass" \| "bordered" | "plain" | |
| size | "s" \| "m" \| "l" | "m" | 40 / 48 / 56px |
| align | "start" \| "center" | "start" | center is the native arrangement |
| sticky | boolean | false | |
| elevateOnScroll | boolean | sticky | Border and backdrop appear once content scrolls under |
| collapseActionsAt | number \| false | 520 | Header width, not viewport width |
| landmark | boolean | true | false inside a panel, where banner would be a lie |
| children | ReactNode | | Anything the kit should not manage. Never collapses |
Each action is { id, label, icon, onClick?, href?, count?, active?, disabled?, pinned?, variant? }.
variant is how one action stands out — "primary" for the host's own — and
only applies while it is in the header rather than folded into the menu
