How Taro Transforms CSS for HarmonyOS: Bridging React and ArkUI

Background

HarmonyOS uses the proprietary ArkUI framework for native UI, which follows its own layout and style system that diverges from the W3C CSS standard. Directly applying HarmonyOS styles in Taro would cause many compatibility issues, so bridging the gap between ArkUI and CSS is essential.

Differences between CSS and ArkUI CAPI styles

1. Inconsistent syntax

Examples show that CSS units and color formats differ from ArkUI’s unified vp unit and 0xAARRGGBB color representation. ArkUI also requires complex properties such as gradients, transforms, and animations to be expressed as data structures.

2. Layout differences

ArkUI’s layout properties differ from CSS, e.g., absolute positioning is relative to the parent, early versions lack right and bottom, and features like calc() are missing. To unify layout handling, Taro adopts the Yoga engine, building a parallel Yoga node tree, computing dimensions, and syncing the results back to ArkUI nodes.

Style Workflow

Style Initialization

After the project starts, compiled style files are loaded, and a stylesheet is turned into StyleRule objects representing CSS property key‑value pairs.

Matching StyleRule by ClassName

During React reconciliation, each node’s className and inline style are merged with matching StyleRule s from the stylesheet, respecting selector specificity.

Pseudo‑elements and keyframe animations are transformed into additional nodes or separate animation threads, ensuring correct priority.

Applying Styles

Matched rules are applied via SetStyle. Layout‑related properties are sent to the Yoga node and marked layout_dirty; paint‑related properties are stored on the node and marked draw_dirty. The dirty nodes are processed in the next frame, where Yoga computes new layouts and the results are written back to the HarmonyOS nodes.

Updating Styles

When style changes, a new inline style is generated and merged with class‑based rules. When className changes, affected selectors are re‑matched, and only the impacted nodes (self, direct children, or descendants) are marked dirty and updated in the next frame, reducing redundant work.

.E .G {}</code><code>.E .H {}</code><code>.I > .J {}</code><code>.I {}

Conclusion

The article details how Taro bridges CSS and ArkUI, handling syntax mismatches, layout translation via Yoga, and an efficient runtime style system that preserves cross‑platform compatibility while delivering high performance on HarmonyOS.