# Component Template and Style

Similar to a page, each custom component has its own wxml template and wxss style.

# Component Template

Component templates are written in the same way as page templates. The node tree generated by binding the component template with the component data will be inserted into the location where the component is referenced.

A <slot> node can be provided in the component template to host the child nodes provided via component reference.

Code example:

Preview with Developer Tool

<!-- Component template -->
<view class="wrapper">
  <view>This indicates the internal node of the component</view>
  <slot></slot>
</view>

<!--Page template where the component is referenced-->
<view>
  <component-tag-name>
    <!-- This part is added to the location of the  <slot>  component -->
    <view>This is inserted in the slot component</view>
  </component-tag-name>
</view>

Note that the custom component referenced in the template and the name of its corresponding node should be explicitly defined in the json file, otherwise the node will be deemed as meaningless. Besides, the node name can also be declared as an Abstract Node.

# Template Data Binding

Like an ordinary WXML template, data binding can also be employed to pass dynamic data to child component properties.

Code example:

<!--Page template where the component is referenced-->
<view>
  <component-tag-name prop-a="{{dataFieldA}}" prop-b="{{dataFieldB}}">
    <!-- This part is added to the location of the  <slot>  component -->
    <view>This is inserted in the slot component</view>
  </component-tag-name>
</view>

In the above example, the component properties propA and propB receive data passed from the page, and the page can change linked data field via setData.

Note: Only JSON compatible data can be passed via the above data binding. From base library 2.0.9 and later, functions can also be included in the data. However, such functions cannot be called directly in WXML, but are only passed to child components.

# slot of Component's WXML

The slot node can be included in the component's wxml to host the wxml structure provided by the component user.

By default, a component's wxml can contain only one slot. Multiple slots can be enabled by declaring in the component js if needed.

Component({
  options: {
    multipleSlots: true // Enable multiple slots in the options of component definition.
  },
  properties: { /* ... */ },
  methods: { /* ... */ }
})

In this case, multiple slots can be used in the wxml of this component, each with a unique name.

<!-- Component template -->
<view class="wrapper">
  <slot name="before"></slot>
  <view>This indicates the internal details of the component</view>
  <slot name="after"></slot>
</view>

You can use the slot property to insert nodes into different slots.

<!--Page template where the component is referenced-->
<view>
  <component-tag-name>
    <!-- This part is added to the location of the  <slot name="before">  component -->
    <view slot="before">This is inserted in the slot name="before" component</view>
    <!-- This part is added to the location of the  <slot name="after">  component -->
    <view slot="after">This is inserted in the slot name="after" component</view>
  </component-tag-name>
</view>

# Component Style

The style of a component for the wxss file is only valid for the nodes in the component's wxml. Note the following when writing a component style:

For the components and the pages that reference the components, the class selector, instead of the id selector (#a), property selector ([a]) and tag name selector, should be used.
Unexpected behaviors may occur with the descendant selector (.a .b) used in the components and the pages that reference the components in extreme cases. If so, avoid using it.
The child selector (.a>.b) can be only used for the view component and its child nodes; unexpected behaviors may occur if it is used in other components.
Inheritance styles, such as font and color, are inherited into the components from outside the components.
In addition to inheritance styles, the styles in app.wxss and the styles of the pages that reference the components are invalid for custom components (unless the component style isolation option is changed).

#a { } /* Cannot be used in components */
[a] { } /* Cannot be used in components */
button { } /* Cannot be used in components */
.a > .b { } /* Invalid unless  .a  is  view  component node */

In addition, a default style can be specified for the node where the component resides by using the :host selector (supported by the Weixin DevTools that contain the base library 1.7.2 or later).

Code example:

Preview with Developer Tool

/* Component custom-component.wxss */
:host {
  color: yellow;
}

<!-- Page's WXML -->
<custom-component>The text here is highlighted in yellow</custom-component>

# Component Style Isolation

By default, the styles of custom components are only affected by the wxss of custom components, unless in the following cases:

The tag name selector (or other special selectors) is used inapp.wxss or wxss of the page to directly specify styles, which might affect the page and all components. This is generally not recommended.
Specify the special style isolation option styleIsolation.

Component({
  options: {
    styleIsolation: 'isolated'
  }
})

Preview with Developer Tool

The styleIsolation option is supported in the base library 2.6.5 and later, which supports the following values:

isolated indicates that the style isolation is enabled. Styles specified via class (default styles in normal cases) are not mutually affected in or outside custom components;
apply-shared indicates that the page's wxss style will affect custom components. However, the style specified in the wxss of custom components will not affect the page;
shared indicates that the page's wxss style will affect custom components, and the style specified in the wxss of custom components will also affect the page and other custom components configured with apply-shared or shared. (This option is not available in plug-ins.)

Pay close attention to the interaction between the styles when using the last two options.

If this Component constructor is used to construct a page, the default value is shared and there are several additional style isolation options available:

page-isolated indicates that app.wxss is disabled on this page, and the wxss of the page does not affect other custom components;
page-apply-shared indicates that app.wxss is disabled on this page, and the wxss of the page does not affect other custom components. But the custom components configured with shared will affect the page;
page-shared indicates that app.wxss is disabled on this page. The wxss of the page will affect other custom components configured with apply-shared or shared, and will also be affected by the custom components configured with shared.

In addition, the addGlobalClass option is supported in the Mini Program base library 2.2.3 and later to set addGlobalClass: true in the options of Component. This option is equivalent to setting styleIsolation: apply-shared, but will become invalid if the styleIsolation option is set.

Code example:

Preview with Developer Tool

/* Component custom-component.js */
Component({
  options: {
    addGlobalClass: true,
  }
})

<!-- Component custom-component.wxml -->
<text class="red-text">The color of this text is determined by `app.wxss` and the style in `wxss` of the page</text>

/* app.wxss */
.red-text {
  color: red;
}

# External Style Class

Sometimes, a component wants to accept a style class passed in externally. In this case, you can define several external style classes in Component via the externalClasses definition field. This feature is supported in base library 1.9.90 and later.

This feature can be used to implement, for example, the hover-class property of the view component: a style class can be provided in the page to specify value for the hover-class of view, which is written in the page instead of being implemented in the view component.

Note: Avoid using an ordinary style class and an external style class on the same node because their priorities are not defined.

Code example:

/* Component custom-component.js */
Component({
  externalClasses: ['my-class']
})

<!-- Component custom-component.wxml -->
<custom-component class="my-class">The color of this text is determined by the  class  outside the component</custom-component>

Therefore, the component user can specify the class corresponding to this style class, just like using ordinary properties. From base library 2.7.1 and later, multiple corresponding classes can be specified.

Code example:

Preview with Developer Tool

<!-- Page's WXML -->
<custom-component my-class="red-text" />
<custom-component my-class="large-text" />
<!-- The following code is supported as of base library 2.7.1 -->
<custom-component my-class="red-text large-text" />

.red-text {
  color: red;
}
.large-text {
  font-size: 1.5em;
}