Artifact Renderer

Code

<ArtifactRenderer  artifact={{ kind: "table", title: "Overdue invoices", columns: [{ key: "n", label: "No." }, { key: "amt", label: "Amount", align: "end" }], rows: [{ n: "INV-1", amt: 1200 }] }}  onAction={(id, artifact) => run(id)}  onPick={(values, artifact) => choose(values)}/>;

AI Assistant · beta

Live examples and controls: Artifact Renderer in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/artifact-renderer.json

An agent answers with data, not markup. You hand its JSON to ArtifactRenderer, it checks the shape, and renders a Nasaq component. Anything it does not understand becomes a small warning instead of a crash or an injection.

When to useCopy Anchor Link

• Agent or copilot output that should be a table, chart, card, picker or set of buttons instead of prose.
• Answers that contain fenced ```artifact blocks, which extractArtifacts pulls out.

When not to useCopy Anchor Link

• Plain answers: render Markdown with Markdown.
• UI you author yourself. Use the real components directly.

ImportCopy Anchor Link

import { ArtifactRenderer, ArtifactList, extractArtifacts } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

<ArtifactRenderer
  artifact={{ kind: "table", title: "Overdue invoices", columns: [{ key: "n", label: "No." }, { key: "amt", label: "Amount", align: "end" }], rows: [{ n: "INV-1", amt: 1200 }] }}
  onAction={(id, artifact) => run(id)}
  onPick={(values, artifact) => choose(values)}
/>;

Answer with blocks in it:

const { text, artifacts } = extractArtifacts(answer);
<Markdown>{text}</Markdown>
<ArtifactList artifacts={artifacts} />

KindsCopy Anchor Link

Text fields take a string or { en, ar }. The older title_en and title_ar keys are accepted.

APICopy Anchor Link

parseArtifact(input) returns { ok: true, artifact } or { ok: false, error, kind? } and never throws.

SafetyCopy Anchor Link

• The renderer builds React elements from validated data. It never uses dangerouslySetInnerHTML.
• Limits apply: 200 rows, 20 columns, 8 series, 200 points, 50 options, 8 actions.
• Colours must be var(--token). Hex values, url() and expressions are dropped.
• Series keys are remapped before they become CSS variable names, so a key cannot inject CSS.
• Markdown and card bodies go through Markdown, which drops raw HTML.
• A tone shows as a dot with the tone named for screen readers ("Critical: …"), so it never relies on colour alone.
• html is shown as a code block unless allowHtml is set. Then it goes in <iframe sandbox="" srcDoc>: no scripts, no same-origin access, no forms, and a Content Security Policy that blocks network. Only enable it for output you would show in a preview, and never give the frame allow-same-origin.
• Links open with rel="noopener noreferrer". Only http, https and mailto are followed.

AccessibilityCopy Anchor Link

• Tables are real tables with header cells. Charts have a text title and a legend.
• Picker uses a radio group or checkboxes with the option label and description associated.
• Action confirmation is a focus-trapping dialog. A sent picker announces "Sent".

RTL and i18nCopy Anchor Link

• Labels come from useOptionalNasaq() and the { en, ar } fields pick by locale.
• Table alignment uses start and end. Charts flip the x axis in RTL via the chart primitives.
• Numbers use the locale digits through Num.

Styling and tokensCopy Anchor Link

Everything is a Nasaq component, so tokens are inherited. Series colours default to the --nq-chart-* palette.

Do / Don'tCopy Anchor Link

• Do validate on every render path. ArtifactRenderer does it for you.
• Do keep allowHtml off unless a sandboxed preview is the point.
• Don't pass model output to ArtifactView without parseArtifact.
• Don't add a kind that runs code.

RelatedCopy Anchor Link

Markdown, CodeBlock, CopilotChat, AgentSteps.