Storyteller List Components

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(StorytellerTileType tileType)
• onPlayerDismissed()

StorytellerTileType is either StorytellerStoryTile or StorytellerClipTile. Both expose id, categories, and categoryDetails when the native SDK provides category metadata. Clip tiles also expose collectionId.

Clips layouts

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

Example usage:

const StorytellerClipsRowView(
  collectionId: 'collection',
  cellType: 'square',
  height: 220,
  context: {'placement': 'custom_placement'},
  adConfiguration: StorytellerClipsAdConfiguration(
    preRollEnabled: true,
    bottomBannerEnabled: true,
    betweenClipsAdProviderOrder: [StorytellerAdProvider.gam],
  ),
);

adConfiguration is fixed when the platform view is created and supported on Android only. iOS ignores the entire value because its native Clips list configuration exposes no presentation ad controls. Android 11.6.3 defaults pre-roll on; omit the nullable value to preserve that native default. For provider order, null preserves native order, an empty list disables standard providers for that list presentation, and a populated list restricts and orders them.

The Showcase feed swaps between rows, grids, and singleton layouts from a single StorytellerItemWidget that wires the callbacks above and hides sections with empty data.

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.