Chat

01Preview

Step through the live screens. Type in the composer and press Enter to move to Thinking; press Tab in an empty composer to use the suggestion.

<ChatPanel
  avatar={<TutorMark />}
  online
  actions={headerActions}
  footer={<>
    <ChatModeToggle value={mode} onValueChange={setMode} />
    <ChatComposer
      onSend={send}
      placeholder="Ask me anything about Business structures"
    />
  </>}
>
  <ChatMessage from="user" quote={highlight} quoteSource="Chapter 2 · Business structures">Can you explain this with a real example?</ChatMessage>
  <ChatMessage
    actions={<ChatMessageActions copyText={answerText} />}
  >
    {answer}
  </ChatMessage>
</ChatPanel>

02Installation

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

No provider is needed. The panel fills its container, so give the container a height (for example the column beside the lesson). Your app supplies the tutor mark or avatar image.

03Usage

import {
  ChatComposer, ChatMessage, ChatMessageActions, ChatModeToggle, ChatPanel, ChatSources, ChatThinking, ChatWelcome,
} from '@nuton/ui'

function Tutor() {
  const [messages, setMessages] = useState([])
  const [mode, setMode] = useState('grounded')
  const [thinking, setThinking] = useState(false)

  async function send(text: string) {
    setMessages((m) => [...m, { id: crypto.randomUUID(), from: 'user', text }])
    setThinking(true)
    const reply = await askYourAiService(text, mode) // your code, not part of @nuton/ui
    setThinking(false)
    setMessages((m) => [...m, { id: crypto.randomUUID(), from: 'assistant', ...reply }])
  }

  return (
    <ChatPanel
      avatar={<img src={tutorMark} alt="" />}
      online
      footer={<>
        <ChatModeToggle value={mode} onValueChange={setMode} />
        <ChatComposer onSend={send} sendDisabled={thinking} placeholder="Ask me anything about Business structures" />
      </>}
    >
      {messages.length === 0 && <ChatWelcome title="Hey Ada 👋" description="What's not clicking yet?" />}
      {messages.map((m) => (
        <ChatMessage
          key={m.id}
          from={m.from}
          sources={m.sources && <ChatSources sources={m.sources} />}
          actions={m.from === 'assistant' && <ChatMessageActions copyText={m.text} />}
        >
          {m.text}
        </ChatMessage>
      ))}
      {thinking && <ChatThinking variant={mode === 'research' ? 'research' : 'thinking'} />}
    </ChatPanel>
  )
}

• The components only display. Your app stores the messages, calls its AI service in onSend, and decides what Retry does.
• Show ChatThinking while you wait, and add the reply as one message when it is complete. If you stream text in, set busy on the panel until it finishes, so screen readers hear it once.
• Show ChatWelcome while there are no messages, and loading while the history loads.
• Assistant messages accept rich content (rendered markdown, lists, code, maths). Sanitise model output before rendering HTML.
• Every string has an English default. Pass labels (or title, subtitle, placeholder) to localise.

04Variants and sizes

The set has ten parts. Each matches a piece of the live AI Tutor.

Welcome

<ChatWelcome mark={<TutorMark />} title="Hey Ada 👋" description="I've read this whole chapter with you. What's not clicking yet?" />

Messages

The learner's message is a bubble on the right. A question about highlighted lesson text carries the quote in a card at the top of the bubble. The tutor's answer has no bubble; it reads as prose.

<ChatMessage from="user" quote={highlight} quoteSource="Chapter 2 · Business structures">
  Can you explain this with a real example?
</ChatMessage>
<ChatMessage from="user">What about partnerships?</ChatMessage>
<ChatMessage actions={<ChatMessageActions copyText={answerText} />}>{answer}</ChatMessage>

Sources from the web

Research answers list the pages they used. Each link opens in a new tab and says so to screen readers. Without a title, the link shows the site name.

<ChatMessage sources={<ChatSources sources={[
  { href: 'https://www.gov.uk/business-legal-structures', title: 'Set up a business: legal structures (GOV.UK)' },
  { href: 'https://en.wikipedia.org/wiki/Sole_proprietorship', title: 'Sole proprietorship (Wikipedia)' },
]} />}>
  {answer}
</ChatMessage>

Message actions

Live has one action: Copy. Its tooltip says “Copy”, then “Copied!” with a green check for two seconds. Good and Bad response toggles are optional (showFeedback) and off by default.

<ChatMessageActions copyText={answerText} />
<ChatMessageActions copyText={answerText} showFeedback onFeedbackChange={save} />
<ChatActionButton label="Regenerate"><RiRefreshLine /></ChatActionButton>

Thinking

<ChatThinking />
<ChatThinking variant="research" />

Answer mode

Grounded answers only from the learner's material. Research also searches the web; it is slower and costs more. Each option has a tooltip with that hint, also read as its description. Pass options for other modes.

<ChatModeToggle value={mode} onValueChange={setMode} />
<ChatModeToggle options={[{ value: 'short', label: 'Short' }, { value: 'detailed', label: 'Detailed' }]} labels={{ group: 'Answer length' }} />

Composer

A pill-shaped field that grows to 140px, then scrolls. The topSlot holds the “Asking about” card. While the field is empty, a suggestion shows as the placeholder; Tab or → fills it in, and a “Tab ⇥” chip says so (hidden on small screens).

<ChatComposer
  placeholder="Ask me anything about Business structures"
  suggestion="Explain this chapter with an example"
  topSlot={highlight && <ChatContextCard onRemove={() => setHighlight(null)}>{highlight}</ChatContextCard>}
  onSend={send}
/>

Measurements

05States and interactions

The live screens, then the states of the parts.

Component tokens

06Composition examples

The AI tutor beside a lesson: Chat dock

The tutor is a ChatDock: one element that is the Ask Nuri pill (Chat launcher), the compact panel and, on the web, a maximized panel; a sheet from the bottom centre on a tablet or phone. It holds a ChatPanel for its content, stays mounted so the conversation and the draft never reset, and replaces the earlier docked column with a separate full-view dialog.

<ChatDock
  open={open}
  onOpenChange={setOpen}
  maximized={max}
  onMaximizedChange={setMax}
  footer={composer}
>
  <ChatWelcome … />
  {messages}
</ChatDock>

• Render the conversation in one panel at a time. Two logs with the same messages would be announced twice.
• Closing the panel is not a layout hack: ChatDock turns it back into the pill and keeps everything in it.

Ask about selected text

Select words in the lesson. A Selection toolbar appears above them (Figma 575:19481). Ask AI Tutor puts the text in a ChatContextCard and moves focus to the composer; Add to notes saves it to the notes list and announces “Added to notes”. With a keyboard, press Alt+F10 (Option+F10 on a Mac) after selecting to reach the toolbar.

const lessonRef = useRef<HTMLElement>(null)
const composerRef = useRef<HTMLTextAreaElement>(null)
const [context, setContext] = useState<string | null>(null)

<article ref={lessonRef}>{lessonText}</article>
<SelectionToolbar
  container={lessonRef}
  onAddToNotes={(text) => addNote(text)}
  onAskAI={(text) => {
    setContext(text)
    composerRef.current?.focus()
  }}
/>
<ChatComposer
  ref={composerRef}
  topSlot={context ? <ChatContextCard onRemove={() => setContext(null)}>{context}</ChatContextCard> : null}
  onSend={send}
/>

• Move focus to the composer in onAskAI, so people can type their question straight away. The toolbar leaves focus where the action put it.
• The live app opens an explanation popover from its own highlight toolbar (“Ask Nuton”, “Explain”, “Simpler”…). Pass those as actions if you need them.

07API reference

ChatPanel

ChatWelcome

ChatMessage

ChatSources

ChatMessageActions and ChatActionButton

ChatThinking

ChatModeToggle

ChatComposer and ChatContextCard

Accessibility

You must: add replies as complete messages (or set busy while streaming), render the conversation in one panel at a time, give extra icon buttons a label, and sanitise any HTML you render from a model.

08Guidelines and related components

Do and don't

Related components

• ModalHolds the full view.
• SheetHolds a compact panel on phones.
• SourcesLarger citation cards for notes and research pages.
• ButtonHeader actions and the send button.
• Selection toolbarAsk about or save selected lesson text.