Vue UEditor Wrapper

2.5.6 · maintenance · verified Sun Apr 19

Vue UEditor Wrap is a Vue.js component that integrates Baidu's UEditor, a widely-used rich-text editor in China, into Vue applications. It provides two-way data binding through `v-model`, significantly simplifying UEditor's usage by abstracting away manual initialization and content management (like `getContent` and `setContent` calls). The package is divided into major versions for Vue compatibility: `vue-ueditor-wrap@2.x` supports Vue 2, while `vue-ueditor-wrap@3.x` supports Vue 3. The version 2.5.6 is primarily for Vue 2, with version 3.0.8 being a recent stable release for Vue 3. Its release cadence is irregular, driven by necessary adaptations to new Vue versions and ecosystem changes, rather than active development of the core UEditor. A key differentiator is its ability to dynamically load UEditor's static resources, enabling on-demand loading and mitigating performance impacts. This wrapper addresses the challenge of using an older, feature-rich editor in modern Vue environments, despite the underlying UEditor itself being largely unmaintained by Baidu since 2016.

Common errors

```
Uncaught (in promise) TypeError: Cannot convert undefined or null to object
```
cause UEditor's core scripts (e.g., ueditor.config.js, ueditor.all.min.js) were not found or loaded correctly, often due to an incorrect `UEDITOR_HOME_URL` configuration or missing UEditor static files.

fix Ensure UEditor's static files are correctly placed in your project's public directory (e.g., `public/UEditor/`) and that `UEDITOR_HOME_URL: '/UEditor/'` is correctly set in your `config` prop. Verify the path in your browser's network tab.
```
editor is not defined at link.html:XX:YY
```
cause Attempting to interact with the UEditor instance (e.g., `window.UE` or methods on the editor object) before UEditor's scripts have fully loaded and initialized.

fix Always perform UEditor instance operations within the `@ready` event handler of the `vue-ueditor-wrap` component, which guarantees the editor is fully initialized.
```
Image/file upload fails or returns an empty value.
```
cause The `serverUrl` in the editor configuration is either incorrect, points to a non-existent endpoint, or the backend server itself is not configured to handle UEditor's upload requests correctly.

fix Verify that your `serverUrl` points to a valid and securely implemented backend API designed to handle UEditor file uploads. Do not use the temporary demo `serverUrl` in production.
```
Editor does not render in a Vite/Vue 3 project, or emits 'Uncaught (in promise) TypeError: Cannot convert undefined or null to object'.
```
cause Often caused by using `vue-ueditor-wrap@2.x` in a Vue 3 project (incorrect version), or Vite's asset handling conflicting with the traditional UEditor asset loading path, or `UEDITOR_HOME_URL` misconfiguration for Vite's dev server.

fix For Vue 3, ensure `vue-ueditor-wrap@3.x` is installed. For Vite, place UEditor files in `public/UEditor/` and explicitly set `UEDITOR_HOME_URL: '/UEditor/'`. Clear browser cache.
```
Editor displays a <textarea> before the rich text editor initializes, or the editor doesn't appear correctly.
```
cause This can happen due to delayed loading of UEditor's scripts or styles, or conflicts with other global scripts, especially in environments where scripts are loaded dynamically or asynchronously.

fix Ensure UEditor's `ueditor.config.js` and `ueditor.all.min.js` are loaded without issues. Check browser console for network errors. If using a build system, ensure static assets are correctly served. The `vue-ueditor-wrap` component includes internal mechanisms to handle script loading; ensure no conflicting manual script loading is present.

Warnings

breaking The package has distinct major versions for Vue 2 and Vue 3. `vue-ueditor-wrap@2.x` is for Vue 2 projects, while `vue-ueditor-wrap@3.x` (e.g., 3.0.8) is required for Vue 3. Installing the incorrect major version will lead to compatibility issues and runtime errors.
Fix: Ensure you install the version compatible with your Vue project: `npm i vue-ueditor-wrap@2.x` for Vue 2, or `npm i vue-ueditor-wrap@3.x` for Vue 3.
gotcha UEditor (the underlying editor) is not an NPM package and must be manually downloaded and placed in your project's static assets directory. Typically, this means downloading the official UEditor release and placing the `UEditor` folder (containing `ueditor.config.js`, `ueditor.all.min.js`, etc.) into your project's `public/` directory (for Vue CLI/Vite) or `static/` directory (for older Vue CLI versions).
Fix: Download a UEditor package (e.g., from its GitHub releases or official site, often maintained community forks are safer) and copy its contents to a public-facing folder in your project, then configure `UEDITOR_HOME_URL` in `vue-ueditor-wrap` to point to this location.
breaking The original Baidu UEditor is largely unmaintained since its last official update in 2016 (v1.4.3.3) and has known security vulnerabilities in its provided backend demo code (e.g., SSRF, file inclusion in PHP examples). It is critical to NOT use any of UEditor's bundled backend demo code in a production environment.
Fix: Implement your own secure server-side file upload and management endpoints. Never use the demo backend code provided with UEditor. Review and sanitize all user inputs and file uploads carefully.
gotcha The `UEDITOR_HOME_URL` configuration property is crucial and frequently misconfigured. It must be an absolute or root-relative path pointing to the *static* directory where UEditor's `ueditor.config.js` and other core files are directly accessible by the browser. Incorrect paths will prevent UEditor from loading its resources, resulting in a non-functional editor.
Fix: Verify the `UEDITOR_HOME_URL` in your `config` object. If UEditor is in `public/UEditor/`, set it to `'/UEditor/'`. Ensure this path is accessible in your browser.
gotcha File upload functionality requires a functional backend server endpoint. The `serverUrl` provided in `vue-ueditor-wrap` examples is for demonstration purposes only and should *not* be used in production. Implementing a secure, production-ready backend for file uploads is the user's responsibility.
Fix: Develop a custom backend API for UEditor's `serverUrl` that securely handles file uploads, image management, and other server-side operations.

Install

npm install vue-ueditor-wrap npm
yarn add vue-ueditor-wrap yarn
pnpm add vue-ueditor-wrap pnpm

Imports

VueUeditorWrap
wrong:
```
const VueUeditorWrap = require('vue-ueditor-wrap');
```
correct:
```
import VueUeditorWrap from 'vue-ueditor-wrap';
```
ES Module import for modern JavaScript environments. For CommonJS, use `require` syntax.

VueUeditorWrap (Vue 3 global registration)

wrong:

Vue.component('vue-ueditor-wrap', VueUeditorWrap); // Vue 2 syntax

correct:

import { createApp } from 'vue';
import VueUeditorWrap from 'vue-ueditor-wrap';

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

In Vue 3, the component is typically globally registered using `app.use()`.

VueUeditorWrap (Vue 2 global registration)

wrong:

app.use(VueUeditorWrap); // Vue 3 syntax

correct:

import Vue from 'vue';
import VueUeditorWrap from 'vue-ueditor-wrap';

Vue.component('vue-ueditor-wrap', VueUeditorWrap);

In Vue 2, the component is globally registered using `Vue.component()`.

Quickstart

This quickstart demonstrates basic integration of `vue-ueditor-wrap` in a Vue 3 application using the Composition API (`<script setup>`). It shows `v-model` for two-way data binding and basic editor configuration, highlighting the necessity of manually placing UEditor's static files and configuring `UEDITOR_HOME_URL`.

<template>
  <div id="app">
    <h1>Vue 3 UEditor Example</h1>
    <p>Editor Content:</p>
    <textarea :value="editorContent" readonly style="width: 100%; height: 100px;"></textarea>
    <vue-ueditor-wrap v-model="editorContent"
                      :config="editorConfig"
                      editor-id="myEditorId">
    </vue-ueditor-wrap>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import VueUeditorWrap from 'vue-ueditor-wrap';

const editorContent = ref('<p>Hello <b>Vue 3</b> and <i>UEditor</i>!</p>');

// Note: UEditor static files must be manually downloaded and placed in the public/UEditor/ directory.
// For example, from https://github.com/fex-team/ueditor/releases
// The UEDITOR_HOME_URL should point to the base path where ueditor.config.js and other files reside.
const editorConfig = {
  UEDITOR_HOME_URL: '/UEditor/', // This path should point to where you placed the UEditor folder
  // Optionally, configure your server-side upload interface here.
  // This example uses a placeholder URL. Implement a secure backend for production.
  serverUrl: 'http://example.com/api/ueditor/upload',
  initialFrameWidth: '100%',
  initialFrameHeight: 300,
  // More UEditor configurations can be added here (e.g., toolbar, plugins)
};

// Optional: Access the UEditor instance after it's ready
const ueditorReady = (editorInstance: any) => {
  console.log('UEditor is ready:', editorInstance);
  // You can interact with the editor instance here, e.g., editorInstance.execCommand('fontsize', '24px');
};

// In a real application, you'd likely use a custom component for the editor
// and pass props/emit events more explicitly.
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
</style>

view raw JSON →