Flutter Widget Previews are stable: a practical guide to @Preview
Widget Previews shipped as experimental back in 3.35, and a lot of developers tried it once, found it slow, and went back to hot reload. Flutter 3.47 marks it stable, with local build caching and an abstract theming API that makes the feature worth a second look. If you build design systems, component libraries, or anything with more than three visual states, this changes your inner loop.
The pitch is narrow and honest: the previewer renders individual widgets in isolation, without booting your app, navigating to the right screen, or faking the right state. That is a different job from hot reload, and it is the job hot reload has always been bad at.
Starting the previewer
From your IDE — Android Studio, IntelliJ, or VS Code — the previewer starts automatically; open the Flutter Widget Preview tab in the sidebar. From a terminal:
flutter widget-preview startThat launches a local server and opens a live preview environment in your browser. Builds are cached in a .widget_preview/ folder in your project — this cache is the reason startup got noticeably faster in 3.47, and it is the thing to add to .gitignore if your tooling has not already.
What you can annotate
@Preview comes from package:flutter/widget_previews.dart and can be applied to:
- top-level functions returning a
WidgetorWidgetBuilder - static methods in a class returning a
WidgetorWidgetBuilder - public widget constructors and factories that take no required arguments
The simplest possible case:
import 'package:flutter/material.dart';
import 'package:flutter/widget_previews.dart';
@Preview(name: 'My Sample Text')
Widget mySampleText() {
return const Text('Hello, World!');
}No app, no MaterialApp, no route. Save the file and the preview updates.
Every parameter, and what it is actually for
The Preview class is small, which is a good sign. Here is the full surface:
| Parameter | Type | What it does |
|---|---|---|
group | String | Groups related previews in the UI. Defaults to 'Default'. |
name | String? | Label shown beside the preview. |
size | Size? | Artificial constraints applied to the widget. |
textScaleFactor | double? | Font scaling, for accessibility checks. |
wrapper | WidgetWrapper? | Wraps the widget in a tree — scaffolds, providers, InheritedWidget. |
theme | PreviewTheme? | Returns Material and Cupertino theming data to apply. |
brightness | Brightness? | Initial light/dark brightness. |
localizations | PreviewLocalizations? | Localization configuration for the preview. |
wrapper is the one that makes previews usable in a real codebase. Most widgets are not standalone — they expect a Scaffold, a theme, or an injected repository. You supply that once:
@Preview(
name: 'Submit button — pressed state',
group: 'Form Controls',
size: Size(240, 56),
textScaleFactor: 1.5,
wrapper: _inScaffold,
)
Widget submitButtonPreview() => const SubmitButton(isBusy: true);
Widget _inScaffold(Widget child) => MaterialApp(
home: Scaffold(body: Center(child: child)),
);Rendering the same widget many ways
This is where previews beat hot reload outright. Stack annotations to get one widget rendered under several configurations at once:
@Preview(group: 'Brightness', name: 'Light', brightness: Brightness.light)
@Preview(group: 'Brightness', name: 'Dark', brightness: Brightness.dark)
Widget buttonPreview() => const ButtonShowcase();When the same three or four variants repeat across dozens of components, promote them to a MultiPreview:
final class MultiBrightnessPreview extends MultiPreview {
const MultiBrightnessPreview();
@override
List<Preview> get previews => const [
Preview(group: 'Brightness', name: 'Light', brightness: Brightness.light),
Preview(group: 'Brightness', name: 'Dark', brightness: Brightness.dark),
];
}
@MultiBrightnessPreview()
Widget buttonPreview() => const ButtonShowcase();Baking your design system into a custom annotation
The abstract theme API added in 3.47 is the piece that makes this scale. Rather than repeating theme: on every preview, subclass Preview and supply the builder once:
final class MyCustomPreview extends Preview {
const MyCustomPreview({
super.name,
super.group,
super.size,
super.textScaleFactor,
super.wrapper,
super.brightness,
super.localizations,
}) : super(theme: MyCustomPreview.themeBuilder);
static PreviewThemeData themeBuilder() {
return PreviewThemeData(
materialLight: ThemeData.light(),
materialDark: ThemeData.dark(),
);
}
}Now every @MyCustomPreview(...) in the codebase renders against your real tokens. PreviewThemeData carries both Material and Cupertino data, which matters more in 3.47 than it used to — with the design system moving into standalone material_ui and cupertino_ui packages, previews are a cheap way to see whether a component actually survives both.
There is also transform(), which lets a custom annotation rewrite the preview at runtime — useful for prefixing names or swapping themes across a whole class of previews without touching call sites.
Previews are not golden tests
Worth being blunt about this, because teams confuse the two. Previews are an authoring tool: fast, visual, human-in-the-loop, no assertions. Golden tests are a regression tool: slow, headless, and they fail your CI when a pixel moves. Previews do not replace goldens, and a preview passing means nothing except that it rendered.
The useful pairing is previews while you build the component, goldens once its states are settled.
The limitations you will hit
The previewer runs in a web-based environment, which sets hard boundaries:
- No native plugins, and no
dart:ioordart:ffi. Anything touching the filesystem, platform channels, or FFI will not render — inject a fake throughwrapperinstead. - Callback arguments must be public and constant. Private closures will not be picked up.
- Asset paths must be package-based: use
'packages/my_package_name/assets/my_image.png', not'assets/my_image.png'. - Unconstrained widgets are automatically clamped to roughly 50% of the previewer’s height and width. Pass
sizewhen that squashes your layout. - Single project or Pub workspace only. Multi-project IDE support is still being investigated, so a large monorepo may not light up entirely.
Adopting it without a rewrite
- Upgrade to 3.47 and run
flutter widget-preview startonce to confirm the previewer builds your project. - Add
.widget_preview/to.gitignore. - Pick one leaf component — a button, a badge, a list tile — and add a single
@Preview. Do not start with a screen. - Write one
wrapperthat installs your app’s theme and providers, and reuse it. - Promote your recurring variants (light/dark, text scale 1.0/2.0, LTR/RTL) into a
MultiPreview. - Subclass
Previewwith your design system’sPreviewThemeDataand standardise on that annotation. - Add goldens for the states you now know are correct.
The bottom line
Widget Previews stopped being a demo in 3.47. The caching makes startup tolerable, and the theme APIs are the difference between a toy and something a design-system team can standardise on. The limitations are real — no native code, package-based asset paths, single-workspace — but they are limitations of scope, not of maturity. If you tried previews in 3.35 and shrugged, the honest advice is to try again: this is the release where the feature earns its place in the loop.
Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.