admin-vben/docs/src/en/components/common-ui/vben-tiptap.md

outline
deep

Vben Tiptap Rich Text Editor

A rich text editor component built on Tiptap, supporting rich text formatting, image insertion, and image upload features.

If some details are not obvious from the docs, check the live demos as well.

::: info Note

If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion.

:::

Basic Usage

Component List

VbenTiptap

Main rich text editor component.

VbenTiptapPreview

Read-only preview component for displaying editor content.

API

Props

Property	Description	Type	Default
modelValue (v-model)	Editor content (HTML string)	string	''
editable	Whether the editor is editable	boolean	true
toolbar	Whether to show the toolbar	boolean	true
previewable	Whether to show the preview button	boolean	true
placeholder	Placeholder text	string	-
minHeight	Minimum height	number | string	240
maxHeight	Maximum height	number | string	400
extensions	Custom Tiptap extensions	Extensions	-
imageUpload	Image upload configuration	ImageUploadOptions	-

Events

Event	Description	Parameters
change	Triggered when content changes	VbenTiptapChangeEvent

VbenTiptapChangeEvent

interface VbenTiptapChangeEvent {
  html: string; // HTML content
  json: JSONContent; // JSON structure
  text: string; // Plain text content
}

ImageUploadOptions

Image upload configuration:

interface ImageUploadOptions {
  /** Allowed file types, default 'image/*' */
  accept?: string;
  /** Max file size in bytes, default 5MB */
  maxSize?: number;
  /** Upload error callback, uses alert if not provided */
  onUploadError?: (error: unknown) => void;
  /** Upload function, returns image URL */
  upload: (
    file: File,
    onProgress?: (percent: number) => void,
  ) => Promise<string>;
}

VbenTiptapPreview Props

Property	Description	Type	Default
content	HTML content to preview	string	''
minHeight	Minimum height	number | string	160
class	Custom class name	any	-

Toolbar Features

The editor toolbar provides the following features:

Formatting

• Undo/Redo - Undo or redo editing operations
• Clear Formatting - Remove all formatting from selected text
• Bold - Bold text
• Italic - Italic text
• Underline - Underline text
• Strikethrough - Strikethrough text
• Inline Code - Inline code mark

Structure

• Headings - Paragraph, H1-H4 heading switching
• Ordered List - Numbered list
• Bullet List - Bulleted list
• Blockquote - Quote block style
• Code Block - Multi-line code block

Links & Images

• Insert Link - Insert or edit hyperlinks
• Remove Link - Remove link from selected text
• Insert Image - Insert image via URL

Style

• Text Color - Set text color (preset palette)
• Highlight Color - Set text background highlight color

Alignment

• Align Left - Left align text
• Align Center - Center align text
• Align Right - Right align text

Other

• Preview - Preview content in a modal

Image Upload

When imageUpload is configured, the toolbar image button becomes a dropdown menu with "Upload" and "URL" options.

Upload Methods

Three image upload methods are supported:

1. File Selection - Click the upload button in toolbar
2. Drag & Drop - Drag images directly into the editor
3. Paste - Paste images into the editor

Upload Progress Display

During upload:

• Loading Indicator - Spinner animation indicating upload in progress
• Progress Bar - Shows progress bar when upload function provides onProgress callback

File Validation

• accept - Specify allowed file types (MIME types)
• maxSize - Maximum file size limit (bytes)
• Validation failure triggers onUploadError callback or default alert

::: warning Important Notes

• Only single image upload is supported; multi-image drag/paste will show a prompt and process only the first image
• Do not save editor content (getHTML()) during upload as image URLs are temporary blob URLs
• When using custom extensions, the image upload feature will not be available (toolbar won't show upload option)

:::

Custom Extensions

Pass custom Tiptap extension configurations via the extensions property:

<script setup lang="ts">
import { VbenTiptap } from '@vben/plugins/tiptap';
import StarterKit from '@tiptap/starter-kit';
import Underline from '@tiptap/extension-underline';

const extensions = [
  StarterKit,
  Underline,
  // Other extensions...
];
</script>

<template>
  <VbenTiptap v-model="content" :extensions="extensions" />
</template>

::: warning Custom Extensions Note

When using custom extensions:

• Default extension configuration will not take effect
• Image upload feature is not available (toolbar won't show upload option)
• You need to configure all required editor features yourself

:::