Skip to content
kitn AI/UI

Empty & first-run state

A new user lands on a blank thread — give them somewhere to start. Compose a <kai-empty> block (icon, headline, subtext) with <kai-suggestions> chips inside it, so the greeting and the starter prompts read as one piece. Click a chip below to start the conversation.

Compose the empty block

Section titled “Compose the empty block”

<kai-empty> is a slotted block: an icon in slot="media", the empty-title and description attributes, and a default slot for actions. Drop <kai-suggestions> into that default slot and the chips render as part of the first-run composition — not as a separate bar.

When a chip is clicked, <kai-suggestions> fires kai-select with the chosen value. Swap the empty block for <kai-chat> and stream the reply.

<div id="shell" style="height:100%">
  <kai-empty
    id="greeting"
    empty-title="Hi, I'm your assistant"
    description="Ask me anything — or pick a starter below to begin."
  >
    <!-- slot="media" accepts any icon or image -->
    <svg slot="media" width="24" height="24" viewBox="0 0 24 24" fill="none"
         stroke="currentColor" stroke-width="1.75"><path d="M9.5 3 11 8l5 1.5-5 1.5L9.5 16 8 11 3 9.5 8 8z"/></svg>


    <!-- default slot: suggestions live INSIDE the empty block -->
    <kai-suggestions id="starters"></kai-suggestions>
  </kai-empty>
</div>


<script type="module">
  import '@kitn.ai/ui/elements';


  const shell = document.getElementById('shell');
  const starters = document.getElementById('starters');
  starters.suggestions = [
    'How do I add kitn-chat to a React app?',
    'Theme the components to match my brand',
    'Stream tokens from my own backend',
  ];


  starters.addEventListener('kai-select', (e) => {
    const prompt = e.detail.value;
    // replace the empty block with a live chat, then stream the reply
    shell.innerHTML = '<kai-chat id="chat" style="height:100%"></kai-chat>';
    const chat = document.getElementById('chat');
    chat.messages = [{ id: crypto.randomUUID(), role: 'user', content: prompt }];
    // …append an assistant message and patch its content as tokens arrive
  });
</script>

The simple path: <kai-chat>’s built-in suggestions

Section titled “The simple path: <kai-chat>’s built-in suggestions”

If you don’t need a custom greeting, <kai-chat> renders starter suggestions on its own when the thread is empty. Set the suggestions property and the chips appear inside the chat’s own empty state — no extra components.

Pass an empty messages array and a suggestions property. <kai-chat> hides the suggestions as soon as the first message arrives.

<kai-chat id="chat" chat-title="Assistant" placeholder="Ask me anything…"></kai-chat>


<script type="module">
  import '@kitn.ai/ui/elements';


  const chat = document.getElementById('chat');
  chat.messages = [];
  chat.suggestions = [
    'Summarize what you can help me with',
    "What's the best way to get started?",
    'Show me an example',
  ];


  chat.addEventListener('kai-submit', async (e) => {
    const prompt = e.detail.value;
    const aId = crypto.randomUUID();
    chat.messages = [
      ...chat.messages,
      { id: crypto.randomUUID(), role: 'user', content: prompt },
      { id: aId, role: 'assistant', content: '' },
    ];
    chat.loading = true;
    // stream tokens into the assistant message…
    chat.loading = false;
  });
</script>

submit vs fill

Section titled “submit vs fill”

The suggestionMode property controls what happens when a user clicks a chip.

ModeBehaviourWhen to use
'submit' (default)Sends the prompt immediately, as if the user typed and hit Enter.Works well when suggestions are complete questions that need no editing.
'fill'Copies the text into the input so the user can edit before sending.Better for partial prompts or templates (e.g. “Translate this to ___”).
// submit mode (default) — one-click send
chat.suggestionMode = 'submit';


// fill mode — prefills the input, user edits then sends
chat.suggestionMode = 'fill';
// listen for fill events (kai-submit still fires when they send)
chat.addEventListener('kai-suggestion-click', (e) => {
  console.log('prefilled:', e.detail.value);
});

Next steps

Section titled “Next steps”