# Artifact Panel

The side panel for what the agent made — code or a document — with versions, copy and download.

- Category: AI & Agents
- Page: https://wunderui.com/components/artifact-panel
- Tier: Core and Pro

## Install

Artifact Panel ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ArtifactPanel, ArtifactChip } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ArtifactPanel } from "@wunderui/react"

const source = "export function UsageSummary() {\n  return <p>1,842 requests</p>\n}"

export function Artifact() {
  return (
    <ArtifactPanel
      title="usage-summary.tsx"
      meta="Code · edited 2 min ago"
      code={source}
      onCopy={() => navigator.clipboard.writeText(source)}
    />
  )
}
```

Expected result: You should see a bordered panel with the title, the meta line and a copy button, and the code with line numbers below.

## When to use

### Use Artifact Panel for

- A file, component or draft that an agent made, next to the chat
- Showing the versions of something the agent changed over several turns
- Copying or downloading what the agent made

### Use something else

- [Code Block](https://wunderui.com/components/code-block) for a snippet inside a message, with its own copy button
- [Diff View](https://wunderui.com/components/diff-view) for the lines an edit tool call changed
- [Sheet](https://wunderui.com/components/sheet) for a panel that slides over the page and takes the focus until it is closed

## Keyboard

The header holds native buttons and one Segment, and the code view is a focusable region.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the version switch (one stop, on the selected version), `Copy`, `Download`, `Close panel` and then the code view. A document has no stop of its own; anything focusable in it is reached in order. |
| `←` or `→` | In the version switch: selects the previous or next version and calls `onVersionChange`. |
| `Home` or `End` | In the version switch: selects the first or last version. |
| `Enter` or `Space` | Presses the focused button: copy, download or close. |
| `↑` or `↓` | In the code view, which is focusable: scrolls it vertically; ← and → scroll long lines sideways. |

Escape does nothing: the panel is not a dialog and has no open state. Close it on Escape where you hold the open state.

## Behavior

What the panel does with content, versions, actions, height and assistive technology.

- **Not a dialog:** The panel is a plain section with no role, name or focus trap. Opening, closing, focus and Escape are yours, so give its wrapper a region role and a label for focus to land on.
- **Code or document:** Pass code for a view with line numbers, or children for a document; if both, code wins. An empty string counts as code, and there is no syntax colouring or wrapping.
- **Versions:** The switch shows for two or more versions. The panel never loads one: swap the code or content in your change handler, or the content stays while the highlight moves.
- **Actions:** Each button appears when its handler is passed. The panel never reads the clipboard, never makes a file and shows no feedback after a press.
- **Height and width:** The panel fills its container and grows with its content. Give it a height and the content scrolls inside while the header stays; there is no resize handle, so width is your layout's job.
- **Long titles and narrow widths:** The title is cut with an ellipsis. The header wraps, so on a narrow width the version switch and the actions move below the title.
- **No loading or error state:** The panel does not know an artifact is being written or has failed. Pass a status line with skeleton rows, or an alert, as content, and omit the handlers until the artifact exists.
- **Assistive technology:** The code view is a region named Code and its line numbers are hidden from assistive technology. The switch is named Version, the buttons Copy, Download and Close panel, and the title is plain text.
- **Motion:** The panel has no motion of its own. Icon buttons press with a small scale that is off under reduced motion, and the version switch changes at once.
- **Reduced motion:** There is nothing to reduce. If you animate opening and closing, follow your layout's motion rules and respect reduced motion.

## Anatomy

- `ArtifactPanel`: A bordered section with a 16 px radius, as wide as its container and as tall as its content unless you set a height. It has no role or name and is not a dialog.
- `Title and meta`: The title in 14 px semibold on one line, cut with an ellipsis, and an optional meta line in 12 px secondary text. The title is not a heading.
- `Version switch`: A small Segment named Version, shown when there are two or more versions. It reports the choice; swapping the content is up to you.
- `Actions`: Ghost icon buttons named Copy, Download and Close panel. Each shows only when you pass its handler.
- `Body`: With code: a monospace view with line numbers, no wrapping, focusable as a region named Code. Without code: your content in a padded column of 14 px secondary text.

## Best practices

### When to use

- Use it for something an agent made that a person keeps working with next to the chat: a file, a component, a draft. For a short snippet in a message use Code Block; for changed lines use Diff View.

### Do

- Hold the version in your code: pass the current version, the change handler and the matching code. Without them the switch moves its own highlight and shows the same content.
- Move focus into the panel when it opens and back to the opener when it closes, since the panel does neither. Make its wrapper a labelled region and close it on Escape.
- Answer copy and download yourself. The panel gives no feedback, so say Copied usage-summary.tsx in a status line, or say that the browser refused.
- Show loading and failure in the content (a status line with skeleton rows, or an alert with a retry) and leave out handlers that cannot work yet: a button without a handler is not drawn.
- Give the panel a height where it sits in a fixed column. The code view and a document then scroll inside while the header stays in place.

### Don't

- Don't put the panel in a dialog just to open it. It is a region beside the content, not a modal, and it does not trap focus.
- Don't expect Preview and Code tabs. Compose Tabs inside the panel, as the Examples tab does.
- Don't pass an empty string as code for a document that has not arrived. It draws one empty numbered line and ignores the content.

## API reference

### ArtifactPanel

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The name of the artifact, on one line in the header. Required. |
| children | React.ReactNode |  | The document, drawn in a padded column of 14 px secondary text when `code` is not set. |
| className | string |  | Extra classes for the panel, for example a width or a height such as `h-56`. |
| code | string |  | A string drawn as code with line numbers. Omit it and pass `children` for a document. `code` wins when both are passed. |
| meta | React.ReactNode |  | A second line under the title, for the kind and who edited it and when. |
| onClose | () => void |  | Draws the `Close panel` button. The panel does not unmount itself. |
| onCopy | () => void |  | Draws the `Copy` button. The panel copies nothing itself: write the clipboard here and say that it worked. |
| onDownload | () => void |  | Draws the `Download` button. The panel makes no file itself. |
| onVersionChange | (v: string) => void |  | Called with the name of the version the person chose. Swap `code` or the children here: the panel does not. |
| version | string |  | The selected version, for a controlled switch. Without it the switch keeps its own selection, starting on the last version. |
| versions | string[] | [] | The names of the versions, for example `["v1", "v2", "v3"]`. With two or more the header draws a version switch. Default: none. |

### ArtifactChip

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| className | string |  |  |
| kind | "document" \| "code" | "document" | Sets the icon and the tile colour: a written document or a piece of code. |
| meta | React.ReactNode |  | The line under the title, for example `Document · v2`. |
| onOpen | () => void |  |  |
| selected | boolean |  | The artifact the panel currently shows. |

## Examples

### Content: code, a document, or lines wider than the panel

### Actions: copy, download and close are each optional

### Versions: none, two or five

### Height: grows with its content or fills a box

### Artifact chip: the card in the chat that opens the panel

### Shadow

## In context

### Beside a chat: opens on a button, takes the focus, closes on Escape

The panel isn't a dialog, so it doesn't trap focus. Press the button and focus moves into the panel, and Escape or the close button closes it and returns focus to the button that opened it.

### Preview and code views, with copy and download that answer

The panel has no tabs of its own, so the views are Tabs inside it. Copy and download do something the eye can't see, so a status line under the panel says what happened, or that the browser refused.

### Generating, ready and failed: the children say it

The panel has no loading or error state. While the artifact is written it holds a status line and skeleton rows without actions, and if the run fails it holds an alert and a retry.

## For AI agents

`get_component("artifact-panel")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
