Artifact

kai-artifact

Shows a generated page, document, or file beside the conversation, with its code a click away.

• Shadow DOM
• Sandboxed iframe
• Preview + Code tabs
• Configurable toolbar
• 4 events

Preview

When to use

When a response produces something runnable or viewable you want beside the chat. Pair it with <kai-resizable> For a split-pane shell and give the parent a height.

Usage

Point src at your hosted artifact and set files in JavaScript (it’s an array, so it can’t be an HTML attribute) for the Code tab.

<kai-artifact src="https://your.app/artifacts/abc/index.html" style="display:block;height:520px"></kai-artifact>
<script type="module">
  import '@kitn.ai/ui/web-components';

  await customElements.whenDefined('kai-artifact');

  const el = document.querySelector('kai-artifact');
  el.files = [
    { path: 'index.html', url: '…/index.html', type: 'html', code: '<!DOCTYPE …>' },
    { path: 'styles.css', url: '…/styles.css', type: 'other', language: 'css', code: '…' },
  ];
  el.addEventListener('kai-navigate', (e) => console.log(e.detail.url));
</script>

• files — each entry needs a path; add url for the preview, code + language for the Code tab, and type (html | pdf | image | other). Folders come from the / in paths.
• Toolbar — hide any default control with its no-* flag (no-nav, no-reload, no-home, no-path-field, no-tabs); expandable and open-in-tab are opt-in.
• Sandbox defaults to allow-scripts allow-forms. Widen it only for trusted content.

Examples

Code view

Code

Preview only

Code

Open in new tab

Code

Standalone

Chrome for an artifact rendered outside a panel.

Code

Expandable

Code

Props

Property	Type	Default	Notes
theme	"light" | "dark" | "auto"	'auto'	Color mode (`auto` follows prefers-color-scheme).
src	string	—	URL the preview iframe frames. Consumer-controlled.
files	ArtifactCardFile[]	[]	Files for the Code tab tree, plus each file's preview `url`. JS property (array); omit for a preview-only artifact.
tab	"preview" | "code"	—	Controlled active tab: `preview` or `code`. When set, the artifact follows it (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`).
defaultTab	"preview" | "code"	—	Uncontrolled INITIAL tab, used only when `tab` is unset. Default `preview`.
activeFile	string	—	Selected file path. Syncs the tree highlight, Code source, and preview.
sandbox	string	'allow-scripts allow-forms'	iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`).
iframeTitle	string	—	Accessible title for the preview iframe.
maximized	boolean	false	Reflects the artifact's own maximized view-state (usually driven by the protocol).
expandable	boolean	false	Show the expand-to-fill button (OPT-IN).
openInTab	boolean	false	Show the open-in-new-tab button (OPT-IN).
noNav	boolean	false	Hide back/forward.
noReload	boolean	false	Hide reload.
noHome	boolean	false	Hide home.
noPathField	boolean	false	Hide the address field.
noTabs	boolean	false	Hide the Preview|Code toggle.
standalone	boolean	false	Standalone chrome: rounded corners + border (else square, borderless in-panel).
readonlyPath	boolean	false	Show the address but make it read-only (visible, nav-tracking, non-editable).
displayUrl	string	—	Friendly read-only address shown in the path field instead of the real url. Attribute: `display-url`.

Events

Event	Detail	Notes
kai-file-select	{ … }	Fired when a file is selected. `detail.path`.
kai-maximize-change	{ … }	Artifact's own maximize button toggled (consumer-observable; non-bubbling).
kai-maximize-intent	{ … }	The maximize PROTOCOL intent, as a raw bubbling + composed CustomEvent.
kai-navigate	{ … }	The preview navigated. `detail.url` is the raw new location.
kai-tab-change	{ … }	Fired when the Preview|Code tab changes. `detail.tab`.

Methods

Method	Signature	Notes
back	(): void	Go back in the artifact's own history stack (no-op when there's no prior entry).
forward	(): void	Go forward in the history stack (no-op when there's no forward entry).
reload	(): void	Force-reload the current preview url (also re-renders an inline PDF).
home	(): void	Navigate to the `src` home url (no-op when there's no `src`).
navigate	(url: string): void	Push + load a url in the preview, the path-field submit path (fires kai-navigate).
selectFile	(path: string): void	Select a file by path: highlights the tree, shows its source, navigates the preview (fires kai-file-select + kai-navigate). Named selectFile to avoid the `activeFile` prop.
openExternal	(): void	Open the current url in a new browser tab (no-op when there's no concrete url). Named openExternal, NOT openInTab, which is a prop (toolbar button visibility).
maximize	(): void	Enter the maximized view-state (fires kai-maximize-change{maximized:true}). Named maximize, NOT maximized, which is a prop.
restore	(): void	Exit the maximized view-state (fires kai-maximize-change{maximized:false}).

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

Artifact

---

Need a hand? Report a bug Ask for help