Hybrid UI

WebF’s Hybrid UI system allows you to seamlessly mix WebF app content with native Flutter widgets. Use high-performance, platform-perfect Flutter components directly within your WebF app UI for the best of both worlds.

How It Works

Unlike libraries that emulate a native look with CSS, WebF renders the actual native widgets. This is achieved through a powerful custom element bridge:

1. Native Widget Wrappers: In the underlying Flutter engine, a native widget (like Flutter’s CupertinoButton) is wrapped in a special Dart class.
2. Custom Element Binding: This Dart wrapper is registered with WebF as a custom HTML element (e.g., <flutter-cupertino-button>).
3. Rendering: When WebF encounters this custom tag in your application, it instructs the Flutter engine to render the real native widget in its place.
4. Props and Styling: HTML attributes and CSS styles you apply to the custom element are passed down to the native widget, allowing you to configure and style it from your web code.
5. Events: When you interact with the native widget (e.g., by pressing it), the widget emits a standard DOM event (like click), which your JavaScript code can listen for.

Example: Using a Cupertino Button in React

The easiest way to use these native widgets is with a pre-packaged npm library that provides convenient wrappers for your chosen framework. The @openwebf/react-cupertino-ui package does exactly this for React.

First, install the package:

npm install @openwebf/react-cupertino-ui

Now, you can import and use the components just like any other React component.

import React from 'react';
import { FlutterCupertinoButton } from '@openwebf/react-cupertino-ui';
 
function MyCupertinoApp() {
  const handleClick = () => {
    console.log('Native Cupertino button was clicked!');
  };
 
  return (
    <div>
      <h2>A real native iOS-style button:</h2>
      <FlutterCupertinoButton
        onClick={handleClick}
        style={{
          width: '200px',
          height: '50px',
          fontSize: '18px',
        }}
      >
        Press Me
      </FlutterCupertinoButton>
    </div>
  );
}

When this component renders, you are not seeing a <div> styled to look like a button. You are seeing the actual, high-fidelity CupertinoButton widget from Flutter, rendered right inside your WebF app layout. This ensures perfect visuals, accessibility, and native performance.

Available Components

The @openwebf/react-cupertino-ui package provides React wrappers for many common iOS-style (Cupertino) widgets:

• Buttons: FlutterCupertinoButton, FlutterCupertinoFilledButton
• Form Controls: FlutterCupertinoTextField, FlutterCupertinoSwitch, FlutterCupertinoSlider
• Navigation: FlutterCupertinoNavigationBar, FlutterCupertinoTabBar
• Indicators: FlutterCupertinoActivityIndicator
• And many more…

Refer to the package documentation for a complete list of available components and their props.

Creating Custom Hybrid UI Components

Creating your own hybrid UI packages is an advanced and powerful feature of WebF. You can wrap any Flutter widget and make it available as a custom HTML element in your web code.

This process involves:

1. Writing Dart code to wrap your Flutter widget
2. Using WebF’s code generation tools to create the bindings
3. Publishing the result as an npm package

For detailed instructions, please see the Hybrid UI Development Guide (coming soon).

Best Practices

• Use for Performance-Critical UI: Flutter widgets are ideal for complex interactions, animations, or lists that need to scroll smoothly.
• Mix with WebF App Content: You can freely mix Flutter widgets with standard HTML/CSS. For example, use a Flutter button inside a WebF app form.
• Styling: While you can apply some CSS styles to Flutter widgets, not all CSS properties will affect them. Refer to the widget documentation for supported styling options.
• Platform Considerations: Some widgets (like Cupertino components) are designed for specific platforms. Consider providing platform-appropriate alternatives when needed.