Controls

The controls configuration allows you to enable or disable interactive controls for various markdown elements, including tables, code blocks, images, and Mermaid diagrams.

controls

• Type: boolean | ControlsConfig
• Default: true (all controls enabled by default)

Configuration for interactive controls. Set to false to disable all controls, or configure specific control types. When configuring specific controls, you only need to specify the options you want to customize - other controls will remain enabled by default.

Interface

type ControlsConfig
  = | boolean
    | {
      table?: boolean | TableControlsConfig
      code?: boolean | CodeControlsConfig
      image?: boolean | ImageControlsConfig
      mermaid?: boolean | ZoomControlsConfig
    }

table

• Type: boolean | TableControlsConfig
• Default: true (all table controls enabled)

Controls for tables. Can be a boolean or an object with specific options.

Interface

type TableControlsConfig
  = | boolean
    | {
      copy?: boolean | string
      download?: boolean | string
    }

copy

• Type: boolean | string | undefined
• Default: true

Enable copy button for tables. When set to true, the default label is used. When set to a string, that string is used as the button label.

Only copy button enabled:

Name	Age	City
Alice	30	New York
Bob	25	London
Charlie	35	Tokyo

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  table: {
    copy: true,
    download: false,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

download

• Type: boolean | string | undefined
• Default: true

Enable download button for tables. When set to true, the default label is used. When set to a string, that string is used as the button label. The download button allows users to download the table as CSV, TSV, or Markdown format.

Only download button enabled:

Name	Age	City
Alice	30	New York
Bob	25	London
Charlie	35	Tokyo

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  table: {
    copy: false,
    download: true,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

code

• Type: boolean | CodeControlsConfig
• Default: true (all code controls enabled)

Controls for code blocks. Can be a boolean or an object with specific options.

Interface

type CodeControlsConfig
  = | boolean
    | {
      collapse?: boolean
      copy?: boolean
      download?: boolean
      fullscreen?: boolean
    }

collapse

• Type: boolean | undefined
• Default: true

Enable collapse/expand functionality for code blocks. When enabled, users can collapse long code blocks to save space.

Only collapse button enabled:

typescript

function greet(name: string): string {
  return `Hello, ${name}!`;
}
const message = greet('World');
console.log(message);

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  code: {
    collapse: true,
    copy: false,
    download: false,
    fullscreen: false,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

copy

• Type: boolean | undefined
• Default: true

Enable copy button for code blocks. When enabled, users can copy the code content to their clipboard.

Only copy button enabled:

typescript

function greet(name: string): string {
  return `Hello, ${name}!`;
}
const message = greet('World');
console.log(message);

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  code: {
    collapse: false,
    copy: true,
    download: false,
    fullscreen: false,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

download

• Type: boolean | undefined
• Default: true

Enable download button for code blocks. When enabled, users can download the code as a file. For Mermaid diagrams, additional options (SVG, PNG) are available.

Only download button enabled:

typescript

function greet(name: string): string {
  return `Hello, ${name}!`;
}
const message = greet('World');
console.log(message);

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  code: {
    collapse: false,
    copy: false,
    download: true,
    fullscreen: false,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

fullscreen

• Type: boolean | undefined
• Default: true

Enable fullscreen mode for code blocks. When enabled, users can view code blocks in a fullscreen modal for better readability.

Only fullscreen button enabled:

typescript

function greet(name: string): string {
  return `Hello, ${name}!`;
}
const message = greet('World');
console.log(message);

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  code: {
    collapse: false,
    copy: false,
    download: false,
    fullscreen: true,
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

image

• Type: boolean | ImageControlsConfig
• Default: true (image controls enabled)

Controls for images. Can be a boolean or an object with specific options.

Note: The preview control enables clicking on the image to open it in preview mode (zoomed/fullscreen). The download control appears when hovering over the image. Other controls (carousel, flip, rotate, and controlPosition) are only displayed when the image is opened in preview mode (zoomed/fullscreen).

Interface

type ImageControlsConfig
  = | boolean
    | {
      preview?: boolean
      download?: boolean
      carousel?: boolean
      flip?: boolean
      rotate?: boolean
      controlPosition?: ZoomControlPosition
    }

preview

• Type: boolean | undefined
• Default: true

Enable preview functionality for images. When enabled, users can click on the image to open it in preview mode.

download

• Type: boolean | undefined
• Default: true

Enable download button for images. When enabled, a download button appears when hovering over the image, allowing users to download the image file. The download button is also displayed when the image is opened in preview mode (zoomed/fullscreen).

Only download button enabled:

Placeholder Image

carousel

• Type: boolean | undefined
• Default: true

Enable carousel functionality for images. When enabled and there are multiple images in the document, users can navigate between images using previous/next buttons when the image is opened in preview mode (zoomed/fullscreen). The carousel buttons are only displayed when there are multiple images in the document.

Only carousel control enabled:

Placeholder Image

Placeholder Image

flip

• Type: boolean | undefined
• Default: true

Enable flip functionality for images. When enabled, users can flip the image horizontally or vertically. This control is only displayed when the image is opened in preview mode (zoomed/fullscreen).

Only flip control enabled:

Placeholder Image

rotate

• Type: boolean | undefined
• Default: true

Enable rotate functionality for images. When enabled, users can rotate the image in 90-degree increments. This control is only displayed when the image is opened in preview mode (zoomed/fullscreen).

Only rotate control enabled:

Placeholder Image

controlPosition

• Type: ZoomControlPosition | undefined
• Default: 'bottom-center'

Position of the control buttons for images in preview mode. The control buttons include download, carousel, flip, rotate, and zoom controls.

Image with controls at top-right:

Placeholder Image

mermaid

• Type: boolean | ZoomControlsConfig
• Default: true (zoom controls enabled)

Controls for Mermaid diagrams. Can be a boolean or an object with zoom options.

Interface

type ZoomControlsConfig
  = | boolean
    | {
      position?: ZoomControlPosition
    }

position

• Type: ZoomControlPosition | undefined
• Default: 'bottom-right'

Position of the zoom control button for Mermaid diagrams. The zoom controls allow users to zoom in, zoom out, and reset the zoom level of Mermaid diagrams.

Mermaid with zoom controls at top-left:

mermaid

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  mermaid: {
    position: 'top-left',
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

Mermaid with zoom controls at top-right:

mermaid

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  mermaid: {
    position: 'top-right',
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

Mermaid with zoom controls at bottom-left:

mermaid

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

<script setup lang="ts">
import type { ControlsConfig } from 'vue-stream-markdown'
import { Markdown } from 'vue-stream-markdown'

const controls: ControlsConfig = {
  mermaid: {
    position: 'bottom-left',
  },
}
</script>

<template>
  <Markdown :content="content" :controls="controls" />
</template>

Disabling All Controls

To disable all controls, set controls to false:

<template>
  <Markdown :content="content" :controls="false" />
</template>

Events

The Markdown component emits events that allow you to customize user interactions and provide enhanced user experiences.

copied

• Type: (content: string) => void
• Triggered when: User copies content from a table or code block

The copied event is emitted when a user successfully copies content using the copy button. This event provides the copied content as a parameter, allowing you to implement custom interactions such as displaying custom notifications, tracking analytics, or integrating with other parts of your application.

Example:

<script setup lang="ts">
import { Markdown } from 'vue-stream-markdown'

const content = `
\`\`\`typescript
function greet(name: string): string {
  return \`Hello, \${name}!\`;
}
\`\`\`

| Name | Age |
|------|-----|
| Alice | 30  |
| Bob   | 25  |
`

function handleCopied(copiedContent: string) {
  // Custom interaction logic
  console.log('Content copied:', copiedContent)

  // Example: Show custom notification
  // toast.success('Content copied to clipboard!')

  // Example: Track analytics
  // analytics.track('content_copied', { length: copiedContent.length })
}
</script>

<template>
  <Markdown :content="content" @copied="handleCopied" />
</template>