Guide to Custom Component Development in WeChat Mini Programs

Introduction

WeChat Mini Programs aim for lightweight applications, but growing business requirements demand more sophisticated component‑based development to improve collaboration and efficiency.

Component Import Methods

Before version 1.6.3, only *. wxml , *. js and *. wxss files could be extracted and reused via import or include . The import method brings a template into the current file with its own scope, while include performs a direct code copy without scope isolation.

Custom Component Definition

From version 1.6.3 onward, Mini Programs support true custom components using the Component constructor. A component consists of four files: componentName.js , componentName.wxml , componentName.wxss , and componentName.json (where "component": true is declared).

// toast.js
Component({
  properties: {
    toastMsg: { type: String, value: '' }
  },
  data: {
    isToastShow: false
  },
  methods: {
    toastShow() {
      this.setData({ isToastShow: true });
    }
  }
});

The corresponding .wxml defines the template:

<template name="toast">
  <view class="{{iconType}}"></view>
  <view>{{toastMsg}}</view>
</template>

Using a Custom Component

Declare the component in the page’s json file:

"usingComponents": {
  "toast": "/components/toast/toast"
}

Then embed it in the page markup and pass data via the data attribute:

<toast id="toast" icon-type="okay" toast-msg="okay成功啦"></toast>

Obtain the component instance in onLoad with this.selectComponent('#toast') and call its methods, e.g., this.toast.toastShow() .

Event Handling

Custom components trigger events using this.triggerEvent('myevent', detail, option) . Parent pages listen with either bindmyevent="onMyEvent" or bind:myevent="onMyEvent" , the latter offering better compatibility.

Third‑Party Component Frameworks

Two popular MVVM‑style frameworks for Mini Programs are:

WePY : Vue‑like single‑file components, supports Less/Sass, Babel/TypeScript, and improves development efficiency.

mpvue : Directly converts a Vue.js application into a Mini Program, offering full Vue.js experience, Vuex state management, and webpack build support.

Conclusion

For simple display components, include is sufficient; for data‑driven templates, use import ; for complex components with events and methods, adopt custom components. Larger projects may benefit from WePY or mpvue, while smaller projects can stick to native componentization. Starting from base library 1.9.6, plugins are also supported, further extending component capabilities.