Custom component

Starting with the Mini Program base library version 1.6.3, the Mini Program supports simplified component programming. The base library version 1.6.3 or higher is required for all custom component related features.

The developers can abstract functional modules within a page into custom components for reuse in different pages; they can also split complex pages into multiple low-coupling modules to help with code maintenance. The usage of custom components are very similar to the underlying components.

Create a custom component

Similar to a page, a custom component consists of 4 files, which include json, wxml, wxss and js. To write a custom component, you first need to make a custom component declaration in the json file (setting the component field to true can make this set of files a custom component):

  "component": true

In addition, you also need to write component templates in the wxml file, and add component styles to the wxss file, and they are written in a similar way to the page. See Component Templates and Styles for details and considerations.

Code sample:

<!-- This is the internal WXML structure of the custom component. -->
<view class="inner">
/* The style here only applies to this custom component */
.inner {
  color: red;

Note: The ID selector, attribute selector, and tag name selector should not be used in the component wxss.

In the custom component's js file, you need to use Component() to register the component and provide the component's attribute definitions, internal data, and custom methods.

The component's attribute values and internal data are used for rendering wxml of component, where the attribute value is passed in from outside of the component. See Component Constructor for more details.

Code sample:

  properties: {
    // The innerText attribute is defined here, and the attribute value can be specified when the component is used.
    innerText: {
      type: String,
      value: 'default value',
  data: {
    // Here is some component internal data
    someData: {}
  methods: {
    // Here is a custom method
    customMethod: function(){}

Use custom components

Before using a registered custom component, first make a reference declaration in the page's json file. You need to provide the tag name of each custom component and the file path of corresponding custom component:

  "usingComponents": {
    "component-tag-name": "path/to/the/custom/component"

Thus, you can use custom components like the base component in the wxml of the page. The node name is the tag name of the custom component, and the node attribute is the attribute value passed to the component.

Code sample:

Preview with Developer Tool

  <!-- The following is a reference to a custom component. -->
  <component-tag-name inner-text="Some text"></component-tag-name>

The custom component's wxml node structure, after being combined with the data, will be inserted into the referenced location.


  • For the 1.5.x version of the base library, 1.5.7 also supports for some custom components.
  • Because WXML node tag names can only be a combination of lowercase letters, strikes, and underscores, so the custom component tag names can only contain these characters.
  • The custom components can also reference custom components, and the reference methods are similar to how pages reference custom components (using the usingComponents field).
  • The root name of the project where the custom component and the page using the custom component are located cannot be prefixed with "wx-", otherwise an error will be reported.
  • Older versions of the base library do not support custom components, in which case the node that references the custom component becomes a default empty node.

个结果 ""

    没有找到相关内容 ""