Skip to main content

Write your first story

Monarch is inspired by Storybook. Conceptually, Monarch stories are the same as Storybook stories. If you are familiar with Storybook, then Monarch will feel very familiar.

You can write stories for every interesting or relevant state your widgets may have.

Stories in code​

Stories are simple functions that return a Widget and take zero arguments. You don't need to import the monarch package to write a story.

Also, since stories are plain functions, they can be re-used from your widget tests.

Where to put stories​

Monarch will look for stories in dart files that end with *_stories.dart.

You can place stories inside the stories directory or, if you prefer, you can place them inside your lib directory. The only requirement is that story files should end in *_stories.dart.

Sample stories​

The monarch init command creates the file stories\sample_button_stories.dart. You can open that file to see how those stories are written. After you run monarch run you should see those stories in the Monarch desktop app.

You should see something like this:

my_project macOS sample stories

Feel free to edit those stories to see their visual state change. Monarch will automatically reload your changes.

Stories for your own widgets​

Let's say your project has a couple of widgets files. One is inside lib and one inside lib\src.

- my_project
    - lib
        - my_fancy_button.dart
        - src
            - my_fancy_card.dart

To write stories for those widgets, you just need to import them into a *_stories.dart file, then you can write stories for those widgets.

// stories/my_stories.dart
import 'package:my_project/my_fancy_button.dart';
import 'package:my_project/src/my_fancy_card.dart';

Widget someButton => MyFancyButton(...);
Widget anotherButton => MyFancyButton(...);

Widget someCard => MyFancyCard(...);
Widget anotherCard => MyFancyCard(...);

After you run monarch run you should see those stories in the Monarch desktop app.

Stories for quick prototypes​

You can write stories that use the Flutter widgets directly. It is a good way to prototype new views. For example, in a file that ends in *_stories.dart, you can add these stories:

Widget foo() => Text('foo', style: TextStyle(fontSize: 50));
Widget bar() => Icon(Icons.pets, size: 50);
Widget foobar() => Center(child: Column(children: [foo(), bar()]));