Skip to Content
DocsAdd WebF To FlutterEmbedding WebF

Embedding WebF in Flutter

Learn how to integrate WebF widgets into your Flutter application’s widget tree and handle layout constraints.

Integrating WebF into Your Widget Tree

Typical Usage: WebF apps usually take the full screen in Flutter apps. The most common pattern is to use WebF with go_router for full-screen navigation between routes.

// Most common pattern - WebF takes full screen with go_router
MaterialApp.router(
  routerConfig: GoRouter(
    routes: [
      GoRoute(
        path: '/:webfPath(.*)',
        pageBuilder: (context, state) {
          final path = '/${state.pathParameters['webfPath']}';
          final controller = WebFControllerManager.instance.getControllerSync('app')!;
 
          return MaterialPage(
            child: WebFSubView(
              path: path,
              controller: controller,
              onAppBarCreated: (title, routeLinkElement) => AppBar(
                title: Text(title),
              ),
            ),
          );
        },
      ),
    ],
  ),
)

Basic Full-Screen Setup

Scaffold(
  body: WebF.fromControllerName(
    controllerName: 'home',
  ),
)

Advanced: Partial Screen Usage

While less common, you can embed WebF in partial screen layouts for specialized use cases:

// In a Column with Flutter widgets
Column(
  children: [
    Text('Flutter Header'),
    Expanded(
      child: WebF.fromControllerName(
        controllerName: 'content',
      ),
    ),
    ElevatedButton(
      onPressed: () {},
      child: Text('Flutter Button'),
    ),
  ],
)
 
// Overlay with Flutter UI
Stack(
  children: [
    WebF.fromControllerName(
      controllerName: 'background',
    ),
    Positioned(
      top: 20,
      right: 20,
      child: FloatingActionButton(
        onPressed: () {},
        child: Icon(Icons.add),
      ),
    ),
  ],
)

Note: For most apps, full-screen WebF with internal routing (using @openwebf/react-router) is the recommended approach rather than multiple partial WebF widgets.

Handling Layout, Sizing, and Constraints

WebF respects Flutter’s constraint system. Understanding how constraints flow is crucial:

Fill Available Space (Most Common)

// WebF will fill its parent's constraints
Expanded(
  child: WebF.fromControllerName(controllerName: 'home'),
)

Fixed Size

SizedBox(
  width: 400,
  height: 600,
  child: WebF.fromControllerName(controllerName: 'card'),
)

Responsive Sizing

LayoutBuilder(
  builder: (context, constraints) {
    return SizedBox(
      width: constraints.maxWidth,
      height: constraints.maxHeight * 0.7,  // 70% of parent height
      child: WebF.fromControllerName(controllerName: 'content'),
    );
  },
)

Inside Scrollable (Important!)

When embedding WebF in scrollable widgets, you must give it a fixed height:

// ❌ BAD - Will cause layout errors
ListView(
  children: [
    WebF.fromControllerName(controllerName: 'article'),
  ],
)
 
// ✅ GOOD - Fixed height
ListView(
  children: [
    SizedBox(
      height: 500,
      child: WebF.fromControllerName(controllerName: 'article'),
    ),
  ],
)

Viewport Sizing in WebF Apps

The WebF app inside the widget sees the widget’s constraints as viewport size:

// Flutter code - 300x400 widget
SizedBox(
  width: 300,
  height: 400,
  child: WebF.fromControllerName(controllerName: 'box'),
)
 
// In your WebF app code:
// window.innerWidth === 300 (in CSS pixels)
// window.innerHeight === 400 (in CSS pixels)
// 100vw === 300px
// 100vh === 400px

Handling Different Screen Sizes

// Responsive WebF app
MediaQuery.of(context).size.width < 600
  ? SizedBox(
      width: MediaQuery.of(context).size.width,
      height: 500,
      child: WebF.fromControllerName(controllerName: 'mobile_view'),
    )
  : SizedBox(
      width: MediaQuery.of(context).size.width,
      height: 800,
      child: WebF.fromControllerName(controllerName: 'desktop_view'),
    )

Hybrid UI: Adding Flutter Widgets to WebF

For detailed information on creating custom Flutter widgets that can be used in your WebF apps, see the Hybrid UI documentation, which covers:

  • Overview of the Hybrid UI approach
  • Workflow with webf codegen
  • Handling children in custom elements (single, multiple, slotted patterns)
  • Managing infinite layout constraints
  • Advanced patterns for popups, dialogs, and modals

The Bridge: Adding Flutter Plugins to WebF

For detailed information on exposing Dart APIs and Flutter plugins to JavaScript, see the Build Native Plugins guide, which covers:

  • Overview of exposing Dart services
  • Automatic binding generation with webf module-codegen
  • Creating typed npm packages for your modules
  • Complete examples (Share, DeepLink modules)

Next Steps

Core ConceptsBuild Hybrid UI Components