AI Chat `<mv-ai-chat>`

Interface de chat com IA: respostas em streaming com cursor, estado “pensando” com brilho, renderização segura de Markdown (listas, negrito, código com botão de copiar), editor de mensagens que cresce sozinho com anexos, seletor de modelo, sugestões, parar / regenerar e rolagem automática que cede ao usuário.

Categoria	Blocos
Tipo	Web Component (`<mv-ai-chat>`)
Status	estável
Também instala	button, kbd, shimmer-text, textarea
Keywords	ai, chat, assistant, llm, streaming, markdown, composer, conversation

When to use

A product needs a full assistant conversation with streamed replies, a thinking state and stop / regenerate
Users must attach files, pick a model or start from suggested prompts in one composer
Assistant replies contain Markdown lists and code blocks that users will want to copy

Avoid when

Only a single request is typed and its outcome, constraints and limits must be made explicit → use Intent Composer instead
The need is a quick search or command launcher rather than a conversation → use Command instead

Instalação

node scripts/add.mjs ai-chat --out ./src/marvelous

Agente de IA com o servidor MCP do Marvelous UI: install_components({ slugs: ["ai-chat"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Arquivos copiados (dependências incluídas): tokens/tokens.css, core/base.css, components/button/button.css, components/kbd/kbd.css, components/shimmer-text/shimmer-text.css, core/dom.js, core/element.js, core/i18n.js, components/textarea/textarea.css, components/textarea/char-count.js, core/motion.js, components/ai-chat/ai-chat.js, components/ai-chat/ai-chat.css.

Uso

Marcação de referência, para usar como ponto de partida e personalizar com atributos, data-* e variáveis CSS:

<mv-ai-chat id="aic-demo" label="Solen" model="solen-pro" style="height:680px;border:1px solid var(--mv-border);border-radius:var(--mv-radius-xl);overflow:hidden">
  <header class="mv-ai-chat-header">
    <mv-menu placement="bottom-start">
      <button class="mv-button mv-ai-chat-model" data-variant="ghost" data-size="sm" type="button">
        <span data-ai-chat-model-label>Solen Pro</span>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg>
      </button>
      <div data-content style="--mv-menu-width:17rem">
        <div class="mv-menu-label">Model</div>
        <div role="group" data-name="model">
          <button role="menuitemradio" value="solen-pro" data-label="Solen Pro" aria-checked="true"><span>Solen Pro<span class="mv-ai-chat-menu-desc">Deep reasoning</span></span></button>
          <button role="menuitemradio" value="solen-swift" data-label="Solen Swift"><span>Solen Swift<span class="mv-ai-chat-menu-desc">Fast everyday answers</span></span></button>
          <button role="menuitemradio" value="solen-code" data-label="Solen Code"><span>Solen Code<span class="mv-ai-chat-menu-desc">Built for coding</span></span></button>
        </div>
      </div>
    </mv-menu>
    <div class="mv-ai-chat-header-end">
      <button class="mv-button" data-variant="ghost" data-size="sm" type="button" data-ai-chat-reset>
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 20h9"/><path d="M16.4 3.6a2 2 0 0 1 2.9 2.9L7 18.8 3 20l1.2-4z"/></svg>
        <span class="mv-ai-chat-header-hide-sm">New chat</span>
      </button>
    </div>
  </header>

  <div class="mv-ai-chat-empty">
    <span class="mv-ai-chat-empty-mark" aria-hidden="true"><svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 2.5c.4 3.9 1.9 6.6 4.2 8 1.3.8 2.9 1.3 4.8 1.5-3.9.4-6.6 1.9-8 4.2-.8 1.3-1.3 2.9-1.5 4.8-.4-3.9-1.9-6.6-4.2-8-1.3-.8-2.9-1.3-4.8-1.5 3.9-.4 6.6-1.9 8-4.2.8-1.3 1.3-2.9 1.5-4.8z"/></svg></span>
    <h2>Hi Maya, ready to dive in?</h2>
    <p>Ask a question, attach a file or start from a suggestion.</p>
    <div class="mv-ai-chat-suggestions">
      <button class="mv-ai-chat-suggestion" type="button" data-prompt="Write a follow-up email about Ms. Chen’s quote"><strong>Write a follow-up</strong><span>about Ms. Chen’s quote</span></button>
      <button class="mv-ai-chat-suggestion" type="button" data-prompt="Summarize September sales"><strong>Summarize sales</strong><span>for September, in 5 points</span></button>
      <button class="mv-ai-chat-suggestion" type="button" data-prompt="Explain Web Components with an example"><strong>Explain Web Components</strong><span>with a code example</span></button>
    </div>
  </div>

  <form class="mv-ai-chat-composer">
    <div class="mv-textarea-group">
      <ul class="mv-ai-chat-attachments" aria-label="Attachments" hidden></ul>
      <textarea class="mv-textarea" rows="1" placeholder="Message Solen…" aria-label="Message Solen" aria-keyshortcuts="Enter"></textarea>
      <div class="mv-textarea-toolbar">
        <label class="mv-button mv-ai-chat-attach" data-variant="ghost" data-size="icon" title="Attach a file">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21 11-8.6 8.6a5.5 5.5 0 0 1-7.8-7.8l8.6-8.6a3.7 3.7 0 0 1 5.2 5.2l-8.6 8.6a1.8 1.8 0 0 1-2.6-2.6L15 7"/></svg>
          <input type="file" multiple aria-label="Attach files">
        </label>
        <span class="mv-textarea-toolbar-spacer"></span>
        <button class="mv-button" data-size="icon" type="submit" data-ai-chat-send aria-label="Send message">
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 19V5M5 12l7-7 7 7"/></svg>
          <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6" y="6" width="12" height="12" rx="2"/></svg>
        </button>
      </div>
    </div>
    <p class="mv-ai-chat-hint"><kbd class="mv-kbd" data-size="sm">Enter</kbd> to send · <kbd class="mv-kbd" data-size="sm">Shift</kbd> + <kbd class="mv-kbd" data-size="sm">Enter</kbd> for a new line · Solen can make mistakes. Check important info.</p>
  </form>

  <script type="application/json">[
    { "role": "user", "content": "How do I build a Web Component that shows a counter?", "files": [{ "name": "counter-brief.pdf", "size": 184320 }] },
    { "role": "assistant", "content": "Here’s a minimal, dependency-free counter:\n\n```js\nclass MvCounter extends HTMLElement {\n  #count = 0;\n  connectedCallback() {\n    this.innerHTML = `<button type=\"button\">0</button>`;\n    this.querySelector(\"button\").addEventListener(\"click\", (e) => {\n      e.currentTarget.textContent = ++this.#count;\n    });\n  }\n}\ncustomElements.define(\"mv-counter\", MvCounter);\n```\n\nA few best practices:\n\n- prefix the tag name (`mv-`) to avoid collisions\n- clean up your listeners in `disconnectedCallback()`\n- expose state through **attributes** to stay compatible with every framework" }
  ]</script>
</mv-ai-chat>

API

Attributes

Name	Tipo	Padrão	Descrição
`label`	string	`Assistant`	Assistant name (accessible labels, announcements).
`model`	string		Current model; synced with a radio menu data-name="model" and passed to the responder.
`user-label`	string	`You`	Accessible name for the user’s messages.
`thinking-label`	string	`Thinking`	Text for the waiting state.
`data-state`	thinking \| streaming		Set while generating.
`data-empty`	boolean		Set when the conversation is empty.

Properties

Name	Tipo	Descrição
`responder`	(messages, { signal, model }) => AsyncIterable`<string>` \| Promise`<string>` \| string	Response source. Default: local simulation (canned English replies, no network). Honor signal for stopping.
`messages`	{ role, content, files? }[]	Reads/writes the history. Also settable via a child `<script type="application/json">`.
`busy`	boolean	Read-only: a response is in progress.
`strings`	Partial<Record<string, string>>	Overrides for the default text (en-US): conversation (log label, {label} placeholder), jumpToLatest (jump button), send / sendTitle and stop / stopTitle (send button label and tooltip), attachments (attachment list label), removeFile (chip remove button, {name}), sizeBytes / sizeKB / sizeMB (file size, {n}), code (caption of a fence without a language), copyCode, copyResponse, responseActions (action bar label), regenerate / regenerateTitle (regenerate button label and tooltip), stopped (stopped notice, also announced), error (reply shown when the responder fails), announceWriting ({label}), announceResponse ({label}, {text}), codeBlock (stands for code in that announcement), announceCopied. App-wide translations: setStrings() from core/i18n.js, under the key "ai-chat". Can be set before the element is defined.

Methods

Name	Descrição
`send(text)`	Sends a message (with pending attachments) and generates the response.
`stop()`	Stops generating (also Escape in the field, or the send button while it reads Stop).
`regenerate()`	Replaces the last response.
`reset()`	Clears the conversation.
`renderMarkdown(source, element, { partial, codeLabel, onCode })`	Export: lightweight, safe Markdown rendering (textContent only). partial: the source may end mid-token (streaming or stopped), so a dangling ** or backtick closes or hides and an open fence stays a code block. The chat uses it while streaming and for a stopped reply.

Events

Name	Descrição
`mv-send`	Cancelable. detail: { content, files }.
`mv-response`	Response finished. detail: { content, stopped }.
`mv-stop / mv-reset / mv-error`	Stop, reset, responder error (detail.error).

Content structure

Name	Descrição
`.mv-ai-chat-header`	Free-form header; [data-ai-chat-model-label] shows the selected model, [data-ai-chat-reset] clears the conversation.
`.mv-ai-chat-empty`	Empty state (hidden after the first message); any [data-prompt] sends its text.
`form.mv-ai-chat-composer`	Composer: textarea (Enter sends, Shift + Enter = new line), input[type=file], ul.mv-ai-chat-attachments, [data-ai-chat-send] button with two icons (send / stop).

CSS classes

Name	Descrição
`mv-ai-chat-log / -thread / -message / -content / -code / -actions`	Generated parts (message: data-role user \| assistant, data-pending).
`mv-ai-chat-suggestions / -suggestion / -empty-mark`	Suggestion grid and empty-state badge.
`mv-ai-chat-chip / -attach / -hint / -model / -menu-desc`	Attachment, file button, hint, model trigger and model description.

CSS variables

Name	Padrão	Descrição
`--mv-ai-chat-max-width`	`46rem`	Reading width of the thread and composer.
`--mv-ai-chat-user-bg`		Background of the user’s bubbles.

Accessibility

Thread with role=log (aria-busy while generating); each message is a named <article> (“You” / assistant name). Streaming isn’t read word by word: a role=status region announces “… is writing a reply”, then the final response (code is summarized). Send button: label toggles between Send / Stop. Focusable code blocks (horizontal scrolling by keyboard), named Copy / Regenerate buttons. Reduced motion: no typing animation or blinking caret.