Taming Large Widget Libraries: Search and Filter in the Flutter Widget Previewer

The Widget Previewer is delightful with five previews and unwieldy with five hundred. In a real design system — every button variant, every card state, every icon size annotated with @Preview — the preview environment fills with tiles faster than you can scan them. That is exactly the problem the previewer’s search and filtering features exist to solve, and they are more capable than a simple substring match.

Source: Flutter Widget Previewer, The Flutter Team, docs.flutter.dev.

The search bar and its criteria

The previewer environment has a search bar at the top that filters previews in real time. The important detail is the filter dropdown beside it: you choose which field to match against, not just what text to match. The available criteria are:

• Preview name — the descriptive name set in the @Preview annotation.
• Group name — the group value you passed to @Preview(group: ...).
• Containing script — the URI of the Dart file holding the preview.
• Containing package — the package name that contains the preview.

The power comes from combining name and group deliberately. Annotate related previews with a shared group, and the group filter becomes a component-library view:

@Preview(name: 'Submit Button', group: 'Form Controls')
Widget submitButtonPreview() => const SubmitButton();

@Preview(name: 'Text Field', group: 'Form Controls')
Widget textFieldPreview() => const TextFormField();

Filtering by Group name = Form Controls collapses the environment down to just that family. In a large library, grouping is not cosmetic metadata — it is the primary navigation axis.

Filter by selected file

Inside an IDE, the previewer adds a second, context-aware filter: Filter previews by selected file. Toggle it on at the bottom of the environment, and the previewer shows only previews contained in the Dart file you currently have open.

This changes the editing loop meaningfully. Instead of searching, you open submit_button.dart and the environment automatically narrows to the submit-button previews defined in that file. Edit, hot-restart that preview, move on. It turns the previewer from a global gallery into a per-file workbench that tracks where your cursor already is.

The toggle lives at the bottom of the environment precisely because it is an IDE-coupled behavior — it depends on knowing the active editor tab, so it is meaningful when launched from Android Studio, IntelliJ, or VS Code rather than from the bare CLI.

Design the annotations for findability

The filtering features reward annotating with structure in mind. A few habits pay off across a large library:

• Always set name. A preview named myPreview01 is invisible to a human scanning the list. Name previews the way you would name a test.
• Group by component family, not by file. group: 'Form Controls' is more useful than group: 'buttons.dart', because it survives refactors and matches how people think about the library.
• Let group names nest conceptually. You can encode hierarchy in the string — 'Form Controls/Buttons' — and still match on a prefix when filtering.

Where this fits

None of these features replace the code. They make the annotation layer — the thing that turns a widget library into an inspectable catalog — scale. Combined with the per-preview controls (zoom, light/dark toggle, per-preview hot restart) and the wrapper and theme parameters for injecting state and theming into a preview, search and filtering are what make the Widget Previewer viable as a living design-system browser rather than a demo toy.

Key takeaways

The Widget Previewer’s search bar matches on preview name, group name, containing script, or containing package — and group-based filtering is the key to navigating a large library. In IDEs, “filter by selected file” narrows the environment to whichever Dart file you have open, turning the previewer into a per-file workbench. The leverage comes from annotating deliberately: meaningful name values and component-family group values make the whole catalog scannable.

Further reading

• Flutter Widget Previewer
• @Preview API
• What’s new in Flutter 3.47