AdvStory Docs
Comment on page

Advanced Usage

This page contains complete usage information of AdvStory widget.
storyCount: 5,
storyBuilder: (index) async {
// Return Story. Explained in next sections.
trayBuilder: (index) {
// Return any widget. AdvStoryTray is a highly customizable
// predefined story tray, you can use this or create your own
// non-animated/animated tray. Explained in next sections.
controller: AdvStoryController(),
buildStoryOnTrayScroll: true,
preloadStory: true,
preloadContent: true,
style: const AdvStoryStyle(),
  • storyCount: count of the stories. trayBuilder and storyBuilder called according to this int value.
  • controller: AdvStoryController, provides methods for controlling story flow.
  • buildStoryOnTrayScroll: Sets whether stories are build when tray list is scrolled or the tray is tapped. Speeds up the opening time of story view on tray tap when this set to true, but increases frequency of the storyBuilder call. If you are requesting data from server in storyBuilder you may want to set this to false to avoid rate limit.
  • preloadStory: Sets whether story preload is enabled. When set to true, three stories and some of their content/s are loaded into memory at a time, otherwise only one story loaded. You can set this to false if your content is mostly video and if you see performance issues. But before doing this, check your video sizes.
  • preloadContent: Sets whether content preload is enabled. When set to true, loads three content into memory at a time, otherwise loads only one content. Most of the time don't need to disable content preloading, this reduces preformance significantly. You might want to set this to false only if your resources are really huge.


Builder to call when creating stories, returns Story. This function runs only once per story and can be async, AdvStory keeps stories in memory until it disposed. Story is a content group andAdvStory creates contents by calling contentBuilder. A content can be one of the predefined types, or can be custom implemented story content.
Predefined types covers most use cases, but AdvStory allows developers to create custom contents for specific use cases. Developer can create anything as story content, for example, audio only content, multiple video content, image and video mixed content, ads...
Prefer to only return content from contentBuilder and no further action. AdvStory doesn't keep contents alive to reduce memory usage, only caches media file to the local storage and may call this function more then once.
For example, when content 4 is displaying, AdvStory disposes content 2 and if user goes back to content 3, callsstoryBuilderand creates content 2 again.
required int contentCount,
required AdvStoryContent Function(int index) contentBuilder,
Widget? header,
Widget? footer,
  • header: top section of story. This is the default story header and can be customized for story contents. This header can be applied to ImageContent, VideoContent and SimpleCustomContent. AdvStory has a predefined StoryHeader that shows a picture and a text in a row.
  • footer: bottom section of story. This is the default story footer and can be customized for story contents. This footer can be applied to ImageContent, VideoContent and SimpleCustomContent.


required Widget Function(int index) trayBuilder,
Builder to call when creating story trays. Two tray type existst in AdvStory, non-animated and animated trays.
The difference between animated and non-animated trays is that, when an animated tray is returned from trayBuilder, AdvStory starts animation, prepares story and its content to show and opens the story view, this prevents from showing a loading screen on first view. In non-animated trays, tapping tray immediately opens story view and AdvStory displays loading screen until content is prepared.
Non-animated trays can be any widget but animated trays has some rules, see creating custom trays to create your own animated trays.
AdvStoryTray is a highly customizable predefined animated tray, shows a nice border rotation animation while content is preparing.
  • size:tray size
  • borderGradientColors: gradient colors apply to border. Use same colors as gradient for a solid color.
  • shimmerStyle: image loading placeholder style.
  • shape: shortcut for creating a circular or rectangular tray
  • strokeWidth: tray's border size.
  • borderRadius: radius for rectangular tray border. Also, this parameter affects image shape.
  • gapSize: transparent area size between tray image and border.
Try AdvStoryTray customization options by running example project or see usage from here.

Style (optional)

AdvStory allows developers to create their own widgets for the most important parts, but some widgets cannot be created by the developer, these settings affect these widgets.
  • hideBars: sets the story view to be full screen or not. Default value is true, hides status and navigation bars. Setting this to false may cause unexpected resizing of the contents.
  • loadingScreen: Custom loading screen widget. This is useful when you want to use your own loading screen. AdvStory default loading screen is a circular progress indicator like widget.
indicatorStyle: const IndicatorStyle(),
trayListStyle: const TrayListStyle(),
loadingStyle: const LoadingStyle(),
loadingScreen: Widget? null,
hideBars: true,


Options for story countdown indicator.
  • backgroundColor: Empty indicator color. Default value is Color(0xe6bdbdbd).
  • valueColor: Filled indicator color. Default value is white.
  • height: Height of indicators. Default value is 2.5.
  • padding: Space between screen edges and first/last indicator. Default value is EdgeInsets.symmetric(horizontal: 4, vertical: 8).
  • spacing: Gap size between indicators. Default value is 3.


Options for tray list.
  • padding: Padding between tray list and parent widget. Default value is EdgeInsets.symmetric(horizontal: 12.0).
  • spacing: Gap size between trays. Default value is 12.0.
  • direction: Tray list direction, trays can be displayed in vertical or horizontal layout. You can see vertical screen shot from gallery. Default value is Axis.horizontal.


Loading screen styles. AdvStory applies these styles to a rotated circular border.
  • backgroundColor: background color of the loading screen (not indicator!). Default value is Color(0xFFFDFBF9)/matte whitefor light theme and Color(0xFF1B1B1B)/matte black for dark theme.
  • gradientColors: indicator gradient colors. Use Colors.transparent for last color to show rotation effect nicely. Default value is [Color(0xCC4b689c), Color(0x00000000)].
  • colorStops: gradient color stops.
  • fillDuration: indicator rotation completion duration. Default value is 3 sec.
  • size: indicator size. Default value is 50.
  • strokeWidth: indicator stroke width. Default value is 7.0.