# How to Add a New Component Type to the Editor Sidebar in Luban H5

> Learn how to add a new component type to the Luban H5 editor sidebar. This guide details creating Vue components, plugin definitions, and registration for seamless integration.

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

---

**To add a new component type to the editor sidebar in Luban H5, create a Vue component and a plugin definition object containing metadata (name, label, component, defaultProps, and optional componentsForPropsEditor), register it in [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js), and add corresponding i18n keys to the locale files.**

Luban H5 is an open-source visual page builder that enables developers to extend its component library through a plugin-based architecture. When you add a new component type to the editor sidebar, you are essentially registering a plugin entry that the left-panel component ([`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js)) renders as a draggable item. This guide provides a complete walkthrough of creating the component file, configuring the plugin registry, and adding internationalization support.

## Understanding the Plugin Architecture

The Luban H5 editor constructs its left sidebar from the `plugins` array exported by [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js). Each object in this array defines a component type available in the **Components** tab.

According to the source code in [`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js), the sidebar iterates over this registry to render draggable plugin items. The registry entry must expose specific fields:

- **name**: A unique identifier for the component type (e.g., `lbp-my-button`)
- **label**: An i18n key for the display name in the sidebar
- **component**: The Vue component rendered on the canvas
- **defaultProps**: Default property values when the component is first dropped
- **componentsForPropsEditor**: (Optional) Configuration for the right-panel property editor
- **icon**: (Optional) Icon displayed in the sidebar list

## Step-by-Step Guide to Adding a New Component

### Step 1: Create the Component File

Create a new JavaScript file under `src/components/core/plugins/`. This file exports an object describing your component.

```javascript
// src/components/core/plugins/lbp-my-button.js
import MyButton from '@/components/core/plugins/lbp-button.vue';

export default {
  name: 'lbp-my-button',
  label: 'myButton.title',
  component: MyButton,
  defaultProps: {
    text: 'Click me',
    type: 'primary',
    size: 'default'
  },
  componentsForPropsEditor: {
    text: { type: 'input', placeholder: 'Button label' },
    type: { type: 'select', options: ['primary', 'default', 'dashed'] }
  },
  icon: require('@/assets/icons/button.svg')
};

```

The `componentsForPropsEditor` object defines how the right-panel renders property controls. Each key corresponds to a `defaultProps` field.

### Step 2: Register the Component in the Plugin Index

Edit [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js) to import your new file and add it to the exported `plugins` array.

```javascript
// src/components/core/plugins/index.js
import LbpButton from './lbp-button.js';
import LbpMyButton from './lbp-my-button.js';

export const plugins = [
  // ... existing plugins ...
  {
    name: 'lbp-my-button',
    label: 'myButton.title',
    component: LbpMyButton.component,
    defaultProps: LbpMyButton.defaultProps,
    componentsForPropsEditor: LbpMyButton.componentsForPropsEditor,
    icon: LbpMyButton.icon
  }
];

```

The left-panel component in [`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js) automatically iterates over this array to populate the sidebar.

### Step 3: Add Internationalization (i18n) Strings

Add display names and tooltips to the locale files so the sidebar shows human-readable text.

```javascript
// src/locales/lang/en-US.js
{
  // ...
  "myButton.title": "My Button",
  "myButton.tooltip": "A custom button you can configure"
}

```

```javascript
// src/locales/lang/zh-CN.js
{
  // ...
  "myButton.title": "我的按钮",
  "myButton.tooltip": "可自定义的按钮组件"
}

```

The `label` field in your plugin entry references the `myButton.title` key.

### Step 4: Add a Custom Icon (Optional)

Place an SVG or PNG file in `src/assets/icons/` and reference it in your plugin definition:

```javascript
icon: require('@/assets/icons/my-button.svg')

```

If no icon is provided, the sidebar may render a default placeholder.

## Complete Working Example

Here is the full implementation combining all steps above.

**Plugin Definition:**

```javascript
// src/components/core/plugins/lbp-my-button.js
import MyButton from '@/components/core/plugins/lbp-button.vue';

export default {
  name: 'lbp-my-button',
  label: 'myButton.title',
  component: MyButton,
  defaultProps: {
    text: 'Click me',
    type: 'primary',
    size: 'default'
  },
  componentsForPropsEditor: {
    text: { type: 'input', placeholder: 'Button label' },
    type: { type: 'select', options: ['primary', 'default', 'dashed'] }
  },
  icon: require('@/assets/icons/button.svg')
};

```

**Registry Update:**

```javascript
// src/components/core/plugins/index.js
import LbpMyButton from './lbp-my-button.js';

export const plugins = [
  // ... existing plugins ...
  {
    name: 'lbp-my-button',
    label: 'myButton.title',
    component: LbpMyButton.component,
    defaultProps: LbpMyButton.defaultProps,
    componentsForPropsEditor: LbpMyButton.componentsForPropsEditor,
    icon: LbpMyButton.icon
  }
];

```

**Locale Entries:**

```javascript
// src/locales/lang/en-US.js
"myButton.title": "My Button",
"myButton.tooltip": "A custom button you can configure"

// src/locales/lang/zh-CN.js
"myButton.title": "我的按钮",
"myButton.tooltip": "可自定义的按钮组件"

```

## Key Files Reference

| File | Purpose |
|------|---------|
| [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js) | Central registry exporting the `plugins` array that populates the sidebar. |
| [`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js) | UI component that iterates over the plugin registry to render draggable items. |
| [`src/locales/lang/en-US.js`](https://github.com/ly525/luban-h5/blob/main/src/locales/lang/en-US.js) | English translations for component labels and tooltips. |
| [`src/locales/lang/zh-CN.js`](https://github.com/ly525/luban-h5/blob/main/src/locales/lang/zh-CN.js) | Chinese translations for component labels and tooltips. |
| `src/assets/icons/` | Directory for sidebar icons referenced by plugin entries. |

## Summary

- **Create** a plugin definition file in `src/components/core/plugins/` containing `name`, `label`, `component`, `defaultProps`, and optional `componentsForPropsEditor` and `icon`.
- **Register** the plugin by importing it into [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js) and adding it to the exported `plugins` array.
- **Localize** the component name by adding entries to [`src/locales/lang/en-US.js`](https://github.com/ly525/luban-h5/blob/main/src/locales/lang/en-US.js) and [`src/locales/lang/zh-CN.js`](https://github.com/ly525/luban-h5/blob/main/src/locales/lang/zh-CN.js) using the key specified in the `label` field.
- **Verify** that the left-panel component ([`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js)) renders your new entry by iterating over the updated registry.

## Frequently Asked Questions

### Where does the sidebar component list come from in Luban H5?

The sidebar component list is generated dynamically from the `plugins` array exported by [`src/components/core/plugins/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/plugins/index.js). The left-panel component ([`src/components/core/editor/left-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/src/components/core/editor/left-panel/index.js)) iterates over this array to render each draggable plugin item, using the `label` and `icon` fields for display.

### What fields are required when defining a new plugin entry?

At minimum, a plugin entry must include `name` (unique identifier), `label` (i18n key for the display name), `component` (the Vue component rendered on canvas), and `defaultProps` (initial property values). Optional but recommended fields include `componentsForPropsEditor` (configures the right-panel property editor) and `icon` (displayed in the sidebar).

### How do I add property editing controls to the right panel?

Define a `componentsForPropsEditor` object in your plugin entry where each key matches a field in `defaultProps`. Each value should specify the editor type (e.g., `input`, `select`) and configuration options like `placeholder` or `options`. The editor's right-panel uses this configuration to render the appropriate form controls for your component.

### Can I reuse an existing Vue component for my new plugin type?

Yes, you can reference any existing Vue component in the `component` field of your plugin definition. For example, you could import [`lbp-button.vue`](https://github.com/ly525/luban-h5/blob/main/lbp-button.vue) and use it as the canvas component for your new plugin entry while providing different `defaultProps` or `componentsForPropsEditor` configurations to create a specialized variant with distinct default behavior or property controls.