Flutter Widget Previewer: Real-Time UI Iteration Without Running the Full App

Coding Liquids tutorial cover featuring Sagnik Bhattacharya for Flutter Widget Previewer, with isolated UI previews and rapid-iteration visuals.
Coding Liquids tutorial cover featuring Sagnik Bhattacharya for Flutter Widget Previewer, with isolated UI previews and rapid-iteration visuals.

Flutter Widget Previewer lets you iterate on a widget in isolation, without constantly rebuilding the whole app or navigating to the screen that contains it. It started as an experimental tool and is stable as of Flutter 3.47. Use it to tune a widget's states, spacing and theme behaviour in a fast loop.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

That saves a surprising amount of friction when you are adjusting spacing, states, copy, or theme behaviour. It does not replace real-device testing, but it can remove a lot of slow feedback loops from day-to-day UI work.

Note: Tooling details can shift between Flutter and IDE releases. Widget Previewer is stable as of Flutter 3.47, having started out as an experimental tool. Treat this guide as current as of 25 September 2026 and check the latest Flutter tooling notes if your setup behaves differently.

What is Flutter Widget Previewer used for?

Use Flutter Widget Previewer to shorten the edit-check-adjust loop for individual widgets and common states. Keep using emulator, device, and integration testing for navigation, lifecycle, performance, accessibility, and cross-screen behaviour.

  • You are tuning layout, state variants, or theme behaviour on one widget.
  • You want faster visual feedback than a full app run can give you.
  • You still plan to verify the result in the actual app afterwards.

Why is Flutter Widget Previewer useful in real teams?

Flutter Widget Previewer helps real teams through focus as well as speed, because a preview encourages you to think in states: loading, empty, error, compact, dense, long text, dark theme, accessibility scaling. That is a healthier habit than only checking the happy path on one route.

It also pairs well with a feature-first structure because isolated widgets become easier to reason about, document, and test. If architecture is your next bottleneck, Flutter app architecture in 2026 is the logical follow-up.

Where does Flutter Widget Previewer save the most time?

Flutter Widget Previewer saves the most time on work that normally forces repetitive setup: open the app, navigate, seed data, reach the right state, change one padding value, and repeat. Previewing a widget short-circuits that loop.

  • Checking how long text wraps on smaller widths.
  • Comparing loading, success, and error states side by side.
  • Testing dark theme and text scaling without bootstrapping the whole route tree.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

What does Flutter Widget Previewer not replace?

Flutter Widget Previewer does not tell you whether navigation works, whether state wiring is correct, or whether the screen still feels right once the full page is assembled. Keep real verification in place.

Use preview for local iteration, then back it up with widget tests, integration tests, and device checks.

Worked example: a reusable order card

Imagine an order card that appears in a list, in search results, and inside an admin dashboard. Without preview, you keep relaunching just to inspect the same component in slightly different states.

With a preview, you can create states for delayed orders, refunded orders, VIP orders, and very long customer names, then settle spacing and hierarchy before returning to the app.

If you want to build real screens like this order card with an instructor, try The Complete Flutter Course on Coding Liquids.

Common mistakes

  • Treating a neat preview as proof that the feature is finished.
  • Previewing only the happy path and missing empty or error states.
  • Skipping device checks for touch targets, performance, and text scaling.

When to use something else

If your main problem is route structure rather than UI iteration, go to go_router deep linking. If the real pain is broad layout adaptation, responsive Flutter UI is the better next read.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

Frequently asked questions

How do I open the Flutter Widget Previewer?

In Android Studio, IntelliJ and VS Code it starts automatically when the IDE launches: open the Flutter Widget Preview tab in the sidebar. From a terminal, run flutter widget-preview start in your project root; it starts a local server and opens the previews in your browser, caching builds in a .widget_preview/ folder so later starts are quicker. The previewer is stable as of Flutter 3.47. It only shows widgets you mark with @Preview or with a custom annotation that extends Preview or MultiPreview.

Why doesn't my widget show up in the Flutter Widget Previewer?

Usually the annotation sits on something the previewer can't use. @Preview, from package:flutter/widget_previews.dart, works only on public top-level functions or static methods that return a Widget or WidgetBuilder, and on public widget constructors or factories with no required arguments. Annotation values must be constant and callbacks public. The previewer also shows previews from a single project or Pub workspace only, and with Filter previews by selected file switched on in your IDE, you see only the selected file's previews.

How do I preview a Flutter widget in dark mode, with large text or at a fixed size?

Set it on the annotation, for example @Preview(name: 'Order card, dark', brightness: Brightness.dark, textScaleFactor: 2.0, size: Size(360, 220)). Give unconstrained widgets a size, because the previewer otherwise limits them to roughly half its own width and height. For several variants of one widget, stack @Preview annotations on the same function, or extend MultiPreview and return them from its previews getter. Each preview also has zoom controls and a light/dark toggle.

How do I preview a widget that reads state from Riverpod or an InheritedWidget?

Use the wrapper parameter: a public top-level or static function of type Widget Function(Widget) that wraps the previewed widget. For Riverpod, write Widget withFakeOrders(Widget child) => ProviderScope(overrides: [ordersProvider.overrideWithValue(fakeOrders)], child: child); and annotate with @Preview(wrapper: withFakeOrders). Where you can, pass sample data through the constructor instead, such as OrderCard(order: refundedOrder), so each state gets its own named preview.

Why does my widget preview fail when it uses a plugin or dart:io?

The previewer is built with Flutter web, so native plugins and dart:io or dart:ffi APIs aren't supported. Widgets that depend on dart:io or dart:ffi still load, but any call into those libraries throws an exception. Keep platform work out of the widget: pass in data or a fake service for the preview, or use conditional imports to swap in a web-safe version. Resources loaded with fromAsset APIs from dart:ui also need package paths, such as packages/my_app/assets/logo.png rather than assets/logo.png.

Does the Flutter Widget Previewer replace widget tests or golden tests?

No. A preview shows you a widget but asserts nothing, and it renders through Flutter web rather than on your target device. Keep testWidgets tests for behaviour such as taps and state changes, golden tests with matchesGoldenFile to compare rendering against a stored reference image, and integration_test runs on a device or emulator for navigation and full flows. Then check touch targets, performance and text scaling on real hardware before you call the screen finished.

This tutorial is one of more than 120 free Flutter tutorials written by Sagnik Bhattacharya, founder of Coding Liquids. For the structured, project-based version, The Complete Flutter Course at codingliquids.com takes you from your first widget to a published Android, iOS and web app, with Riverpod, Firebase, animations and REST APIs covered in real projects.

Related tutorials

If you want to keep going without opening dead ends, these are the most useful next reads from this site.

Official references

These official references are useful if you need the product or framework documentation alongside this guide.