danny-avila · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026 · chatgpt-codex-connector · Oct 12, 2026
diff --git a/content/docs/features/artifacts.mdx b/content/docs/features/artifacts.mdx
@@ -15,9 +15,11 @@ Artifacts let LibreChat Agents render generated React components, HTML, SVG, Mar
 
 The available modes are:
 
-- **Normal**: Injects LibreChat's standard instructions for React, HTML, SVG, Markdown, and Mermaid artifacts.
-- **shadcn/ui**: Adds shadcn/ui component-library guidance for more polished generated interfaces.
-- **Custom**: Keeps artifact rendering enabled but injects no built-in instructions. Put the complete artifact behavior you want in the agent's instructions.
+- **Normal**: Injects LibreChat's standard instructions for React, HTML, SVG, Markdown, and Mermaid artifacts: when to create one, the artifact syntax, and the rules for each type.
+- **shadcn/ui**: Injects the standard instructions plus usage documentation for the bundled shadcn/ui components, for more polished generated interfaces.
+- **Custom**: Keeps artifact rendering enabled but injects no built-in instructions. The agent's instructions must teach the model the artifact syntax; see [Custom Instructions](#custom-instructions).
+
+The shadcn/ui components are available to React artifacts in every mode. The shadcn/ui mode only adds their documentation to the prompt.
 
 Agent-level configuration is preferred because each agent can use the mode and instructions appropriate to its purpose. The administrator can hide Artifacts by removing the `artifacts` [agent capability](/docs/configuration/librechat_yaml/object_structure/agents#capabilities).
 
@@ -33,6 +35,103 @@ Agent-level configuration is preferred because each agent can use the mode and i
 - Iterative updates through follow-up messages
 - Any model available to the configured agent
 
+## Custom Instructions
+
+In **Custom** mode, LibreChat sends the model no artifact instructions at all. It still renders any artifact the model writes in the format below, so the agent's instructions have to describe that format. Without it, the model answers in plain Markdown and no artifact appears.
+
+Custom mode is useful when you want to:
+
+- **Apply a house style**: your own rules for when to create an artifact, design conventions, or examples from your domain.
+- **Spend fewer tokens**: the Normal instructions add about 2,700 tokens to every request and the shadcn/ui instructions about 6,000. A focused custom prompt can be a fraction of that.
+- **Restrict output**: allow only the types your users need, such as Markdown reports or Mermaid diagrams.
+
+If you only want artifacts to work, use **Normal**. Its instructions are maintained alongside the renderer.
+
+### Artifact Syntax
+
+Each artifact is a `:::artifact` directive wrapping a single fenced code block:
+
+`````md
+:::artifact{identifier="quarterly-report" type="text/markdown" title="Quarterly Report"}
+````
+# Quarterly Report
+
+Revenue grew 12% over the previous quarter.
+````
+:::
+`````
+
+- `identifier`: a kebab-case ID. Reuse it when revising an artifact. Two artifacts in the same message need a different identifier, type, or title.
+- `type`: one of the [supported types](#supported-types).
+- `title`: shown on the artifact card and used as the download name.
+- Put the opening `:::artifact{...}` line and the closing `:::` on their own lines.
+- Put the complete content inside one fenced block. Content outside a fence is parsed as Markdown first and loses its formatting.
+- Make the fence longer than any fence inside the content: four backticks by default, five if the content contains a four-backtick fence, and so on.
+
+### Supported Types
+
+| Type                      | Renders as                | Requirements                                                                                                                                       |
+| ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text/html`               | A single web page         | One file with inline CSS and JavaScript. The built-in prompt allows external scripts only from `https://cdnjs.cloudflare.com`.                      |
+| `image/svg+xml`           | An SVG image              | Set a `viewBox`. The preview stretches the root `<svg>` to fill the panel, so a fixed `width` and `height` do not size it.                          |
+| `text/markdown`           | A rendered document       | Standard Markdown, including tables. `text/md` is also accepted.                                                                                   |
+| `application/vnd.mermaid` | A Mermaid diagram         | Mermaid source only, without surrounding Markdown.                                                                                                 |
+| `application/vnd.react`   | An interactive React page | A component as the default export that renders without props. See [React Artifacts](#react-artifacts).                                             |
+
+The short names `html`, `svg`, `markdown`, `md`, `mermaid`, and `react` are accepted too, in any letter case. These are the types intended for model-authored artifacts; a type the renderer does not recognize is previewed as HTML.
+
+LibreChat does not serve placeholder images. The `/api/placeholder/400/320` URL used in the built-in prompt resolves inside the preview sandbox and does not return an image, so ask for inline SVG or CSS placeholders instead. Images from reachable HTTPS URLs still load.
+
+### React Artifacts
+
+React artifacts run in a Sandpack `react-ts` sandbox with React 18. The component is mounted as `<App />`, so it must be the default export and have no required props. TypeScript is allowed.
+
+These imports are available:
+
+- `react` and `react-dom`
+- `lucide-react` (0.394), `recharts` (2.12), `three` (0.167), `date-fns` (3.x), and `react-day-picker` (9.x)
+- `react-router-dom`, `clsx`, `class-variance-authority`, `tailwind-merge`, `tailwindcss-animate`, `embla-carousel-react`, `vaul`, `dat.gui`, and the Radix UI primitives the shadcn/ui components are built on
+- shadcn/ui components from `/components/ui/<name>`, for example `import { Button } from '/components/ui/button'`, and the `cn` helper from `/lib/utils`
+
+Import shadcn/ui components from `/components/ui/<name>`, not `@/components/ui/<name>` or `/components/<name>`. The available names are `accordion`, `alert`, `alert-dialog`, `avatar`, `badge`, `breadcrumb`, `button`, `calendar`, `card`, `carousel`, `checkbox`, `collapsible`, `dialog`, `drawer`, `dropdown-menu`, `input`, `label`, `menubar`, `navigation-menu`, `pagination`, `popover`, `progress`, `radio-group`, `select`, `separator`, `skeleton`, `slider`, `switch`, `table`, `tabs`, `textarea`, `toast`, `toaster`, `toggle`, `toggle-group`, `tooltip`, and `use-toast`.
+
+No other packages are installed, and an import outside this list fails to build. The minimal template below names only the libraries the built-in prompt allows; add any of the other installed packages if your agent needs them.
+
+Style React artifacts with Tailwind CSS 3.4, which the preview loads from the Tailwind Play CDN. The built-in prompt forbids arbitrary values such as `h-[600px]`. The Play CDN compiles them, so whether to keep that rule is up to you.
+
+### Minimal Template
+
+Paste this into the agent's instructions and remove the types you don't need:
+
+`````md
+## Artifacts
+
+You can create artifacts: substantial, self-contained content (roughly 15+ lines) that the user is likely to reuse or iterate on, shown in a panel beside the chat. Answer inline for short snippets, explanations, and one-off questions. Create at most one artifact per message unless asked for more.
+
+Write each artifact exactly like this, with the directive lines on their own lines and the complete content in one fenced block:
+
+:::artifact{identifier="kebab-case-id" type="TYPE" title="Short Title"}
+````
+complete content
+````
+:::
+
+- Reuse the identifier when updating an artifact, and always resend the complete content. Never leave placeholders or write "rest unchanged".
+- Use a backtick fence longer than any fence inside the content (four backticks by default).
+
+Allowed types:
+
+- "text/html": one self-contained page with inline CSS and JavaScript. Load external scripts only from https://cdnjs.cloudflare.com.
+- "image/svg+xml": an SVG with a viewBox instead of a fixed width and height.
+- "text/markdown": a Markdown document.
+- "application/vnd.mermaid": Mermaid diagram source only.
+- "application/vnd.react": a React component as the default export, with no required props.
+  - Style it with Tailwind utility classes.
+  - Import only from react, lucide-react, recharts, three, date-fns, react-day-picker, and shadcn/ui components at "/components/ui/<name>" (for example `import { Button } from "/components/ui/button"`). Do not import any other library.
+
+Draw placeholder images with inline SVG or CSS instead of placeholder-service URLs. If a request can't meet these rules, use a regular code block instead of an artifact.
+`````
+
 ## Preview and Export
 
 Use the fullscreen control in a rendered artifact preview to expand it to the complete browser display. The control follows browser Fullscreen API state, exits normally with Escape or browser controls, and is hidden when fullscreen is unavailable.