# How to Create a Custom Plugin Component in Luban H5: A Complete Guide

> Learn to create a custom plugin component in Luban H5 with our complete guide. Scaffold a Vue component implement logic and register your plugin effortlessly.

- Repository: [小小鲁班/luban-h5](https://github.com/ly525/luban-h5)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To create a custom plugin component in Luban H5, scaffold a Vue component using the official `vue-cli-plugin-lubanh5-component` preset, implement your logic in [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js), optionally add a custom editor panel in [`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js), and register the plugin via the editor's plugin system.**

Luban H5 is an open-source visual page builder that powers the `ly525/luban-h5` repository. Extending the editor with custom plugin components allows you to add bespoke UI elements, business logic, or third-party integrations while maintaining full compatibility with the visual editing experience.

## Scaffolding a New Plugin Component

The fastest way to create a custom plugin component in Luban H5 is using the official Vue CLI preset. This generates the required folder structure and boilerplate automatically.

Run the following command to scaffold your plugin:

```bash
vue create --preset luban-h5/vue-cli-plugin-lbhc my-luban-plugin
cd my-luban-plugin

```

The preset creates a standardized structure documented in [`docs/zh/plugin-development/quick-start.md`](https://github.com/ly525/luban-h5/blob/main/docs/zh/plugin-development/quick-start.md)【[[`quick-start.md`](https://github.com/ly525/luban-h5/blob/main/quick-start.md)](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/quick-start.md)】:

```

mini-editor/                 # simulated core editor environment

component/
  ├─ index.js               # component entry (Vue component)

  └─ editor.js                # optional editor-panel configuration

```

## Implementing the Component Logic

A Luban H5 plugin component is fundamentally a standard Vue component. You write your logic in [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js), including props, methods, computed properties, and template syntax.

### Default Injected Props

The editor automatically injects several default props into every plugin component, as documented in [`docs/zh/plugin-development/plugin-default-inject-props.md`](https://github.com/ly525/luban-h5/blob/main/docs/zh/plugin-development/plugin-default-inject-props.md)【[[`plugin-default-inject-props.md`](https://github.com/ly525/luban-h5/blob/main/plugin-default-inject-props.md)](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/plugin-default-inject-props.md)】. These include:

- **`editorMode`**: Distinguishes between `'edit'` and `'preview'` modes, allowing you to change behavior based on context.
- **`uuid`**: A unique identifier for the component instance.

Here is a complete example of [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js):

```js
// component/index.js
export default {
  name: 'my-custom-button',
  props: {
    text: {
      type: String,
      default: 'Click me',
    },
    color: {
      type: String,
      default: '#409EFF',
      // The `editor` key tells Luban H5 which UI component to use in the property panel
      editor: {
        type: 'el-color-picker',
      },
    },
  },
  methods: {
    handleClick() {
      this.$emit('click');
    },
  },
  template: `
    <el-button
      :style="{ backgroundColor: color }"
      @click="handleClick"
    >{{ text }}</el-button>
  `,
};

```

## Creating a Custom Editor Panel

When the default prop editors are insufficient, you can provide a custom editor panel. This is a Vue component that renders in the right-hand property panel when your plugin is selected.

Create [`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js) (or [`component/editor.vue`](https://github.com/ly525/luban-h5/blob/main/component/editor.vue)) as documented in [`docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md`](https://github.com/ly525/luban-h5/blob/main/docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md)【[[`custom-editor-single-prop.md`](https://github.com/ly525/luban-h5/blob/main/custom-editor-single-prop.md)](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md)】:

```js
// component/editor.js
export default {
  name: 'my-button-editor',
  props: {
    pluginProps: {
      type: Object,
      required: true,
    },
  },
  data() {
    return {
      localProps: { ...this.pluginProps },
    };
  },
  watch: {
    localProps: {
      deep: true,
      handler(val) {
        this.$emit('update:pluginProps', val);
      },
    },
  },
  template: `
    <div>
      <el-input v-model="localProps.title" placeholder="Card title" />
      <el-color-picker v-model="localProps.bgColor" />
    </div>
  `,
};

```

The core editor loads this through [`mini-editor/panel/props.js`](https://github.com/ly525/luban-h5/blob/main/mini-editor/panel/props.js), rendering your custom UI whenever the component is active.

## Registering and Distributing Your Plugin

The scaffolded project automatically handles registration through the plugin index system. The core registration logic resides in [`front-end/h5/src/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/plugins/index.js)【[[`plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/plugins/index.js)](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/index.js)】, which imports:

- [`UI.js`](https://github.com/ly525/luban-h5/blob/main/UI.js) – UI-related mixins exposing editor utilities【[[`plugins/UI.js`](https://github.com/ly525/luban-h5/blob/main/plugins/UI.js)](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/UI.js)】
- [`Prototype.js`](https://github.com/ly525/luban-h5/blob/main/Prototype.js) – Vue prototype extensions for helper methods【[[`plugins/Prototype.js`](https://github.com/ly525/luban-h5/blob/main/plugins/Prototype.js)](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/Prototype.js)】
- [`components/global/index.js`](https://github.com/ly525/luban-h5/blob/main/components/global/index.js) – global component registration that automatically loads custom plugins【[[`components/global/index.js`](https://github.com/ly525/luban-h5/blob/main/components/global/index.js)](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/components/global/index.js)】

To distribute your plugin, build and publish to npm:

```bash

# Build the plugin package

yarn build

# Publish to npm (use --access public for scoped packages)

npm login
npm publish

```

Install the plugin in any Luban H5 project:

```bash
yarn add my-luban-plugin

```

The editor automatically discovers the plugin, injects default props, and makes the custom editor panel available without additional configuration.

## Complete Working Example

Here is a minimal end-to-end example you can copy into a fresh scaffolded project.

**Scaffold the project:**

```bash
vue create --preset luban-h5/vue-cli-plugin-lbhc demo-plugin
cd demo-plugin

```

**[`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js):**

```js
export default {
  name: 'demo-card',
  props: {
    title: {
      type: String,
      default: 'Demo Card',
      editor: { type: 'el-input' },
    },
    bgColor: {
      type: String,
      default: '#FFFFFF',
      editor: { type: 'el-color-picker' },
    },
  },
  template: `
    <div :style="{ backgroundColor: bgColor, padding: '12px', border: '1px solid #ddd' }">
      <h3>{{ title }}</h3>
      <slot />
    </div>
  `,
};

```

**[`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js)** (optional):

```js
export default {
  name: 'demo-card-editor',
  props: { pluginProps: Object },
  data() {
    return { local: { ...this.pluginProps } };
  },
  watch: {
    local: {
      deep: true,
      handler(v) { this.$emit('update:pluginProps', v); },
    },
  },
  template: `
    <div>
      <el-input v-model="local.title" placeholder="Card title" />
      <el-color-picker v-model="local.bgColor" />
    </div>
  `,
};

```

**Build and publish:**

```bash
yarn build
npm publish

```

**Install in another project:**

```bash
yarn add demo-card

```

The component appears in the editor’s component palette automatically.

## Summary

- **Scaffold** your plugin using `vue create --preset luban-h5/vue-cli-plugin-lbhc` to generate the required [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js) and optional [`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js) files.
- **Implement** the component as a standard Vue component in [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js), utilizing automatically injected props like `editorMode` and `uuid`.
- **Configure** the property panel by adding an `editor` field to props for simple cases, or create a full custom editor panel in [`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js) for complex UIs.
- **Register** the plugin through the automatic global component system in [`front-end/h5/src/components/global/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/global/index.js).
- **Distribute** by building with `yarn build` and publishing to npm, then installing via `yarn add` in target projects.

## Frequently Asked Questions

### What is the difference between a plugin component and a regular Vue component in Luban H5?

A plugin component is a Vue component that follows the Luban H5 packaging convention, including the [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js) entry point and optional [`component/editor.js`](https://github.com/ly525/luban-h5/blob/main/component/editor.js) for property panel customization. While regular Vue components can be used anywhere, plugin components receive automatic injections like `editorMode` and `uuid`, and integrate with the visual editor's property panel system as documented in [`plugin-default-inject-props.md`](https://github.com/ly525/luban-h5/blob/main/plugin-default-inject-props.md).

### How do I access the editor mode inside my custom plugin component?

The editor automatically injects the `editorMode` prop into every plugin component, distinguishing between `'edit'` and `'preview'` modes. You can use this prop to conditionally render editing controls or disable interactive features while in edit mode. This injection is handled by the core plugin system in [`front-end/h5/src/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/plugins/index.js) and [`UI.js`](https://github.com/ly525/luban-h5/blob/main/UI.js).

### Can I use third-party UI libraries in my Luban H5 plugin?

Yes, you can import any UI library that Luban H5 already bundles, such as Element-UI, Ant-Design-Vue, or Vant. Since these libraries are already registered globally in the editor, you can use their components directly in your plugin's template without additional installation. For example, use `<el-button>` or `<el-input>` directly in your [`component/index.js`](https://github.com/ly525/luban-h5/blob/main/component/index.js) template string.

### What is the purpose of the [`editor.js`](https://github.com/ly525/luban-h5/blob/main/editor.js) file in a Luban H5 plugin?

The [`editor.js`](https://github.com/ly525/luban-h5/blob/main/editor.js) file provides a custom property panel UI for your plugin component. While simple props can use the inline `editor` configuration in [`index.js`](https://github.com/ly525/luban-h5/blob/main/index.js), complex components requiring coordinated multi-field editing or custom validation should export a Vue component from [`editor.js`](https://github.com/ly525/luban-h5/blob/main/editor.js). This component receives the full `pluginProps` object and emits `update:pluginProps` to sync changes back to the main component, as implemented in [`mini-editor/panel/props.js`](https://github.com/ly525/luban-h5/blob/main/mini-editor/panel/props.js).