How Taro 3.0 Enables H5‑Web UI Frameworks to Run in Mini‑Programs

Implementation Overview

Taro 3.0 provides a runtime‑focused cross‑platform layer that emulates browser BOM and DOM APIs, enabling React, Vue and other web frameworks to run in mini‑program environments. The core challenge is the mismatch between HTML tags and mini‑program components.

Rendering Pipeline

The data flow is frontend framework → Taro DOM → mini‑program data . The frontend framework remains unchanged; Taro DOM performs mapping when serializing to mini‑program data.

Tag Mapping

HTML tags are treated as a subset of mini‑program components. A rule‑based conversion maps tags, e.g.:

{
  nn: 'img'
} → {
  nn: 'image'
}

Full tag‑mapping rules are documented in RFC Appendix 1.

Attribute Mapping

When an HTML attribute has an equivalent in the target component, it is translated, e.g.:

{
  nn: 'a',
  href: 'xxx',
  target: '_blank'
} → {
  nn: 'navigator',
  url: 'xxx',
  openType: 'navigate'
}

See RFC Appendix 2 for the complete list.

Event Mapping

HTML events are mapped to mini‑program events (e.g., click → tap). Full rules are in RFC Appendix 3.

Style Handling

Because CSS tag selectors become ineffective after mapping, Taro prefixes class names with h5-${tagName} and uses a PostCSS plugin to rewrite selectors. Two built‑in style sheets are provided: @tarojs/taro/html.css: lightweight HTML4 defaults. @tarojs/taro/html5.css: richer HTML5 defaults (larger bundle, not supported by all mini‑program containers).

Key Limitations

Element size retrieval : Web APIs like getBoundingClientRect are synchronous, while mini‑program APIs are asynchronous, preventing direct reuse of components that rely on synchronous size queries.

DOM API differences : Elements such as <canvas>, <video>, <audio> require creating a Taro Context (e.g., const ctx = Taro.createVideoContext('myVideo'); ctx.play();).

Style restrictions : Wildcard selectors, media queries, and non‑native attribute selectors are not supported in mini‑programs.

Usage Guide

Upgrade to 3.3.0‑alpha

npm i -g @tarojs/cli@alpha

Update package.json to version ^3.3.0-alpha.2 and reinstall dependencies (remove node_modules first).

Install the HTML‑compatibility plugin

npm i @tarojs/plugin-html

Add the plugin to config/index.js:

const config = {
  // ...
  plugins: ['@tarojs/plugin-html']
}

Demo Projects

Compatibility was evaluated with three UI libraries:

WEUI – repository https://github.com/NervJS/taro-weui. High CSS compatibility; most components work out‑of‑the‑box.

Ant Design Mobile – repository https://github.com/NervJS/taro-antd-mobile. Approximately 80% of components are usable; limitations include lack of SVG support and reliance on synchronous size queries.

VantUI – repository https://github.com/NervJS/taro-vant. Roughly 70% component compatibility; challenges involve missing SVG icons, synchronous size queries, and Vue <transition> adaptation.

Reference Materials

RFC Appendix 1 (tag mapping): https://github.com/NervJS/taro-rfcs/blob/html-support/rfcs/0004-rendering-html.md#%E4%B8%80%E6%A0%87%E7%AD%BE%E5%90%8D%E5%BD%B1%E5%B0%84

RFC Appendix 2 (attribute mapping): https://github.com/NervJS/taro-rfcs/blob/html-support/rfcs/0004-rendering-html.md#%E4%BA%8C%E5%B1%9E%E6%80%A7%E5%90%8D%E5%BD%B1%E5%B0%84

RFC Appendix 3 (event mapping): https://github.com/NervJS/taro-rfcs/blob/html-support/rfcs/0004-rendering-html.md#%E4%B8%89%E4%BA%8B%E4%BB%B6%E5%BD%B1%E5%B0%84

taro-weui repository: https://github.com/NervJS/taro-weui

taro-antd-mobile repository: https://github.com/NervJS/taro-antd-mobile

taro-vant repository: https://github.com/NervJS/taro-vant

Co‑creation discussion (RFC): https://github.com/NervJS/taro/discussions/9029