@dev_owl/cliveedit

CliveEdit

A themeable WYSIWYG markdown editor component for Vue 3, built with TypeScript.

CliveEdit gives your users a rich editing experience with a familiar toolbar while keeping markdown as the canonical data format. Switch between visual and raw markdown modes, undo/redo with full history, and adapt the look to any design system using CSS custom properties.

🚀 Try the Demo

Table of Contents

• Installation
• Quick Start
• MarkdownViewer (Read-only)
  • MarkdownViewer Props
  • Borderless Example
  • Code Block Copy Button
• Props
• Events
• v-model Bindings
• Exposed Methods
• Keyboard Shortcuts
• Auto-Formatting Shortcuts
• Toolbar
  • Default Toolbar Items
  • Custom Toolbar
    • ToolbarItem Interface
• Syntax Highlighting
  • Installation
  • Basic Usage
  • How It Works
  • Theming the Language Label
• Emoji Picker
  • Installation
  • Basic Usage
  • Options
  • How It Works
• Image Paste & Drop
  • Default Behaviour (Base64)
  • Visual Resize Controls
  • Custom Upload Handler
  • Size Limit
• Tables
  • Inserting a Table
  • Table Controls
  • Table Keyboard Navigation
• Theming
  • CSS Custom Properties
  • Dark Theme Example
• Vue Plugin (Global Registration)
• Advanced Usage
  • EditorContext (Provide / Inject)
    • EditorContext Interface
  • useHistory Composable
  • useEditor Composable
  • useHighlighter Composable
  • useEmojiPicker Composable
• TypeScript
• Build Scripts
• Browser Support
• License

Installation

npm install @dev_owl/cliveedit

Peer dependency: Vue 3.3 or higher.

npm install vue@^3.5

Quick Start

<template>
  <CliveEdit v-model="content" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CliveEdit } from '@dev_owl/cliveedit'
import '@dev_owl/cliveedit/style.css'

const content = ref('# Hello World\n\nStart writing **markdown** here.')
</script>

That's it. The editor renders a toolbar and a WYSIWYG editing area. The content ref always contains the raw markdown string.

MarkdownViewer (Read-only)

Need to display markdown without editing? Use the MarkdownViewer component:

<template>
  <MarkdownViewer v-model="content" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MarkdownViewer } from '@dev_owl/cliveedit'
import '@dev_owl/cliveedit/style.css'

const content = ref('# Hello World\n\nThis is **read-only** markdown.')
</script>

The viewer renders markdown to styled HTML using the same theming system as the editor. Links are clickable by default.

MarkdownViewer Props

Borderless Example

<MarkdownViewer v-model="content" :bordered="false" />

Code Block Copy Button

Every code block in the viewer carries a copy button that puts the block's content on the clipboard. It appears when the block is hovered or focused, confirms the copy for a moment, and is always visible on touch devices. Keyboard users reach it by tabbing to it.

This is a viewer-only feature — the editor never shows it, so it can't be confused with editable content.

<!-- On by default -->
<MarkdownViewer v-model="content" />

<!-- Switched off -->
<MarkdownViewer v-model="content" :code-copy-button="false" />

The button is styled with CSS variables like everything else:

Clipboard writes use the async Clipboard API and fall back to a selection-based copy on insecure origins (plain http).

Props

Events

Usage

<CliveEdit
  v-model="content"
  @update:modelValue="onContentChange"
  @update:mode="onModeChange"
/>

function onContentChange(markdown: string) {
  console.log('Content changed:', markdown)
}

function onModeChange(mode: 'wysiwyg' | 'markdown') {
  console.log('Mode switched to:', mode)
}

v-model Bindings

CliveEdit supports two v-model bindings:

<CliveEdit
  v-model="markdown"
  v-model:mode="editorMode"
/>

Exposed Methods

Access these via a template ref:

<template>
  <CliveEdit ref="editorRef" v-model="content" />
  <button @click="editorRef?.focus()">Focus Editor</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CliveEdit } from '@dev_owl/cliveedit'

const editorRef = ref<InstanceType<typeof CliveEdit> | null>(null)
const content = ref('')
</script>

Keyboard Shortcuts

These shortcuts work in both WYSIWYG and Markdown modes:

Auto-Formatting Shortcuts

In WYSIWYG mode, CliveEdit detects common markdown patterns as you type and automatically converts them into the corresponding rich-text elements. These shortcuts trigger when you press Space after typing the pattern at the very beginning of an empty line (inside a <p> or <div> block).

Note: Auto-formatting only applies when the shortcut characters are the sole content of the line. If the line already contains other text, the space is inserted normally. These shortcuts do not apply inside existing lists, blockquotes, tables, code blocks, or headings.

Toolbar

Default Toolbar Items

The built-in toolbar includes 20 buttons plus a mode toggle:

Custom Toolbar

toolbarItems lets you define your own toolbar layout.

Important behavior:

• toolbarItems replaces the built-in toolbar completely.
• A toolbar item can be either:
  • a built-in editor action via action: ToolbarAction
  • a custom button via onClick: (ctx) => void
• If you want to append to the built-in toolbar instead of rewriting it manually, use the exported defaultToolbarItems.

That means:

• If you want a smaller toolbar, pass only the buttons you want.
• If you want to add one extra button to the default toolbar, spread defaultToolbarItems and append your own item.
• Custom buttons can run application-specific logic and can also use the injected EditorContext, including ctx.insertText(...) for literal text and ctx.insertMarkdown(...) for markdown-aware insertion.

Insertion semantics:

• ctx.insertText(text) always inserts literal text.
• ctx.insertMarkdown(markdown) inserts raw markdown in markdown mode and renders the markdown into rich content in visual mode before syncing it back to the canonical markdown value.

Example: append application-specific buttons to the built-in toolbar and use both insertion modes.

<template>
  <CliveEdit v-model="content" :toolbar-items="myToolbar" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CliveEdit, defaultToolbarItems } from '@dev_owl/cliveedit'
import type { ToolbarItem } from '@dev_owl/cliveedit'
import { CalendarClock } from '@lucide/vue'

const content = ref('')

const myToolbar: ToolbarItem[] = [
  ...defaultToolbarItems,
  {
    id: 'insert-date-time',
    label: 'Insert Date/Time',
    icon: CalendarClock,
    divider: true,
    onClick: (ctx) => {
      const formatted = new Intl.DateTimeFormat(undefined, {
        dateStyle: 'medium',
        timeStyle: 'short',
      }).format(new Date())

      ctx.insertText(formatted)
    },
  },
  {
    id: 'insert-callout',
    label: 'Insert Callout',
    icon: CalendarClock,
    onClick: (ctx) => {
      ctx.insertMarkdown('> **Note**\n> Review this section before publishing.')
    },
  },
]
</script>

In that example:

• ctx.insertText(formatted) inserts the formatted date/time as literal text.
• ctx.insertMarkdown('> **Note**\n> ...') inserts markdown syntax in markdown mode and rendered rich content in visual mode.

Example: build a smaller toolbar from built-in actions only.

<template>
  <CliveEdit v-model="content" :toolbar-items="compactToolbar" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CliveEdit } from '@dev_owl/cliveedit'
import type { ToolbarItem } from '@dev_owl/cliveedit'
import { Bold, Italic, Heading1, Link, Undo2, Redo2 } from '@lucide/vue'

const content = ref('')

const compactToolbar: ToolbarItem[] = [
  {
    id: 'bold',
    label: 'Bold',
    icon: Bold,
    action: 'bold',
    shortcut: 'Ctrl+B',
    active: (ctx) => ctx.isActive('strong'),
  },
  {
    id: 'italic',
    label: 'Italic',
    icon: Italic,
    action: 'italic',
    shortcut: 'Ctrl+I',
    active: (ctx) => ctx.isActive('em'),
  },
  {
    id: 'heading1',
    label: 'Heading 1',
    icon: Heading1,
    action: 'heading1',
    divider: true,
  },
  {
    id: 'link',
    label: 'Link',
    icon: Link,
    action: 'link',
    shortcut: 'Ctrl+K',
    active: (ctx) => ctx.isActive('a'),
  },
  {
    id: 'undo',
    label: 'Undo',
    icon: Undo2,
    action: 'undo',
    divider: true,
  },
  {
    id: 'redo',
    label: 'Redo',
    icon: Redo2,
    action: 'redo',
  },
]
</script>

toolbarItems still replaces the full rendered toolbar, but exporting defaultToolbarItems makes extension practical.

ToolbarItem Interface

type ToolbarItem = BuiltInToolbarItem | CustomToolbarItem

interface BuiltInToolbarItem {
  id: string              // Unique identifier
  label: string           // Accessible label / tooltip
  icon: Component         // Vue component (Lucide icon or custom)
  action: ToolbarAction   // Action name dispatched on click
  onClick?: never
  shortcut?: string       // Keyboard shortcut label (display only)
  active?: (ctx: EditorContext) => boolean   // Active state check
  divider?: boolean       // Show separator before this item
}

interface CustomToolbarItem {
  id: string
  label: string
  icon: Component
  onClick: (ctx: EditorContext) => void
  action?: never
  shortcut?: string
  active?: (ctx: EditorContext) => boolean
  divider?: boolean
}

type ToolbarAction =
  | 'bold'
  | 'italic'
  | 'strikethrough'
  | 'heading1'
  | 'heading2'
  | 'heading3'
  | 'bulletList'
  | 'orderedList'
  | 'indentList'
  | 'outdentList'
  | 'blockquote'
  | 'codeInline'
  | 'codeBlock'
  | 'link'
  | 'image'
  | 'horizontalRule'
  | 'emoji'
  | 'table'
  | 'print'
  | 'undo'
  | 'redo'

Available action names: bold, italic, strikethrough, heading1, heading2, heading3, bulletList, orderedList, indentList, outdentList, blockquote, codeInline, codeBlock, link, image, horizontalRule, emoji, table, print, undo, redo.

Print action: The print action opens the current document in an isolated print view (a hidden iframe styled with the editor's CSS) and triggers the browser's print dialog. It is read-only — the editor content and the host page are never modified — and it works even when the editor is disabled.

In markdown mode, indentList and outdentList follow the same structural rules as visual mode: list items only move one level at a time, and indenting requires a valid previous sibling at the target level.

Syntax Highlighting

CliveEdit supports syntax highlighting in fenced code blocks via Shiki — the same engine that powers VS Code's syntax highlighting.

Installation

Shiki is an optional peer dependency. Install it alongside CliveEdit:

npm install shiki

Without Shiki installed, code blocks render as plain preformatted text — no errors.

Basic Usage

<CliveEdit
  v-model="content"
  :highlight-options="{
    theme: 'github-light',
    langs: ['javascript', 'typescript', 'python', 'html', 'css']
  }"
/>

Pass {} (empty object) to use defaults with the github-light theme and a set of common languages.

How It Works

• Markdown mode: Write fenced code blocks with a language identifier as usual:

  ```javascript
  const greeting = 'Hello, world!'
  ```
  

• WYSIWYG mode: When you insert a code block, a small language label appears in the top-right corner of the block (initially showing "plain text"). Click the label to type a language name (e.g. javascript, python, css). The code is immediately re-highlighted with the correct syntax colours.

• MarkdownViewer: Highlighted code blocks render automatically when a parent component provides the highlight function (via CliveEdit or useHighlighter).

Theming the Language Label

The language label badge can be customised with CSS variables:

Emoji Picker

CliveEdit supports an emoji picker for inserting native Unicode emoji via emoji-picker-element — a lightweight web component (~12.5 kB min+gz) with built-in search, categories, skin tones, favourites, and accessibility.

Installation

emoji-picker-element is an optional peer dependency. Install it alongside CliveEdit:

npm install emoji-picker-element

Without emoji-picker-element installed, the emoji button simply does not appear in the toolbar — no errors.

Basic Usage

<!-- Defaults -->
<CliveEdit v-model="content" :emoji-picker="true" />

<!-- With options -->
<CliveEdit
  v-model="content"
  :emoji-picker="{ locale: 'en' }"
/>

Options

Pass true instead of an object to use all defaults.

How It Works

• Click the 😊 (Smile) button in the toolbar to open a floating emoji picker panel.
• Search for emoji by typing in the search box.
• Browse by category (Smileys, Animals, Food, etc.).
• Pick a skin tone via the built-in skin tone selector.
• Recently used emoji appear in the Favourites row.
• Select an emoji to insert the native Unicode character at the current cursor position. This works in both WYSIWYG and Markdown modes.
• The picker closes on selection, pressing Escape, or clicking outside.

Emoji are native Unicode characters — they render using each platform's built-in emoji font (Apple on macOS/iOS, Segoe UI Emoji on Windows, Noto Color Emoji on Linux/Android). This is the expected cross-platform behaviour.

Dark Mode

The emoji picker automatically detects whether the editor is in dark mode by reading the computed --ce-bg CSS variable on the .cliveedit wrapper and calculating its luminance. There is no manual darkMode option — just apply your dark theme via CSS custom properties as usual and the picker follows:

<div :class="{ 'dark-theme': isDark }">
  <!-- The emoji picker automatically adapts its dark/light appearance -->
  <CliveEdit v-model="content" :emoji-picker="true" />
</div>

Image Paste & Drop

CliveEdit supports pasting and dragging images directly into the editor. Screenshots from the clipboard, files from your desktop, or images copied from other apps can be inserted seamlessly.

Accepted formats: PNG, JPEG, GIF, WebP

Inserted images are centered automatically in both the editor and the read-only viewer. Resizing only changes the image width, so the browser keeps the original aspect ratio intact.

Default Behaviour (Base64)

With no extra configuration, pasted or dropped images are embedded as base64 data URIs:

<!-- Images just work — no config needed -->
<CliveEdit v-model="content" />

The resulting markdown:

![pasted image](data:image/png;base64,iVBORw0KGgo...)

Note: Base64 encoding increases file size by ~33%. For large images, consider using a custom upload handler instead.

Visual Resize Controls

Click an image in WYSIWYG mode to open its resize tooltip. CliveEdit includes preset width steps of 25%, 50%, 75%, and 100%, plus a custom percentage field for exact sizing.

Resized images are stored in markdown using image-title metadata, for example:

![Preview](https://example.com/image.png "ce-width:75%")

That metadata is handled automatically by CliveEdit and round-trips cleanly between visual and markdown modes.

Custom Upload Handler

Provide an onImageUpload callback to upload images to your own server or cloud storage. The function receives a File object and should return a Promise<string> with the final URL:

<template>
  <CliveEdit v-model="content" :on-image-upload="uploadImage" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CliveEdit } from '@dev_owl/cliveedit'

const content = ref('')

async function uploadImage(file: File): Promise<string> {
  const formData = new FormData()
  formData.append('image', file)

  const res = await fetch('/api/upload', {
    method: 'POST',
    body: formData,
  })
  const { url } = await res.json()
  return url  // e.g. 'https://cdn.example.com/images/photo.png'
}
</script>

If the upload function throws an error, the image is silently discarded.

Size Limit

By default, images larger than 2 MB are rejected. Customise this with the maxImageSize prop (value in bytes):

<!-- Allow images up to 5 MB -->
<CliveEdit
  v-model="content"
  :max-image-size="5 * 1024 * 1024"
/>

Tables

CliveEdit includes full GFM (GitHub Flavoured Markdown) table support. Tables round-trip cleanly between WYSIWYG and Markdown modes.

Inserting a Table

Click the Table button in the toolbar (or call ctx.table() programmatically) to insert a 3×3 starter table with a header row and two body rows. The table is rendered as standard HTML <table> markup and serialised to pipe-delimited GFM markdown:

| Header | Header | Header |
| --- | --- | --- |
|  |  |  |
|  |  |  |

Table Controls

When the cursor is inside a table, a floating control bar appears above it with the following actions:

The control bar repositions automatically as the selection moves between tables and hides when the cursor leaves all tables.

Table Keyboard Navigation

Formatting commands (bold, italic, etc.) work within individual cells. Block-level commands (headings, lists, blockquotes) are disabled when the cursor is inside a table to prevent structural corruption.

Theming

CliveEdit uses CSS custom properties scoped under the .cliveedit class. Override any variable to match your application's design system — no JavaScript configuration needed.

CSS Custom Properties

Layout

Toolbar

Typography

Headings

Content Elements

Interaction

Dark Theme Example

.dark-theme .cliveedit {
  --ce-bg: #1e1e1e;
  --ce-text: #d4d4d4;
  --ce-border: #3e3e42;
  --ce-toolbar-bg: #252526;
  --ce-toolbar-border: #3e3e42;
  --ce-toolbar-btn-hover: #3e3e42;
  --ce-toolbar-btn-active: #505054;
  --ce-code-bg: #2d2d30;
  --ce-code-text: #ce9178;
  --ce-blockquote-border: #6366f1;
  --ce-link-color: #4fc1ff;
  --ce-selection-bg: rgba(38, 79, 120, 0.5);
  --ce-placeholder-color: #6a6a6a;
  --ce-focus-ring: rgba(99, 102, 241, 0.5);
  --ce-hr-color: #3e3e42;
  --ce-line-height: 1;
}

<div :class="{ 'dark-theme': isDark }">
  <CliveEdit v-model="content" />
</div>

You can also use @media (prefers-color-scheme: dark) for automatic dark mode:

@media (prefers-color-scheme: dark) {
  .cliveedit {
    --ce-bg: #1e1e1e;
    --ce-text: #d4d4d4;
    /* ... */
  }
}

Vue Plugin (Global Registration)

Instead of importing CliveEdit in every component, you can register it globally:

// main.ts
import { createApp } from 'vue'
import { CliveEditPlugin } from '@dev_owl/cliveedit'
import '@dev_owl/cliveedit/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(CliveEditPlugin)
app.mount('#app')

Then use <CliveEdit> or <MarkdownViewer> anywhere without importing:

<template>
  <CliveEdit v-model="markdown" />
  <MarkdownViewer v-model="markdown" />
</template>

Advanced Usage

EditorContext (Provide / Inject)

CliveEdit provides an EditorContext object via Vue's provide/inject system. Child or descendant components can access the editor's commands and state:

import { inject } from 'vue'
import { EDITOR_CTX_KEY } from '@dev_owl/cliveedit'

const ctx = inject(EDITOR_CTX_KEY)

// Call formatting commands
ctx?.bold()
ctx?.heading(2)
ctx?.link('https://example.com', 'Example')
ctx?.table()  // Insert a 3×3 table
ctx?.insertText(new Date().toISOString())
ctx?.insertMarkdown('**Prefilled** _markdown_')

// Check state
ctx?.isActive('strong') // true if cursor is inside bold text
ctx?.isActive('table')  // true if cursor is inside a table
ctx?.canUndo            // true if undo is available
ctx?.mode               // 'wysiwyg' | 'markdown'

// Switch modes
ctx?.toggleMode()

EditorContext Interface

interface EditorContext {
  // State
  mode: EditorMode
  disabled: boolean

  // Formatting commands
  bold(): void
  italic(): void
  strikethrough(): void
  heading(level: 1 | 2 | 3): void
  bulletList(): void
  orderedList(): void
  indentList(): void
  outdentList(): void
  blockquote(): void
  codeInline(): void
  codeBlock(lang?: string): void
  link(url?: string, text?: string): void
  image(src?: string, alt?: string): void
  horizontalRule(): void
  table(): void
  emoji(): void
  insertText(text: string): void
  insertMarkdown(markdown: string): void

  // History
  undo(): void
  redo(): void
  canUndo: boolean
  canRedo: boolean

  // Mode
  toggleMode(): void

  // Query
  isActive(tag: string): boolean
}

useHistory Composable

The undo/redo system is available as a standalone composable for headless or custom editor builds:

import { useHistory } from '@dev_owl/cliveedit'

const history = useHistory({ maxDepth: 50, debounceMs: 200 })

history.init('# Initial content')
history.pushState('# Updated content')    // debounced (for keystrokes)
history.pushImmediate('# After toolbar')  // immediate (for actions)

const prev = history.undo()   // returns HistoryEntry | null
const next = history.redo()   // returns HistoryEntry | null

history.canUndo.value  // boolean (computed ref)
history.canRedo.value  // boolean (computed ref)

useEditor Composable

The editor command layer is available standalone for building custom UIs around a contenteditable element:

import { ref } from 'vue'
import { useEditor } from '@dev_owl/cliveedit'

const editorEl = ref<HTMLElement | null>(null)
const editor = useEditor(editorEl)

// Formatting
editor.bold()
editor.italic()
editor.heading(2)
editor.link('https://example.com')

// State
editor.isActive('strong')  // boolean
editor.refreshActiveState()

// DOM access
editor.getHtml()
editor.setHtml('<p>Hello</p>')
editor.focus()

useHighlighter Composable

The syntax highlighting system is available as a standalone composable for advanced or custom integrations:

import { useHighlighter } from '@dev_owl/cliveedit'

const { init, highlight, isReady, provideHighlight } = useHighlighter()

// Initialise Shiki (async — call once at startup)
await init({ theme: 'github-dark', langs: ['javascript', 'python'] })

// Check readiness
isReady.value  // true after successful init

// Highlight code (synchronous after init)
const html = highlight('const x = 42', 'javascript')

// Provide the highlight function to child components
provideHighlight()

Child components can consume the highlight function:

import { useInjectHighlight } from '@dev_owl/cliveedit'

const highlightFn = useInjectHighlight()
// highlightFn.value is null until a parent calls provideHighlight()

useEmojiPicker Composable

The emoji picker system is available as a standalone composable for advanced or custom integrations:

import { useEmojiPicker } from '@dev_owl/cliveedit'

const { init, isReady, enabled, setEnabled } = useEmojiPicker()

// Initialise (async — attempts to load emoji-picker-element)
await init()

// Check readiness
isReady.value  // true after successful init

// Control the feature
setEnabled(false)   // hide the emoji button

Note: Dark mode is detected automatically from the editor's background — there is no manual setDarkMode() call.

TypeScript

All types are exported for full IntelliSense support:

import type {
  EditorMode,
  ToolbarAction,
  ToolbarItem,
  HistoryEntry,
  CliveEditProps,
  CliveEditEmits,
  EditorContext,
  HighlightOptions,
  EmojiPickerOptions,
  MarkdownViewerProps,
} from '@dev_owl/cliveedit'

Build Scripts

Build outputs in dist/:

Browser Support

CliveEdit uses standard DOM APIs (contenteditable, Selection, Range, DOMParser) and works in all modern browsers:

• Chrome / Edge 90+
• Firefox 90+
• Safari 15+

License

MIT