Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(design-system): add Markdown component to ui-patterns (#46325)

Francesco Sansalvadoree79f0d1dd12f
diff --git a/apps/design-system/__registry__/index.tsx b/apps/design-system/__registry__/index.tsx
index 9d5f52779c0..5fd983a108f 100644
--- a/apps/design-system/__registry__/index.tsx
+++ b/apps/design-system/__registry__/index.tsx
@@ -3195,6 +3195,160 @@ export const Index: Record<string, any> = {
subcategory: "undefined",
chunks: []
},
+ "markdown-full-example": {
+ name: "markdown-full-example",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-full-example")),
+ source: "",
+ files: ["registry/default/example/markdown-full-example.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-customization": {
+ name: "markdown-customization",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-customization")),
+ source: "",
+ files: ["registry/default/example/markdown-customization.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-headings": {
+ name: "markdown-headings",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-headings")),
+ source: "",
+ files: ["registry/default/example/markdown-headings.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-paragraphs": {
+ name: "markdown-paragraphs",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-paragraphs")),
+ source: "",
+ files: ["registry/default/example/markdown-paragraphs.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-lists": {
+ name: "markdown-lists",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-lists")),
+ source: "",
+ files: ["registry/default/example/markdown-lists.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-links": {
+ name: "markdown-links",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-links")),
+ source: "",
+ files: ["registry/default/example/markdown-links.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-inline-code": {
+ name: "markdown-inline-code",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-inline-code")),
+ source: "",
+ files: ["registry/default/example/markdown-inline-code.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-blockquotes": {
+ name: "markdown-blockquotes",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-blockquotes")),
+ source: "",
+ files: ["registry/default/example/markdown-blockquotes.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-code-blocks": {
+ name: "markdown-code-blocks",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-code-blocks")),
+ source: "",
+ files: ["registry/default/example/markdown-code-blocks.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-tables": {
+ name: "markdown-tables",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-tables")),
+ source: "",
+ files: ["registry/default/example/markdown-tables.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-images": {
+ name: "markdown-images",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-images")),
+ source: "",
+ files: ["registry/default/example/markdown-images.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-horizontal-rules": {
+ name: "markdown-horizontal-rules",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-horizontal-rules")),
+ source: "",
+ files: ["registry/default/example/markdown-horizontal-rules.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-quote-component": {
+ name: "markdown-quote-component",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-quote-component")),
+ source: "",
+ files: ["registry/default/example/markdown-quote-component.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
+ "markdown-avatar-component": {
+ name: "markdown-avatar-component",
+ type: "components:example",
+ registryDependencies: ["markdown"],
+ component: React.lazy(() => import("@/registry/default/example/markdown-avatar-component")),
+ source: "",
+ files: ["registry/default/example/markdown-avatar-component.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
"status-code-demo": {
name: "status-code-demo",
type: "components:example",
diff --git a/apps/design-system/components/error-codes.tsx b/apps/design-system/components/error-codes.tsx
new file mode 100644
index 00000000000..758128ef1e5
--- /dev/null
+++ b/apps/design-system/components/error-codes.tsx
@@ -0,0 +1,56 @@
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from 'ui'
+
+// Demo ErrorCodes component — mirrors the real `<ErrorCodes service="..." />` used in
+// apps/docs MDX files (e.g. apps/docs/content/guides/auth/debugging/error-codes.mdx).
+interface ErrorCodesProps {
+ service?: string
+}
+
+const ERROR_CODES: Record<string, Array<{ code: string; description: string }>> = {
+ auth: [
+ { code: 'invalid_credentials', description: 'Invalid email or password provided' },
+ { code: 'session_not_found', description: 'User session not found or has expired' },
+ { code: 'weak_password', description: 'Password does not meet strength requirements' },
+ { code: 'email_not_confirmed', description: 'Email address has not been verified' },
+ { code: 'mfa_required', description: 'Multi-factor authentication is required' },
+ ],
+ database: [
+ { code: 'connection_timeout', description: 'Database connection timeout after 30 seconds' },
+ { code: 'query_failed', description: 'Query execution failed due to syntax error' },
+ { code: 'permission_denied', description: 'User does not have permission for this operation' },
+ { code: 'row_level_security', description: 'Row-level security policy blocked the request' },
+ ],
+ realtime: [
+ { code: 'SUBSCRIPTION_JOINED', description: 'Client successfully subscribed to a channel' },
+ { code: 'SUBSCRIPTION_LEFT', description: 'Client left a subscribed channel' },
+ { code: 'MESSAGE_BROADCAST', description: 'Broadcast message received on channel' },
+ { code: 'PRESENCE_STATE', description: 'Presence state synchronized' },
+ ],
+}
+
+export const ErrorCodes = ({ service = 'auth' }: ErrorCodesProps) => {
+ const errorCodes = ERROR_CODES[service] || ERROR_CODES.auth
+
+ return (
+ <div className="my-6 w-full overflow-y-auto">
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead className="font-semibold">Error Code</TableHead>
+ <TableHead className="font-semibold">Description</TableHead>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {errorCodes.map((item) => (
+ <TableRow key={item.code} className="even:bg-surface-75/75">
+ <TableCell>
+ <code className="text-sm font-mono">{item.code}</code>
+ </TableCell>
+ <TableCell>{item.description}</TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </div>
+ )
+}
diff --git a/apps/design-system/config/docs.ts b/apps/design-system/config/docs.ts
index 748ccee8bfc..bfb6de81579 100644
--- a/apps/design-system/config/docs.ts
+++ b/apps/design-system/config/docs.ts
@@ -86,13 +86,18 @@ export const docsConfig: DocsConfig = {
items: [],
},
{
- href: '/docs/ui-patterns/modality',
+ title: 'Markdown',
+ href: '/docs/ui-patterns/markdown',
+ items: [],
+ },
+ {
title: 'Modality',
+ href: '/docs/ui-patterns/modality',
items: [],
},
{
- href: '/docs/ui-patterns/navigation',
title: 'Navigation',
+ href: '/docs/ui-patterns/navigation',
items: [],
},
{
diff --git a/apps/design-system/content/docs/ui-patterns/introduction.mdx b/apps/design-system/content/docs/ui-patterns/introduction.mdx
index b0fe4b736dc..59dc6599381 100644
--- a/apps/design-system/content/docs/ui-patterns/introduction.mdx
+++ b/apps/design-system/content/docs/ui-patterns/introduction.mdx
@@ -11,6 +11,7 @@ These patterns help ensure consistency across Supabase products by establishing
- **[Empty States](empty-states)**: Communicating the absence of data and guiding users toward meaningful actions.
- **[Forms](forms)**: Building cohesive form experiences in both page layouts and side panels.
- **[Layout](layout)**: Creating consistent page structures with proper spacing, max-widths, and content organization.
+- **[Markdown](markdown)**: Rendering composable markdown content with defaults
- **[Navigation](navigation)**: Organizing complex hierarchical navigation systems across multiple products and contexts.
UI patterns may incorporate external libraries (such as `react-markdown`, `reactflow`, `recharts`, etc) or compose various components from the `ui` package. They serve as blueprints for solving recurring design problems, ensuring that similar features across the application follow the same structural and interaction patterns.
diff --git a/apps/design-system/content/docs/ui-patterns/markdown.mdx b/apps/design-system/content/docs/ui-patterns/markdown.mdx
new file mode 100644
index 00000000000..0b6e4a0d8b0
--- /dev/null
+++ b/apps/design-system/content/docs/ui-patterns/markdown.mdx
@@ -0,0 +1,110 @@
+---
+title: Markdown
+description: Composable Markdown renderer
+---
+
+A composable `react-markdown` component with defaults for all standard markdown elements (headings, paragraphs, lists, blockquotes, links, images, tables, code). Customize any element via the `components` prop and import optional components such as Quote or Avatar.
+All components are lazy-loaded.
+
+<ComponentPreview name="markdown-full-example" peekCode />
+
+## API
+
+| Prop | Type | Default | Description |
+| --------------- | --------------------- | ------------- | ---------------------------------------------------------------------- |
+| `children` | `string` | - | Markdown content to render |
+| `content` | `string` | `''` | **Deprecated**: Use `children` instead |
+| `codeBlock` | `boolean` | `false` | Enable syntax highlighting for code blocks (lazy-loaded via CodeBlock) |
+| `components` | `Partial<Components>` | - | Override or add specific markdown elements |
+| `className` | `string` | - | CSS class for the wrapper div |
+| `remarkPlugins` | `PluggableList` | `[remarkGfm]` | Additional remark plugins (GFM is included by default) |
+
+All other `react-markdown` options are supported via spread props.
+
+## Customization
+
+Override any element or add new ones via the `components` prop.
+
+<ComponentPreview name="markdown-customization" peekCode />
+
+## Primitive Components
+
+```tsx
+import {
+ Anchor,
+ Avatar,
+ Blockquote,
+ Code,
+ CodeBlockPre,
+ DefaultPre,
+ H1,
+ H2,
+ H3,
+ H4,
+ H5,
+ H6,
+ Hr,
+ Img,
+ InlineCode,
+ ListItem,
+ OrderedList,
+ Paragraph,
+ Quote,
+ SimplePre,
+ Table,
+ Td,
+ Th,
+ Tr,
+ UnorderedList,
+} from 'ui-patterns/Markdown'
+```
+
+### Headings
+
+<ComponentPreview name="markdown-headings" />
+
+### Paragraphs
+
+<ComponentPreview name="markdown-paragraphs" />
+
+### Lists
+
+<ComponentPreview name="markdown-lists" />
+
+### Links
+
+<ComponentPreview name="markdown-links" />
+
+### Inline Code
+
+<ComponentPreview name="markdown-inline-code" />
+
+### Blockquotes
+
+<ComponentPreview name="markdown-blockquotes" />
+
+### Code Blocks
+
+<ComponentPreview name="markdown-code-blocks" />
+
+### Tables
+
+<ComponentPreview name="markdown-tables" />
+
+### Images
+
+<ComponentPreview name="markdown-images" />
+
+### Horizontal Rules
+
+<ComponentPreview name="markdown-horizontal-rules" />
+
+## Optional Components
+
+### Quote
+
+<ComponentPreview name="markdown-quote-component" peekCode />
+
+### Avatar
+
+<ComponentPreview name="markdown-avatar-component" peekCode />
diff --git a/apps/design-system/lib/remark-jsx-components.ts b/apps/design-system/lib/remark-jsx-components.ts
new file mode 100644
index 00000000000..d54e3c5e019
--- /dev/null
+++ b/apps/design-system/lib/remark-jsx-components.ts
@@ -0,0 +1,33 @@
+import { visit } from 'unist-util-visit'
+
+// Matches self-closing JSX-like elements with PascalCase component names:
+// <ComponentName />
+// <ComponentName service="auth" />
+const JSX_SELF_CLOSING = /^<([A-Z]\w*)((?:\s+[\w-]+(?:="[^"]*")?)*)\s*\/>$/
+const ATTR_PATTERN = /([\w-]+)(?:="([^"]*)")?/g
+
+/**
+ * Remark plugin that converts JSX-like self-closing tags (e.g. `<ErrorCodes service="auth" />`)
+ * in markdown into nodes that react-markdown maps to entries in the `components` prop —
+ * giving the ui-patterns `Markdown` component MDX-like behavior in design-system demos.
+ */
+export const remarkJsxComponents = () => (tree: any) => {
+ visit(tree, 'html', (node: any, index: number | undefined, parent: any) => {
+ if (!parent || index === undefined) return
+ const match = node.value.trim().match(JSX_SELF_CLOSING)
+ if (!match) return
+
+ const [, name, attrsStr] = match
+ const properties: Record<string, string | boolean> = {}
+ ATTR_PATTERN.lastIndex = 0
+ let attrMatch: RegExpExecArray | null
+ while ((attrMatch = ATTR_PATTERN.exec(attrsStr || '')) !== null) {
+ properties[attrMatch[1]] = attrMatch[2] !== undefined ? attrMatch[2] : true
+ }
+
+ parent.children[index] = {
+ type: 'jsxComponent',
+ data: { hName: name, hProperties: properties },
+ }
+ })
+}
diff --git a/apps/design-system/registry/default/example/markdown-avatar-component.tsx b/apps/design-system/registry/default/example/markdown-avatar-component.tsx
new file mode 100644
index 00000000000..f223fd3c0c6
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-avatar-component.tsx
@@ -0,0 +1,11 @@
+import { Avatar } from 'ui-patterns/Markdown'
+
+export default function MarkdownAvatarComponentDemo() {
+ return (
+ <Avatar
+ src="https://avatars.githubusercontent.com/u/54469796?s=200&v=4"
+ alt="Supabase"
+ caption="Supabase Team"
+ />
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-blockquotes.tsx b/apps/design-system/registry/default/example/markdown-blockquotes.tsx
new file mode 100644
index 00000000000..9eb474cec9e
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-blockquotes.tsx
@@ -0,0 +1,10 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownBlockquotesDemo() {
+ return (
+ <Markdown>{`> This is a blockquote with important information.
+
+> Blockquotes can span multiple lines and are useful for
+> emphasizing key points or highlighting quotes.`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-code-blocks.tsx b/apps/design-system/registry/default/example/markdown-code-blocks.tsx
new file mode 100644
index 00000000000..f61d25e5342
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-code-blocks.tsx
@@ -0,0 +1,15 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownCodeBlocksDemo() {
+ return (
+ <Markdown codeBlock>{`\`\`\`javascript
+const greeting = 'Hello, World!'
+console.log(greeting)
+\`\`\`
+
+\`\`\`python
+def hello_world():
+ print("Hello, World!")
+\`\`\``}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-customization.tsx b/apps/design-system/registry/default/example/markdown-customization.tsx
new file mode 100644
index 00000000000..b1183300b93
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-customization.tsx
@@ -0,0 +1,20 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+import { ErrorCodes } from '@/components/error-codes'
+import { remarkJsxComponents } from '@/lib/remark-jsx-components'
+
+export default function MarkdownCustomization() {
+ return (
+ <Markdown
+ remarkPlugins={[remarkJsxComponents]}
+ components={{
+ ErrorCodes,
+ }}
+ >
+ {`## Auth error codes
+
+<ErrorCodes service="auth" />
+`}
+ </Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-full-example.tsx b/apps/design-system/registry/default/example/markdown-full-example.tsx
new file mode 100644
index 00000000000..9915e8efebc
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-full-example.tsx
@@ -0,0 +1,51 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownFullExample() {
+ const content = `# Main Heading
+
+This is a paragraph with some **bold text**, *italic text*, and \`inline code\`.
+
+## Subheading
+
+You can use [links](https://supabase.com) in your content.
+
+### Code Example
+
+\`\`\`javascript
+const greeting = 'Hello, Markdown!'
+console.log(greeting)
+\`\`\`
+
+### Lists
+
+**Unordered list:**
+- First item
+- Second item
+ - Nested item
+ - Another nested item
+- Third item
+
+**Ordered list:**
+1. First step
+2. Second step
+3. Third step
+
+### Blockquote
+
+> This is a blockquote. It can span multiple lines and is useful for emphasizing important information or highlighting quotes.
+
+### Horizontal Rule
+
+---
+
+### Table
+
+| Feature | Support | Status |
+|---------|---------|--------|
+| Headings | h1–h6 | ✓ |
+| Lists | Unordered & Ordered | ✓ |
+| Code | Inline & Blocks | ✓ |
+| Tables | GitHub Flavored | ✓ |`
+
+ return <Markdown codeBlock>{content}</Markdown>
+}
diff --git a/apps/design-system/registry/default/example/markdown-headings.tsx b/apps/design-system/registry/default/example/markdown-headings.tsx
new file mode 100644
index 00000000000..e46d235aa9f
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-headings.tsx
@@ -0,0 +1,11 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownHeadingsDemo() {
+ return (
+ <Markdown>{`# H1 Heading
+
+## H2 Heading
+
+### H3 Heading`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-horizontal-rules.tsx b/apps/design-system/registry/default/example/markdown-horizontal-rules.tsx
new file mode 100644
index 00000000000..9285d1a5932
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-horizontal-rules.tsx
@@ -0,0 +1,11 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownHorizontalRulesDemo() {
+ return (
+ <Markdown>{`Content before
+
+---
+
+Content after`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-images.tsx b/apps/design-system/registry/default/example/markdown-images.tsx
new file mode 100644
index 00000000000..8b0f64d2be6
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-images.tsx
@@ -0,0 +1,9 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownImagesDemo() {
+ return (
+ <Markdown>{`![Supabase Logo](https://avatars.githubusercontent.com/u/54469796?s=200&v=4)
+
+Image with alt text for accessibility.`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-inline-code.tsx b/apps/design-system/registry/default/example/markdown-inline-code.tsx
new file mode 100644
index 00000000000..29c2b21a84b
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-inline-code.tsx
@@ -0,0 +1,11 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownInlineCodeDemo() {
+ return (
+ <Markdown>{`Use the \`useState\` hook for state management.
+
+The \`useEffect\` hook runs side effects after render.
+
+Functions like \`map()\`, \`filter()\`, and \`reduce()\` are common.`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-links.tsx b/apps/design-system/registry/default/example/markdown-links.tsx
new file mode 100644
index 00000000000..71284e46bba
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-links.tsx
@@ -0,0 +1,9 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownLinksDemo() {
+ return (
+ <Markdown>{`This is a [link to Supabase](https://supabase.com) in the middle of text.
+
+You can also have [multiple links](https://github.com) in one [paragraph](https://docs.supabase.com).`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-lists.tsx b/apps/design-system/registry/default/example/markdown-lists.tsx
new file mode 100644
index 00000000000..aceaa3c2073
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-lists.tsx
@@ -0,0 +1,14 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownListsDemo() {
+ return (
+ <Markdown>{`**Unordered list:**
+- Item 1
+- Item 2
+ - Nested item
+
+**Ordered list:**
+1. First step
+2. Second step`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-paragraphs.tsx b/apps/design-system/registry/default/example/markdown-paragraphs.tsx
new file mode 100644
index 00000000000..38ed2821da1
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-paragraphs.tsx
@@ -0,0 +1,11 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownParagraphsDemo() {
+ return (
+ <Markdown>{`First paragraph with text.
+
+Second paragraph with **bold** and *italic* text.
+
+Third paragraph for spacing demonstration.`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-quote-component.tsx b/apps/design-system/registry/default/example/markdown-quote-component.tsx
new file mode 100644
index 00000000000..7f1a47fc4cd
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-quote-component.tsx
@@ -0,0 +1,22 @@
+import { Markdown, Quote } from 'ui-patterns/Markdown'
+
+export default function MarkdownQuoteComponentDemo() {
+ const content = `> This is a powerful insight that deserves emphasis with attribution.`
+
+ return (
+ <Markdown
+ components={{
+ blockquote: (props) => (
+ <Quote
+ attribution="Jane Doe"
+ src="https://avatars.githubusercontent.com/u/54469796?s=200&v=4"
+ caption="Co-founder at Supabase"
+ {...props}
+ />
+ ),
+ }}
+ >
+ {content}
+ </Markdown>
+ )
+}
diff --git a/apps/design-system/registry/default/example/markdown-tables.tsx b/apps/design-system/registry/default/example/markdown-tables.tsx
new file mode 100644
index 00000000000..4693cb80625
--- /dev/null
+++ b/apps/design-system/registry/default/example/markdown-tables.tsx
@@ -0,0 +1,12 @@
+import { Markdown } from 'ui-patterns/Markdown'
+
+export default function MarkdownTablesDemo() {
+ return (
+ <Markdown>{`| Feature | Support | Status |
+|---------|---------|--------|
+| Headings | h1–h6 | ✓ |
+| Lists | Unordered & Ordered | ✓ |
+| Code | Inline & Blocks | ✓ |
+| Tables | GitHub Flavored | ✓ |`}</Markdown>
+ )
+}
diff --git a/apps/design-system/registry/examples.ts b/apps/design-system/registry/examples.ts
index 85097c15a08..596c4fbb5a0 100644
--- a/apps/design-system/registry/examples.ts
+++ b/apps/design-system/registry/examples.ts
@@ -1708,6 +1708,90 @@ export const examples: Registry = [
registryDependencies: ['mermaid'],
files: ['example/mermaid-basic.tsx'],
},
+ {
+ name: 'markdown-full-example',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-full-example.tsx'],
+ },
+ {
+ name: 'markdown-customization',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-customization.tsx'],
+ },
+ {
+ name: 'markdown-headings',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-headings.tsx'],
+ },
+ {
+ name: 'markdown-paragraphs',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-paragraphs.tsx'],
+ },
+ {
+ name: 'markdown-lists',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-lists.tsx'],
+ },
+ {
+ name: 'markdown-links',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-links.tsx'],
+ },
+ {
+ name: 'markdown-inline-code',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-inline-code.tsx'],
+ },
+ {
+ name: 'markdown-blockquotes',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-blockquotes.tsx'],
+ },
+ {
+ name: 'markdown-code-blocks',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-code-blocks.tsx'],
+ },
+ {
+ name: 'markdown-tables',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-tables.tsx'],
+ },
+ {
+ name: 'markdown-images',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-images.tsx'],
+ },
+ {
+ name: 'markdown-horizontal-rules',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-horizontal-rules.tsx'],
+ },
+ {
+ name: 'markdown-quote-component',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-quote-component.tsx'],
+ },
+ {
+ name: 'markdown-avatar-component',
+ type: 'components:example',
+ registryDependencies: ['markdown'],
+ files: ['example/markdown-avatar-component.tsx'],
+ },
{
name: 'status-code-demo',
type: 'components:example',
diff --git a/packages/ui-patterns/src/Markdown/components.tsx b/packages/ui-patterns/src/Markdown/components.tsx
new file mode 100644
index 00000000000..659ee6d61cf
--- /dev/null
+++ b/packages/ui-patterns/src/Markdown/components.tsx
@@ -0,0 +1,246 @@
+'use client'
+
+import dynamic from 'next/dynamic'
+import React, { isValidElement, type HTMLAttributes } from 'react'
+import { cn } from 'ui'
+import { type CodeBlockLang } from 'ui-patterns/CodeBlock'
+
+const DynamicCodeBlock = dynamic(() =>
+ import('../CodeBlock').then((m) => ({ default: m.CodeBlock }))
+)
+
+export const H1 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h1 className={cn('font-heading mt-2 scroll-m-20 text-4xl font-bold', className)} {...props} />
+)
+
+export const H2 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h2
+ className={cn(
+ 'font-heading mt-12 scroll-m-20 border-b pb-2 text-2xl font-semibold tracking-tight first:mt-0',
+ className
+ )}
+ {...props}
+ />
+)
+
+export const H3 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h3
+ className={cn('font-heading mt-8 scroll-m-20 text-xl font-semibold tracking-tight', className)}
+ {...props}
+ />
+)
+
+export const H4 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h4
+ className={cn('font-heading mt-8 scroll-m-20 text-lg font-semibold tracking-tight', className)}
+ {...props}
+ />
+)
+
+export const H5 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h5
+ className={cn('mt-8 scroll-m-20 text-lg font-semibold tracking-tight', className)}
+ {...props}
+ />
+)
+
+export const H6 = ({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) => (
+ <h6
+ className={cn('mt-8 scroll-m-20 text-base font-semibold tracking-tight', className)}
+ {...props}
+ />
+)
+
+export const Paragraph = ({ className, ...props }: HTMLAttributes<HTMLParagraphElement>) => (
+ <p className={cn('leading-7 [&:not(:first-child)]:mt-6 text-foreground', className)} {...props} />
+)
+
+export const InlineCode = ({ className, ...props }: HTMLAttributes<HTMLElement>) => (
+ <code className={cn('text-code-inline', className)} {...props} />
+)
+
+export const Anchor = ({
+ href,
+ className,
+ ...props
+}: HTMLAttributes<HTMLAnchorElement> & { href?: string }) => (
+ <a
+ href={href ?? '#'}
+ className={cn(
+ 'underline decoration-1 decoration-foreground-muted underline-offset-4 transition-colors hover:decoration-foreground hover:decoration-2',
+ className
+ )}
+ {...props}
+ />
+)
+
+export const UnorderedList = ({ className, ...props }: HTMLAttributes<HTMLUListElement>) => (
+ <ul className={cn('my-6 ml-6 list-disc text-foreground', className)} {...props} />
+)
+
+export const OrderedList = ({ className, ...props }: HTMLAttributes<HTMLOListElement>) => (
+ <ol className={cn('my-6 ml-6 list-decimal text-foreground', className)} {...props} />
+)
+
+export const ListItem = ({ className, ...props }: HTMLAttributes<HTMLLIElement>) => (
+ <li className={cn('mt-2', className)} {...props} />
+)
+
+export const Blockquote = ({ className, ...props }: HTMLAttributes<HTMLElement>) => (
+ <blockquote
+ className={cn('mt-4 border-l-2 pl-6 italic text-foreground-light', className)}
+ {...props}
+ />
+)
+
+export const Hr = ({ ...props }: HTMLAttributes<HTMLHRElement>) => (
+ <hr className="my-4 md:my-8" {...props} />
+)
+
+export const Img = ({
+ className,
+ alt = '',
+ ...props
+}: HTMLAttributes<HTMLImageElement> & { alt?: string }) => (
+ // eslint-disable-next-line @next/next/no-img-element
+ <img className={cn('rounded-md border', className)} alt={alt} {...props} />
+)
+
+export const Table = ({ className, ...props }: HTMLAttributes<HTMLTableElement>) => (
+ <div className="my-6 w-full overflow-y-auto">
+ <table className={cn('w-full', className)} {...props} />
+ </div>
+)
+
+export const Tr = ({ className, ...props }: HTMLAttributes<HTMLTableRowElement>) => (
+ <tr className={cn('m-0 border-t p-0 even:bg-surface-75/75', className)} {...props} />
+)
+
+export const Th = ({ className, ...props }: HTMLAttributes<HTMLTableCellElement>) => (
+ <th
+ className={cn(
+ 'border px-4 py-2 text-left font-normal [[align=center]]:text-center [[align=right]]:text-right',
+ className
+ )}
+ {...props}
+ />
+)
+
+export const Td = ({ className, ...props }: HTMLAttributes<HTMLTableCellElement>) => (
+ <td
+ className={cn(
+ 'border text-foreground-light px-4 py-2 text-left [[align=center]]:text-center [[align=right]]:text-right',
+ className
+ )}
+ {...props}
+ />
+)
+
+export const SimplePre = ({ className, ...props }: HTMLAttributes<HTMLPreElement>) => (
+ <pre
+ className={cn(
+ 'my-4 overflow-x-auto rounded-lg border bg-surface-75 py-4 px-4 text-sm text-foreground-light',
+ className
+ )}
+ {...props}
+ />
+)
+
+export const Code = ({
+ className,
+ children,
+}: {
+ className?: string
+ children?: React.ReactNode
+}) => {
+ // Code blocks have language-xxx class, pass through for pre handler to extract
+ if (className?.startsWith('language-')) {
+ return <code className={className}>{children}</code>
+ }
+ return <InlineCode>{children}</InlineCode>
+}
+
+export const DefaultPre = ({ children, ...props }: HTMLAttributes<HTMLPreElement>) => (
+ <SimplePre {...props}>{children}</SimplePre>
+)
+
+export const CodeBlockPre = ({ children, ...props }: HTMLAttributes<HTMLPreElement>) => {
+ // Find the code element inside pre
+ const codeElement = React.Children.toArray(children).find(
+ (child) => isValidElement(child) && child.type === 'code'
+ )
+
+ if (!isValidElement(codeElement)) {
+ return <SimplePre {...props}>{children}</SimplePre>
+ }
+
+ const { className, children: code } = codeElement.props as {
+ className?: string
+ children: string
+ }
+ const language = className?.replace('language-', '') as CodeBlockLang
+ const content = typeof code === 'string' ? code.trimEnd() : ''
+
+ if (!language || !content) {
+ return <SimplePre {...props}>{children}</SimplePre>
+ }
+
+ return (
+ <DynamicCodeBlock
+ value={content}
+ language={language}
+ hideLineNumbers={false}
+ className="my-4"
+ />
+ )
+}
+
+export const Avatar = ({
+ src,
+ alt = 'Avatar',
+ caption,
+}: {
+ src: string
+ alt?: string
+ caption?: string
+}) => (
+ <div className={cn('align-center m-0 flex items-center gap-3')}>
+ <img src={src} alt={alt} className="h-8 w-8 rounded-full object-cover m-0" />
+ {caption && (
+ <figcaption className="text-foreground-lighter font-normal not-italic text-sm m-0">
+ {caption}
+ </figcaption>
+ )}
+ </div>
+)
+
+export const Quote = ({
+ children,
+ attribution,
+ src,
+ alt,
+ caption,
+ className,
+ ...props
+}: HTMLAttributes<HTMLQuoteElement> & {
+ attribution?: string
+ src?: string
+ alt?: string
+ caption?: string
+}) => (
+ <blockquote
+ className={cn(
+ 'mt-4 border-l-2 pl-6 italic text-foreground-light [&>p]:my-0 [&>p:not(:last-child)]:mb-4',
+ className
+ )}
+ {...props}
+ >
+ {children}
+ {attribution && (
+ <div className="mt-4 not-italic text-sm text-foreground">
+ <div className="font-semibold">— {attribution}</div>
+ {src && caption && <Avatar src={src} alt={alt} caption={caption} />}
+ </div>
+ )}
+ </blockquote>
+)
diff --git a/packages/ui-patterns/src/Markdown/index.tsx b/packages/ui-patterns/src/Markdown/index.tsx
index 3994fabf275..eb527583ffa 100644
--- a/packages/ui-patterns/src/Markdown/index.tsx
+++ b/packages/ui-patterns/src/Markdown/index.tsx
@@ -1,20 +1,130 @@
'use client'
-import Image from 'next/image'
+import React from 'react'
+import ReactMarkdown, { type Components, type Options } from 'react-markdown'
+import remarkGfm from 'remark-gfm'
import { cn } from 'ui'
-import { CodeBlock } from 'ui-patterns/CodeBlock'
+import { Heading } from 'ui/src/components/CustomHTMLElements'
+
+import {
+ Anchor,
+ Avatar,
+ Blockquote,
+ Code,
+ CodeBlockPre,
+ DefaultPre,
+ H1,
+ H2,
+ H3,
+ H4,
+ H5,
+ H6,
+ Hr,
+ Img,
+ InlineCode,
+ ListItem,
+ OrderedList,
+ Paragraph,
+ Quote,
+ SimplePre,
+ Table,
+ Td,
+ Th,
+ Tr,
+ UnorderedList,
+} from './components'
+
+const defaultComponents: Components = {
+ h1: (props) => <Heading tag="h1" {...props} />,
+ h2: (props) => <Heading tag="h2" {...props} />,
+ h3: (props) => <Heading tag="h3" {...props} />,
+ h4: (props) => <Heading tag="h4" {...props} />,
+ h5: (props) => <Heading tag="h5" {...props} />,
+ h6: (props) => <Heading tag="h6" {...props} />,
+ p: Paragraph,
+ a: Anchor,
+ code: Code,
+ img: Img,
+ ul: UnorderedList,
+ ol: OrderedList,
+ li: ListItem,
+ blockquote: Blockquote,
+ hr: Hr,
+ pre: DefaultPre,
+ table: Table,
+ tr: Tr,
+ th: Th,
+ td: Td,
+}
+
+interface MarkdownProps extends Omit<Options, 'children' | 'node' | 'components'> {
+ children?: string
+ className?: string
+ codeBlock?: boolean
+ /** @deprecated Use children instead */
+ content?: string
+ components?: Partial<Components> & Record<string, React.ComponentType<any>>
+}
+
+export function Markdown({
+ children,
+ content = '',
+ codeBlock = false,
+ components,
+ className,
+ remarkPlugins,
+ ...props
+}: MarkdownProps) {
+ // Allow opting into code block syntax highlighting
+ const mergedComponents = {
+ ...defaultComponents,
+ ...(codeBlock && { pre: CodeBlockPre }),
+ ...components,
+ }
-const NextImageHandler = (props: any) => {
return (
- <span className={cn('next-image--dynamic-fill', props.className)}>
- <Image {...props} className={['rounded-md border'].join(' ')} layout="fill" />
- </span>
+ <div className={cn('text-sm', className)}>
+ <ReactMarkdown
+ remarkPlugins={[remarkGfm, ...(remarkPlugins ?? [])]}
+ components={mergedComponents}
+ {...props}
+ >
+ {children ?? content}
+ </ReactMarkdown>
+ </div>
)
}
export const markdownComponents = {
mono: (props: any) => <code className="text-sm">{props.children}</code>,
- code: (props: any) => <CodeBlock {...props} />,
- img: (props: any) => NextImageHandler(props),
- Image: (props: any) => NextImageHandler(props),
+ code: Code,
+ img: Img,
+}
+
+export {
+ Anchor,
+ Avatar,
+ Blockquote,
+ Code,
+ CodeBlockPre,
+ DefaultPre,
+ H1,
+ H2,
+ H3,
+ H4,
+ H5,
+ H6,
+ Hr,
+ Img,
+ InlineCode,
+ ListItem,
+ OrderedList,
+ Paragraph,
+ Quote,
+ SimplePre,
+ Table,
+ Td,
+ Th,
+ Tr,
+ UnorderedList,
}