Vue Markdown Component with Streaming and Custom Components

Render Markdown in Vue 3 and Nuxt with the Markdown component: map elements to your own components, add plugins, and stream AI output as it arrives.

@comark/vue renders Markdown and Comark components in Vue 3 and Nuxt, with plugin support and streaming.

Installation

pnpm add @comark/vue

Nuxt

Add @comark/vue to the modules in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@comark/vue']
})

Nuxt auto-imports the <Markdown> and <MarkdownDocument> components and the defineMarkdownComponent() and defineMarkdownDocumentComponent() helpers, so you can skip their imports in the examples below. parseMarkdown() and createMarkdownParser() are auto-imported too, in your app and in server routes.

<Markdown>

<Markdown> parses and renders Markdown in one component.

<Markdown> is an async component and must be wrapped in <Suspense>.

For server-side rendering, use the MarkdownDocument component combined with parsing on the server instead.

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'

const content = `# Hello World

This is **markdown** with Comark components.
`
</script>

<template>
  <Suspense>
    <Markdown>{{ content }}</Markdown>
  </Suspense>
</template>

Usage

Pass Markdown content via the default slot or the value prop. value accepts a Markdown string or a pre-parsed MarkdownDocument:

<template>
  <Markdown>{{ content }}</Markdown>
</template>
Passing a document to <Markdown> skips parsing at runtime, but the parser is still bundled because Markdown imports it. To keep the client bundle free of the parser, use <MarkdownDocument> instead.

Props

PropTypeDefaultDescription
valuestring | MarkdownDocumentundefinedMarkdown string or pre-parsed document (alternative to default slot)
optionsParserOptions{}Parser options (autoUnwrap, autoClose, and others)
pluginsComarkPlugin[][]Array of plugins
unwrapboolean | string | string[]falseStrip wrapper tags (MDC unwrap). true unwraps <p>; a comma- or space-separated string or array peels tags sequentially, for example "ul li"
componentsRecord<string, Component>{}Custom Vue component mappings
componentsManifestComponentManifestundefinedDynamic component resolver
streamingbooleanfalseEnable streaming mode
summarybooleanfalseOnly render content before <!-- more -->
caretboolean | { class: string }falseAppend caret to last text node
dataRecord<string, unknown>{}Runtime values referenced from Markdown via :prop="data.path"
transformNodeNodeTransform | NodeTransform[]undefinedChange the tag or props of element nodes right before they render

options

See ParserOptions for available options.

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'
</script>

<template>
  <Markdown :options="{ autoUnwrap: true, autoClose: true }">
    {{ content }}
  </Markdown>
</template>

plugins

See ComarkPlugin for available plugins.

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import shiki from '@comark/vue/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'

const plugins = [
  shiki({
    themes: {
      light: githubLight,
      dark: githubDark
    }
  })
]
</script>

<template>
  <Suspense>
    <Markdown :plugins="plugins">{{ content }}</Markdown>
  </Suspense>
</template>

For the math and mermaid plugins, also pass the companion components:

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import math, { Math } from '@comark/vue/plugins/math'
import mermaid, { Mermaid } from '@comark/vue/plugins/mermaid'
import 'katex/dist/katex.min.css'
</script>

<template>
  <Suspense>
    <Markdown
      :value="markdown"
      :components="{ math: Math, mermaid: Mermaid }"
      :plugins="[math(), mermaid()]"
    />
  </Suspense>
</template>

components

Map custom Vue components to Comark elements in your Markdown.

Create a Vue component

Save a component such as components/Alert.vue:

components/Alert.vue
<script setup lang="ts">
defineProps<{
  type?: 'info' | 'warning' | 'error' | 'success'
}>()
</script>

<template>
  <div class="alert" :class="`alert-${type || 'info'}`" role="alert">
    <slot />
  </div>
</template>

Map the tag to your component

Pass the components prop to Markdown:

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import Alert from './components/Alert.vue'
import Card from './components/Card.vue'

const components = { alert: Alert, card: Card }
</script>

<template>
  <Markdown :components="components">{{ content }}</Markdown>
</template>
Components receive props from the Markdown and render children via slots.

Use it in your Markdown content

::alert{type="warning"}
This is a warning message!
::
See Component bindings for how props and slots map to your Vue component, or Component syntax for nested components, inline syntax, and attributes.

componentsManifest

Pass a function to load components on demand. Comark resolves each component once and caches it, in both <Markdown> and <MarkdownDocument>:

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'

const manifest = (name: string) => {
  return import(`./components/prose/${name}.vue`)
}
</script>

<template>
  <Markdown :components-manifest="manifest">{{ content }}</Markdown>
</template>

data

Expose runtime values to Markdown authors. Any prop written with a : prefix resolves against the render context { frontmatter, meta, data, props } when its value isn't valid JSON. See Data binding for details.

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'

const user = { name: 'Ada', role: 'admin' }
const content = `Hello, :badge{:label="data.user.name"}!`
</script>

<template>
  <Suspense>
    <Markdown :value="content" :data="{ user }" />
  </Suspense>
</template>

transformNode

Change an element's tag or props right before it renders, using values that are only known at render time. The function receives the node's tag, its resolved props, and the render context. It returns a new tag, new props, or nothing to keep the node as it is. See Transforming nodes before render for the full rules.

App.vue
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import type { NodeTransform } from '@comark/vue'

const user = { id: 42 }
const content = `::cta\nOpen your dashboard\n::`

const transformNode: NodeTransform = ({ tag, props }) => {
  if (tag !== 'cta') return
  return { tag: 'a', props: { ...props, href: `/users/${user.id}/dashboard` } }
}
</script>

<template>
  <Suspense>
    <Markdown :value="content" :transform-node="transformNode" />
  </Suspense>
</template>

Comark renders what the function returns as-is, without sanitizing it, and the security plugin doesn't apply to it. Validate anything you build from untrusted data, such as URLs from data.

Define the function once in <script setup>. A new array on every render makes the document render again.

defineMarkdownComponent

Creates a pre-configured <Markdown> component with default options, plugins, and components.

Usage

Expose your configured component

markdown.ts
import { defineMarkdownComponent } from '@comark/vue'
import shiki from '@comark/vue/plugins/shiki'
import math, { Math } from '@comark/vue/plugins/math'
import mermaid, { Mermaid } from '@comark/vue/plugins/mermaid'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import CustomAlert from './components/CustomAlert.vue'

export const AppMarkdown = defineMarkdownComponent({
  name: 'AppMarkdown',

  plugins: [
    math(),
    mermaid(),
    shiki({
      themes: {
        light: githubLight,
        dark: githubDark
      },
    }),
  ],

  components: {
    Math,
    Mermaid,
    alert: CustomAlert,
  },
})

Use it in your templates

App.vue
<script setup lang="ts">
import { AppMarkdown } from './markdown'
</script>

<template>
  <AppMarkdown>{{ content }}</AppMarkdown>

  <AppMarkdown :components="{ alert: DifferentAlert }">{{ content }}</AppMarkdown>
</template>

Options

OptionTypeDefaultDescription
extendsReturnType<typeof defineMarkdownComponent>undefinedInherit plugins and components from another component
namestringundefinedComponent name for debugging
autoUnwrapbooleantrueUnwrap single paragraph elements inside components
autoClosebooleantrueAuto-close incomplete Markdown syntax
linkifybooleantrueDeprecated. Use registerDefaultPlugins: false and register linkify() instead
registerDefaultPluginsbooleantrueRegister default plugins (linkify, frontmatter, html, alert, task-list, components, attributes)
pluginsComarkPlugin[][]Array of plugins
componentsRecord<string, Component>{}Custom Vue component mappings
transformNodeNodeTransform | NodeTransform[]undefinedNode transforms that run before the instance's own transformNode
classstringundefinedAdditional CSS classes for the wrapper div

extends

Inherit plugins and components from another component, then layer your own on top:

markdown.ts
import { defineMarkdownComponent } from '@comark/vue'
import shiki from '@comark/vue/plugins/shiki'
import githubLight from '@shikijs/themes/github-light'
import githubDark from '@shikijs/themes/github-dark'
import toc from '@comark/vue/plugins/toc'
import math, { Math } from '@comark/vue/plugins/math'
import ProsePre from './components/ProsePre.vue'

export const BaseMarkdown = defineMarkdownComponent({
  name: 'BaseMarkdown',
  plugins: [
    shiki({ themes: { light: githubLight, dark: githubDark } }),
  ],
  components: { ProsePre },
})

export const ArticleMarkdown = defineMarkdownComponent({
  name: 'ArticleMarkdown',
  extends: BaseMarkdown,
  plugins: [toc({ depth: 3 }), math()],
  components: { Math },
})

export const CommentMarkdown = defineMarkdownComponent({
  name: 'CommentMarkdown',
  extends: BaseMarkdown,
})

Merging behavior

  • plugins: Arrays are concatenated (config plugins + prop plugins)
  • components: Component mappings override global configuration
  • Other options: Component options override global configuration

<MarkdownDocument>

Renders a pre-parsed MarkdownDocument without any parsing. Use it when you parse on the server, in a build step, or via an API, so no parser or plugin code is shipped to the browser.

Parsing

Parse on the server

server.ts
import { createMarkdownParser } from 'comark'
import { readFile } from 'node:fs/promises'

const parse = createMarkdownParser()

export async function getContentDocument(slug: string) {
  const markdown = await readFile(`content/${slug}.md`, 'utf-8')
  return parse(markdown)
}

Render with MarkdownDocument

ContentPage.vue
<script setup lang="ts">
import { MarkdownDocument } from '@comark/vue'
import Alert from './components/Alert.vue'

const { slug } = defineProps<{ slug: string }>()

const res = await fetch(`/api/content/${slug}`)
const document = await res.json()
</script>

<template>
  <MarkdownDocument :value="document" :components="{ alert: Alert }" />
</template>

Renderer props

PropTypeDefaultDescription
valueMarkdownDocument-Required. The parsed document returned by parseMarkdown()
componentsRecord<string, Component>{}Custom Vue component mappings
componentsManifestComponentManifestundefinedDynamic component resolver for lazy-loaded components
streamingbooleanfalseEnable streaming mode
caretboolean | { class: string }falseAppend a blinking caret to the last text node
dataRecord<string, unknown>{}Runtime values referenced from Markdown via :prop="data.path"
transformNodeNodeTransform | NodeTransform[]undefinedChange the tag or props of element nodes right before they render

defineMarkdownDocumentComponent

Creates a pre-configured <MarkdownDocument> component with default component mappings.

Setup

Expose your configured renderer

markdown.ts
import { defineMarkdownDocumentComponent } from '@comark/vue'
import CustomAlert from './components/Alert.vue'
import ProsePre from './components/ProsePre.vue'

export const ArticleMarkdownDocument = defineMarkdownDocumentComponent({
  name: 'ArticleMarkdownDocument',
  components: {
    alert: CustomAlert,
    ProsePre,
  },
})

Use it in your templates

ArticlePage.vue
<script setup lang="ts">
import { ArticleMarkdownDocument } from './markdown'

const { slug } = defineProps<{ slug: string }>()

const res = await fetch(`/api/article/${slug}`)
const document = await res.json()
</script>

<template>
  <ArticleMarkdownDocument :value="document" />
</template>

Renderer options

OptionTypeDefaultDescription
extendsReturnType<typeof defineMarkdownDocumentComponent>undefinedInherit component mappings from another renderer
namestringundefinedComponent name for debugging
componentsRecord<string, Component>{}Custom Vue component mappings
transformNodeNodeTransform | NodeTransform[]undefinedNode transforms that run before the instance's own transformNode
classstringundefinedAdditional CSS classes for the wrapper div

Inheritance

Inherit component mappings from another renderer, then layer your own on top:

markdown.ts
import { defineMarkdownDocumentComponent } from '@comark/vue'
import ProsePre from './components/ProsePre.vue'
import ProseA from './components/ProseA.vue'
import CustomAlert from './components/Alert.vue'
import CommentAlert from './components/CommentAlert.vue'

const BaseMarkdownDocument = defineMarkdownDocumentComponent({
  name: 'BaseMarkdownDocument',
  components: { ProsePre, ProseA },
})

export const ArticleMarkdownDocument = defineMarkdownDocumentComponent({
  name: 'ArticleMarkdownDocument',
  extends: BaseMarkdownDocument,
  components: { alert: CustomAlert },
})

export const CommentMarkdownDocument = defineMarkdownDocumentComponent({
  name: 'CommentMarkdownDocument',
  extends: BaseMarkdownDocument,
  components: { alert: CommentAlert },
})

Live documents

MarkdownDocument can subscribe to an ambient context so external sources can update a mounted renderer, such as HMR, a collaboration socket, an agent, or devtools. The listen key comes from meta.key (set by a plugin) or the document-key prop. When globalThis.comarkContext exists, the renderer listens for updates on that key, re-renders on change, and unsubscribes on unmount. Without a context, the key is ignored.

<template>
  <MarkdownDocument document-key="page" :value="document" />
</template>

A driver installs the context once and pushes updates by key with set() to replace the whole document, or patch() to edit individual nodes with structural sharing so only the changed branch re-renders:

import { createComarkContext, parseMarkdown } from 'comark'

const ctx = createComarkContext() // installs globalThis.comarkContext
const doc = ctx.get('page', await parseMarkdown('# Hello')) // seed on first access

doc.set(await parseMarkdown('# Replaced'))
doc.patch({ op: 'insert', path: [1], node: ['p', {}, 'inserted'] })

A path indexes into document.nodes, where the first segment selects a top-level node and each later segment selects a child of that element. Patch operations include replace, insert, and remove (each taking a path), along with meta, frontmatter, and data merges. @comark/react, @comark/svelte, and @comark/angular share the same context API.


Component bindings

Comark maps component attributes and slots in Markdown to Vue props and slots.

Prop binding

Attributes in Comark syntax are passed as props to your component. Use the : prefix to pass typed values:

MarkdownProp value
{type="warning"}"warning" (string)
{:count="5"}5 (number)
{:active="true"}true (boolean)
{:config='{"key":"val"}'}{ key: 'val' } (object)

Named slots

Named slots in Comark (#slotname) map to Vue named slots:

  • Default slot → <slot />
  • Named slots → <slot name="slotname" /> (for example, #footer → <slot name="footer" />)
<script setup lang="ts">
defineProps<{
  title?: string
}>()
</script>

<template>
  <div class="card">
    <h3 v-if="title">{{ title }}</h3>
    <slot />
    <footer>
      <slot name="footer" />
    </footer>
  </div>
</template>

Overriding HTML elements

Override how native HTML elements render by mapping a component to their tag name via the components prop in both the Markdown and MarkdownDocument components.

Create overridden version

components/Heading.vue
<script setup lang="ts">
const props = defineProps<{
  __node?: ElementNode
  id?: string
}>()
</script>

<template>
  <component :is="__node?.[0] || 'h2'" :id="id" class="heading">
    <a v-if="id" :href="`#${id}`" class="anchor">#</a>
    <slot />
  </component>
</template>

Map

Pass the component to the components prop:

App.vue
<template>
  <Markdown :components="{ h1: Heading, h2: Heading, h3: Heading }">
    {{ content }}
  </Markdown>
</template>

Resolution order

Comark resolves each tag against Vue components in this order and stops at the first match:

  1. Prose{PascalTag}: for example, ProseH1 for h1. Follows the Nuxt Content prose component convention.
  2. {PascalTag}: for example, Alert for alert. PascalCase version of the tag name.
  3. {tag}: for example, alert. Exact tag name as-is.
  4. Global: any component registered via app.component().

If none match, the tag renders as a native HTML element.


Nuxt UI integration

When @nuxt/ui is installed, Comark renders Markdown elements with Nuxt UI's prose components. In Nuxt, the module enables them by default.

Vite setup

Enable prose components by setting prose: true in the Nuxt UI Vite plugin:

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prose: true
    })
  ]
})

CSS setup

src/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

Streaming

Render Markdown incrementally as chunks arrive from an AI stream or live preview.

Setup

Set streaming to true while content is being received, then false when done:

components/AiChat.vue
<script setup lang="ts">
import { ref } from 'vue'
import { Markdown } from '@comark/vue'

const content = ref('')
const isStreaming = ref(false)

async function askAI(prompt: string) {
  content.value = ''
  isStreaming.value = true

  const response = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ prompt }),
  })

  const reader = response.body!.getReader()
  const decoder = new TextDecoder()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    content.value += decoder.decode(value, { stream: true })
  }

  isStreaming.value = false
}
</script>

<template>
  <Markdown :streaming="isStreaming" caret>
    {{ content }}
  </Markdown>
</template>
autoClose is enabled by default and closes incomplete syntax such as **bold text on every parse. Disable it with :options="{ autoClose: false }".

Caret

The caret prop appends a blinking cursor to the last text node while streaming is true:

App.vue
<!-- Default caret -->
<Markdown :streaming="isStreaming" caret>{{ content }}</Markdown>

<!-- Custom caret class -->
<Markdown :streaming="isStreaming" :caret="{ class: 'my-caret' }">{{ content }}</Markdown>
.my-caret {
  display: inline-block;
  width: 2px;
  height: 1em;
  background: currentColor;
  animation: blink 1s step-end infinite;
  vertical-align: text-bottom;
}

@keyframes blink {
  50% { opacity: 0; }
}

TypeScript support

Use ComarkPlugin from comark to type plugin arrays, and ElementNode to type the __node prop in components that override HTML elements:

ComarkWrapper.vue
<script setup lang="ts">
import type { Component } from 'vue'
import type { ComarkPlugin } from 'comark'
import { Markdown } from '@comark/vue'

interface Props {
  content: string
  components?: Record<string, Component>
  plugins?: ComarkPlugin[]
}

const props = defineProps<Props>()
</script>

<template>
  <Suspense>
    <Markdown :components="props.components" :plugins="props.plugins">
      {{ props.content }}
    </Markdown>
  </Suspense>
</template>
components/Heading.vue
<script setup lang="ts">
import type { ElementNode } from 'comark'

defineProps<{
  __node?: ElementNode
  id?: string
}>()
</script>

© 2026 Vercel, Inc.