npx skills add ...
npx skills add flutter/agent-plugins --skill flutter-add-widget-preview
npx skills add flutter/agent-plugins --skill flutter-add-widget-preview
Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing.
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context.
@Preview annotation to top-level functions, static methods within a class, or public widget constructors/factories that have no required arguments and return a Widget or WidgetBuilder.package:flutter/widget_previews.dart to access the preview annotations.Preview class to create custom annotations that inject common properties (e.g., themes, wrappers) across multiple widgets.@Preview annotations to a single target to generate multiple preview instances. Alternatively, extend MultiPreview to encapsulate common multi-preview configurations.transform() method in custom Preview or MultiPreview classes to modify preview configurations dynamically at runtime (e.g., generating names based on dynamic values, which is impossible in a const context).Adhere to the following constraints when authoring previewable widgets, as the Widget Previewer runs in a web environment:
dart:io or dart:ffi. Widgets with transitive dependencies on dart:io or dart:ffi will throw exceptions upon invocation. Use conditional imports to mock or bypass these in preview mode.dart:ui fromAsset APIs (e.g., packages/my_package_name/assets/my_image.png instead of assets/my_image.png).size parameter in the @Preview annotation if your widget is unconstrained, as the previewer defaults to constraining them to approximately half the viewport.Copy and track this checklist when implementing a new widget preview:
package:flutter/widget_previews.dart.@Preview annotation to the target.name, group, size, theme, brightness, etc.) as needed.Preview.Follow the appropriate conditional workflow to launch and interact with the Widget Previewer:
If using a supported IDE (Android Studio, IntelliJ, VS Code with Flutter 3.38+):
If using the Command Line:
flutter widget-preview start.Feedback Loop: Preview Iteration
import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';
final class TransformativePreview extends Preview {
const TransformativePreview({
super.name,
super.group,
});
PreviewThemeData _themeBuilder() {
return PreviewThemeData(
materialLight: ThemeData.light(),
materialDark: ThemeData.dark(),
);
}
@override
Preview transform() {
final originalPreview = super.transform();
final builder = originalPreview.toBuilder();
builder
..name = 'Transformed - ${originalPreview.name}'
..theme = _themeBuilder;
return builder.toPreview();
}
}
@TransformativePreview(name: 'Custom Themed Button')
Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click'));import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart';
/// Creates light and dark mode previews automatically.
final class MultiBrightnessPreview extends MultiPreview {
const MultiBrightnessPreview({required this.name});
final String name;
@override
List<Preview> get previews => const [
Preview(brightness: Brightness.light),
Preview(brightness: Brightness.dark),
];
@override
List<Preview> transform() {
final previews = super.transform();
return previews.map((preview) {
final builder = preview.toBuilder()
..group = 'Brightness'
..name = '$name - ${preview.brightness!.name}';
return builder.toPreview();
}).toList();
}
}
@MultiBrightnessPreview(name: 'Primary Card')
Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')));