Embedding Flutter Widgets as Custom Elements in Kraken for High‑Performance Web Rendering

Background

Component encapsulation and development greatly improve front‑end development efficiency. Teams create reusable UI modules and Flutter widgets, aiming to combine Web development dynamism with native‑level performance.

Kraken is a high‑performance, extensible Web standard rendering engine that follows W3C standards. While Web Components enable reusable custom elements, they lack native‑level optimizations, leaving room for deeper integration with Flutter.

Because Kraken is built on Flutter technology, the question arises: can we reuse Flutter widgets within Kraken to create a hybrid, high‑performance, easily extensible front‑end system?

Implement a Flutter Widget as a Custom Element

Developers extend WidgetElement to create a FlutterContainerWidgetElement and register it with defineCustomElement. The element’s build method receives updated attributes and children, rebuilds the Flutter widget, and updates the UI.

Below is a demo that implements a Column widget as a ColumnWidgetElement custom element.

void main() {
  Kraken.defineCustomElement('flutter-column', (context) {
    return ColumnWidgetElement(context);
  });
}

// Extend WidgetElement to implement the custom element.
class ColumnWidgetElement extends WidgetElement {
  ColumnWidgetElement(EventTargetContext? context) : super(context);

  @override
  Widget build(BuildContext context, Map<String, dynamic> properties, List<Widget> children) {
    return Column(
      textDirection: properties['direction'] ? TextDirection.ltr : TextDirection.ltr,
      children: children,
    );
  }
}

Front‑end developers can then create and use the element in JavaScript:

const column = document.createElement('flutter-column');
document.body.appendChild(column);
for (let i = 0; i < 10; i++) {
  column.appendChild(document.createTextNode(i));
}

Technical Principles

Kraken’s rendering pipeline mirrors the classic three‑tree model (CSSOM, DOM, Render Object). Flutter follows a similar three‑tree model (Widget, Element, RenderObject). The two render object trees are independent, so direct nesting is impossible without an adapter.

An adapter bridges the DOM, Widget, Flutter Element, and Render Object trees, allowing each node’s render object to attach to its parent’s render object, achieving mixed rendering.

The relationship among the four trees is illustrated below (images omitted for brevity).

Key scenarios include:

Element as a container appends a Flutter widget.

Flutter widget as a container appends an Element (text node).

Flutter widget as a container appends another Flutter widget.

Flutter widget as a container appends an Element, which further appends a Flutter widget.

Element as a container appends another Element (text node).

Kraken creates a rootFlutterElement to store the Flutter element pointer. It also initializes Window, Document, Body, and Head nodes with corresponding render objects.

When a Flutter widget is inserted into the DOM, a WidgetElement creates a stateful widget ( _KrakenAdapterWidget) that triggers rebuilds on attribute changes or child modifications. The adapter wraps child nodes, converting Flutter widgets or ordinary DOM nodes into appropriate Flutter elements.

Ordinary DOM elements are transformed into KrakenElementToWidgetAdaptor widgets, which generate Flutter elements that directly return the original DOM render objects, ensuring seamless integration.

Advanced: More Complex Scenarios

Using Flutter Widget to Optimize Waterfall‑Flow Performance

By registering a Flutter waterfall‑flow widget as a custom element, front‑end developers can create a high‑performance scrolling container without extra effort, while the widget handles dynamic render‑object recycling.

void main() {
  Kraken.defineCustomElement('flutter-container', (context) {
    return EasyRefreshWidgetElement(context);
  });
}

class EasyRefreshWidgetElement extends WidgetElement {
  EasyRefreshWidgetElement(EventTargetContext? context)
      : super(context, defaultStyle: {'height': '100vh', 'display': 'block'});

  @override
  Widget build(BuildContext context, Map<String, dynamic> properties, List<Widget> children) {
    return EasyRefresh(
      child: WaterfallFlow.builder(
        itemCount: children.length,
        itemBuilder: (BuildContext ctx, int index) => children[index],
        padding: EdgeInsets.all(5.0),
        gridDelegate: SliverWaterfallFlowDelegateWithFixedCrossAxisCount(
          crossAxisCount: 2,
          crossAxisSpacing: 5.0,
          mainAxisSpacing: 5.0,
        ),
      ),
      onRefresh: () async => dispatchEvent(Event('refresh')),
      onLoad: () async => dispatchEvent(Event('load')),
    );
  }
}

Front‑end code to create and listen to the element:

const flutterContainer = document.createElement('flutter-container');
flutterContainer.addEventListener('refresh', () => {});

Conclusion

Kraken follows W3C standards while integrating Flutter’s rendering capabilities, creating a hybrid front‑end ecosystem that leverages the strengths of both Web and native technologies. This enables rapid development, high performance, and extensibility, with all code open‑source for community collaboration.

Kraken GitHub: https://github.com/openkraken/kraken

Kraken website: https://openkraken.com/