How to Add Custom Styles and Themes to Components in Luban H5

You can customize Luban H5 components by leveraging its three-layer styling architecture—global SCSS frameworks, component-level theme classes controlled via the theme prop, and inline overrides using customStyle or customClass properties.

Luban H5 is an open-source visual page builder that renders UI blocks as Vue components. To add custom styles and themes to components in Luban H5, you work within a structured architecture that separates global design tokens, preset theme classes, and ad-hoc customizations.

Understanding the Three-Layer Styling Architecture

The styling system in ly525/luban-h5 is organized into three distinct layers that work together to provide flexibility while maintaining consistency.

Global Style Framework

The foundation consists of SCSS helper files that define spacing, shapes, color variables, and utility classes. These global styles live in front-end/h5/src/components/core/styles/index.scss and are imported across the application. When you create custom themes, you can reference these utilities to maintain consistency with the base design system.

Component-Level Theme Classes

Each component that supports theming exposes a theme prop that applies a preset CSS class to the root element. For example, in front-end/h5/src/components/core/plugins/lbp-table.js, the component defines a theme prop (around line 25) that toggles between visual variants like lbp-table-theme-stripe or lbp-table-theme-light-blue. These classes are defined in associated SCSS files and activated by passing the theme name to the component.

Custom Style Overrides

For one-off customizations, components accept customStyle and customClass props. The customStyle object merges with internal component styles, while customClass appends additional classes to the root element. This layer is ideal for specific instances where you need unique styling without creating a reusable theme.

Adding a Custom Theme to a Component

To add custom styles and themes to components in Luban H5, follow this implementation pattern using the Table component as an example.

Step 1: Create the SCSS Theme File

Create a new SCSS file that defines your theme classes:

// front-end/h5/src/components/core/styles/custom-table-theme.scss
.my-table-theme {
  background: #f8f9fa;
  border-radius: 6px;
  
  .lbp-table-cell {
    padding: 12px 8px;
    border-bottom: 1px solid #e9ecef;
  }
}

Step 2: Import the Styles into the Component

Open the component's plugin file and import your new stylesheet:

// front-end/h5/src/components/core/plugins/lbp-table.js
import '@/components/core/styles/custom-table-theme.scss';

export default {
  name: 'lbp-table',
  props: {
    theme: {
      type: String,
      default: '',
      // Add your theme to the enum for UI visibility
      enum: ['', 'lbp-table-theme-stripe', 'lbp-table-theme-light-blue', 'my-table-theme']
    }
  }
  // ...
};

Step 3: Activate the Theme

Apply the theme when using the component in your page:

<template>
  <lbp-table 
    :theme="'my-table-theme'" 
    :data="tableData" 
  />
</template>

Applying Inline Custom Styles

For scenarios requiring unique styling without reusable themes, use the customStyle and customClass props.

Using customStyle for Inline Overrides

Pass a style object that merges with the component's internal styles:

<lbp-qq-map
  class="my-map-container"
  :customStyle="{ 
    width: '100%', 
    height: '400px', 
    border: '2px solid #ddd',
    borderRadius: '8px'
  }"
/>

Using customClass for Additional Classes

Append extra CSS classes to the root element:

<lbp-table 
  :customClass="'extra-padding shadow-lg'" 
  :data="tableData"
/>

Then define these classes in your SCSS:

// front-end/h5/src/components/core/styles/utility-classes.scss
.extra-padding {
  padding: 20px;
}

.shadow-lg {
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}

Key Source Files for Custom Styling

Understanding where styling logic resides in the ly525/luban-h5 repository helps you navigate the codebase effectively.

Purpose	File Path	Why It Matters
Global SCSS Entry	front-end/h5/src/components/core/styles/index.scss	Imports helper utilities and variables available to all custom themes.
Component Theme Prop	front-end/h5/src/components/core/plugins/lbp-table.js	Defines the theme prop (around line 25) that toggles preset CSS classes.
Vue CLI Theme Alias	front-end/h5/vue.config.js	Contains a commented alias at line 84 for ./src/theme that you can uncomment to enable a dedicated theme folder.
Component Style Import Example	front-end/h5/src/components/core/plugins/lbp-text.js	Demonstrates importing component-specific SCSS at line 17 (e.g., text-overwrite-quil-snow-theme.scss).
Custom Editor Props	docs/zh/plugin-development/how-it-works/custom-editor-multiple-props.md	Documents the custom: true flag used when creating new components with custom styling options.

Summary

To add custom styles and themes to components in Luban H5, leverage the three-layer architecture that separates global SCSS utilities, component-level theme classes, and inline overrides:

• Global styles in front-end/h5/src/components/core/styles/index.scss provide design tokens and utilities for all themes.
• Component themes use the theme prop defined in plugin files like lbp-table.js to toggle preset CSS classes.
• Inline customization via customStyle and customClass props allows one-off adjustments without creating reusable themes.

By creating SCSS files in the styles directory, importing them into component plugins, and registering theme names in prop definitions, you can extend Luban H5's visual system to match any design requirement.

Frequently Asked Questions

How do I create a completely new theme for a Luban H5 component?

Create a new SCSS file in front-end/h5/src/components/core/styles/ that defines your CSS classes, then import it in the component's plugin file (e.g., lbp-table.js). Add your theme name to the theme prop's enum array so it appears in the editor UI, then activate it by passing the theme name to the component's theme prop.

Can I use inline styles instead of creating a theme file?

Yes. Every Luban H5 component accepts a customStyle prop that accepts a style object. This object merges with the component's internal styles, allowing you to override specific properties like backgroundColor, borderRadius, or padding without creating a reusable theme class.

Where should I place global style variables that multiple themes share?

Place shared SCSS variables, mixins, and utility classes in front-end/h5/src/components/core/styles/index.scss. This file serves as the global entry point for the styling system, and any variables defined here are available to all component-specific theme files you create.

What is the difference between the theme prop and customClass prop?

The theme prop activates predefined CSS class sets that are bundled with the component (such as lbp-table-theme-stripe), while the customClass prop allows you to append arbitrary CSS class names to the component's root element. Use theme for switching between designed visual variants, and customClass for one-off utility classes or experimental styling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}