Previews

What are previews?

Previews are widgets. These widgets contain a sample (or multiple-different samples) of your widget.

Its purpose is to offer a quick view of your widget. You can mock any state your widget could need.

Create a basic page for a widget

Creating pages for your catalog is easy. After including a few parameters, you'll have a complete page sample.

Include the @Preview annotation:

sized_container.dart

import 'package:catalog/catalog.dart';
import 'package:flutter/material.dart';

@Preview(
  id: 'SizedContainerPreview',
  path: 'sized/container',
  description: 'Container with a max width of 700',
  parameters: {
    'child': 'dummy_text_small',
  },
)
class SizedContainer extends StatelessWidget {
  final Widget? child;

  const SizedContainer({
    Key? key,
    this.child,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(
      constraints: const BoxConstraints(
        maxWidth: 700,
      ),
      child: child,
    );
  }
}

id: Unique identifier of your catalog page.
path: Catalog route path. In this case sized/container builds catalog/sized/container.
description: Description of your widget page.
parameters: In this sample, our widget only has a single parameter (Widget? child). You can include a basic dummy text widget as a parameter:

parameters: {
  'child': 'dummy_text_small',
},

This sample is really basic. The reality involves more complex scenarios. For working with complex parameters, keep reading how to build the dummy pages.

Generate the preview and dummy files

Catalog works with .preview. and .dummy. files. These files are generated from your widget.

dart run catalog:preview

your_widget_folder
    |
    |-- preview
    |   |
    |   |-- dummy
    |   |   |
    |   |   |-- sized_container.dummy.dart      <-- dummy created (only created if not exist)
    |   |
    |   |-- sized_container.preview.dart        <-- preview created (always regenerated)
    |
    |--sized_container.dart                     <-- widget file