Artifact

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add artifact

Usage#

Anatomy#

Two pieces that share a status. The card lives in the thread: an icon tile, a title over a short description, the version and an Open action. The pane lives beside it: a header with the title, the version stepper, the Preview / Code switch and the actions, over a content sheet that holds the preview, the code, the empty state or the skeleton.

import {
  ArtifactCard,
  ArtifactCardIcon,
  ArtifactCardHeading,
  ArtifactCardTitle,
  ArtifactCardDescription,
  ArtifactCardVersion,
  ArtifactCardStatus,
  ArtifactCardAction,
  Artifact,
  ArtifactHeader,
  ArtifactTitle,
  ArtifactVersion,
  ArtifactTabs,
  ArtifactActions,
  ArtifactAction,
  ArtifactCopy,
  ArtifactContent,
  ArtifactPreview,
  ArtifactCode,
  ArtifactEmpty,
  ArtifactSkeleton,
} from "@/components/ui/artifact"

<ArtifactCard>
  <ArtifactCardIcon />
  <ArtifactCardHeading>
    <ArtifactCardTitle />
    <ArtifactCardDescription />
  </ArtifactCardHeading>
  <ArtifactCardStatus />
  <ArtifactCardVersion />
  <ArtifactCardAction />
</ArtifactCard>

<Artifact>
  <ArtifactHeader>
    <ArtifactTitle />
    <ArtifactVersion />
    <ArtifactTabs />
    <ArtifactActions>
      <ArtifactCopy />
      <ArtifactAction />
    </ArtifactActions>
  </ArtifactHeader>
  <ArtifactContent>
    <ArtifactSkeleton />
    <ArtifactPreview />
    <ArtifactCode />
    <ArtifactEmpty />
  </ArtifactContent>
</Artifact>

Card states#

Four states, and they all live where your eye already is. The icon tile cross-fades to a spinner while the agent works and to a warning when it gives up. While generating, the title sweeps and the description holds a shimmer bar in its own footprint, so the card does not grow when the words arrive. While updating, the version chip opens to v3 → v4: the number you know stays put and only the new one is added.

Play the lifecycle once to see the hand-offs: generating, ready, updating, then ready on the next version.

Types#

type picks the glyph and the fallback description: document, code, app, chart or image. Pass your own glyph as the icon's children for anything else.

Card to pane#

The card and the pane share nothing but your state, which keeps them free to live in different trees: the card inside a message, the pane in a split, a sheet or an AI Panel. Hold one open flag and one status per artifact. The card's action sets it, the pane's close clears it, and open on the card keeps it lifted while its pane is showing so you can tell which card the pane belongs to. Send a change from the composer below: the card switches to updating, the pane dims and sweeps its title, then follows to the new version on its own.

import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

export function PricingCard() {
  return (
    <div className="flex flex-col gap-4 rounded-xl p-5 ring-1 ring-edge">
      <div className="flex items-center justify-between">
        <p className="font-medium">Pro</p>
      </div>
      <p className="text-3xl font-semibold">$24<span>/month</span></p>
      <p className="text-sm text-muted-foreground">$288 billed yearly</p>
      <ul className="flex flex-col gap-2 text-sm">
        <li>Every Pro component</li>
        <li>Figma kit</li>
        <li>Priority support</li>
      </ul>
      <Button className="w-full">Start free trial</Button>
    </div>
  )
}

Version stepping#

Each request makes a version, and earlier ones stay one step away. Stepping back slides the content right, stepping forward slides it left, and the number in the read-out rolls the same way, so you always know which direction you went. Pass history and the read-out opens a menu of every version with a line about what changed.

Preview and code#

Add ArtifactTabs and the preview and the code become two views of one sheet. Leave it out and whichever parts you render simply show, so a document needs no tabs at all. For a live app, pass src to the preview and it renders a sandboxed iframe that fades in once it has loaded.

import { Button } from "@/components/ui/button"
import { InputField, InputRoot } from "@/components/ui/input"

export function WaitlistForm() {
  return (
    <form className="flex w-full max-w-sm flex-col gap-3">
      <p className="font-medium">Join the Koala beta</p>
      <InputRoot>
        <InputField type="email" placeholder="you@company.com" />
      </InputRoot>
      <Button type="submit">Request access</Button>
    </form>
  )
}

Empty and building#

Before anything exists, ArtifactEmpty tells the reader what the pane is for. While the first version is generating, ArtifactSkeleton takes the sheet with shimmer lines in the shape of a page; the preview and code wait for ready, so you can leave all three in the markup and let the status decide.

In an AI Panel#

Inside an AI Panel the panel is already the frame, so use variant="plain": the tint goes and the header sits on the body's own inset, while the content keeps its sheet so the result still reads as one object. Give it a height and it scrolls inside, under the panel's composer.

API reference#

FAQ#