Storyteller Lists

Storyteller ships multiple Flutter widgets that mirror the native list experiences. Each widget wraps a platform view, so the iOS and Android SDKs render the UI while Flutter manages sizing, layout, and callbacks.

Stories layouts

Widget	Description	Common parameters
StorytellerStoriesGridView	Scrollable, multi-column grid of stories.	isScrollable, categories, cellType, uiStyle, displayLimit, visibleTiles, theme, context, controller
StorytellerStoriesRowView	Horizontal row of story tiles.	categories, cellType, uiStyle, displayLimit, visibleTiles, height, theme, context, controller

Example usage:

const StorytellerStoriesGridView(
  isScrollable: true,
  categories: ['example'],
  cellType: 'square', // or 'round'
  onTileTapped: handleOnTileTapped,
  onDataLoadStarted: handleLoadStart,
);

Both widgets expose optional callbacks:

• onDataLoadStarted()
• onDataLoadComplete(bool success, Object? error, int dataCount)
• onTileTapped(String id)
• onPlayerDismissed()

Clips layouts

Widget	Description	Common parameters
StorytellerClipsGridView	Grid of clips sourced from a collection.	isScrollable, collectionId, cellType, uiStyle, displayLimit, visibleTiles, theme, context, controller
StorytellerClipsRowView	Horizontal reel of clips.	collectionId, cellType, uiStyle, displayLimit, visibleTiles, height, theme, context, controller

Example usage:

const StorytellerClipsRowView(
  collectionId: 'collection',
  cellType: 'square',
  height: 220,
  context: {'placement': 'custom_placement'},
);

Controlling list refresh

Pass a StorytellerListViewController into any stories or clips list widget when you need to trigger native reloads on demand (for example, after a user signs in or changes preferences).

class CategoryStories extends StatefulWidget {
  const CategoryStories({super.key});

  @override
  State<CategoryStories> createState() => _CategoryStoriesState();
}

class _CategoryStoriesState extends State<CategoryStories> {
  final _controller = StorytellerListViewController();

  @override
  Widget build(BuildContext context) {
    return StorytellerStoriesRowView(
      categories: const ['recommended'],
      controller: _controller,
    );
  }

  Future<void> refreshStories() async {
    await _controller.reloadData();
  }
}

If you call reloadData before the platform view has been created, the controller queues the request and executes it automatically after the widget is ready.