Flutter Widget Previewer: Now Stable in Flutter 3.47

Iterating on individual widgets shouldn’t require building and launching your entire application. Flutter Widget Previewer, now stable in Flutter 3.47, lets you instantly render, inspect, and iterate on UI components in isolation.

What Is Widget Preview?

Widget Previewer allows you to annotate widgets with @preview and see them rendered in real-time, separate from your full app. This is a game-changer for UI development — no more running the entire app just to check how a button looks with different themes.

Getting Started

Annotate a Widget

import 'package:flutter/widgets.dart';

@preview
class MyButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {},
      child: Text('Preview Me'),
    );
  }
}

The @preview annotation marks the widget for preview detection.

Open the Previewer

In VS Code:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
2. Run Flutter: Open Widget Preview.

In Android Studio:

1. Go to Tools > Flutter > Open Widget Preview.

From command line:

flutter widget-preview

Stable Features

The stable release brings several improvements:

Faster Startup

Local project caching in a .widget_preview/ folder eliminates repeated setup overhead. Subsequent launches are significantly faster.

Theme Layering

The abstract PreviewThemeData API supports sequential theme layering for complex matrix tests:

@preview
Widget myWidget() => MyWidget();

@preview
Widget myWidgetDark() => Theme(
  data: ThemeData.dark(),
  child: MyWidget(),
);

Web Asset Synchronization

When previewing web widgets, the previewer automatically copies your host project’s web/ assets, applying any custom theming or index.html customization.

Search and Filter

Filter previews by group, name, and script/package URIs — essential for projects with many previews.

Light/Dark Mode Toggle

Switch between light and dark themes instantly to verify your widget looks correct in both modes.

IDE Integration

Widget Previewer integrates with your IDE for a seamless experience:

• VS Code: Full integration with the Flutter extension.
• Android Studio: Built-in support via the Flutter plugin.
• Detected automatically: The Dart Analysis Server handles preview detection, reducing memory usage by up to 50%.

Custom Preview Annotations

Create your own preview annotations for specific use cases:

class PreviewConfig {
  final double width;
  final double height;
  final bool showDarkMode;
  
  const PreviewConfig({
    this.width = 300,
    this.height = 200,
    this.showDarkMode = true,
  });
}

Multiple Configurations

A single widget can have multiple preview configurations, showing it at different sizes, with different themes, or in different states:

@preview(name: 'Default')
Widget button() => MyButton();

@preview(name: 'Disabled')
Widget buttonDisabled() => MyButton(enabled: false);

@preview(name: 'Large')
Widget buttonLarge() => MyButton(textScale: 2.0);

Limitations

Widget Previewer works best for stateless widgets and simple stateful widgets. Complex interactions, platform-specific code, and full app state are better tested through integration tests.

Why This Matters

Widget Previewer closes the gap between “write code” and “see result” for UI components. Instead of:

1. Save file.
2. Wait for hot reload.
3. Navigate to the right screen.
4. Check the widget.

You get:

1. Save file.
2. See the preview update instantly.

This is particularly valuable for design system development, component libraries, and any workflow where visual iteration is frequent.

Sources:

• Flutter Widget Previewer Documentation
• What’s new in Flutter 3.47