Story

The Story widget lets you build immersive, Instagram-style story experiences inside your app. It shows a sequence of full-screen or card-style “stories” that users can tap through, swipe, or watch as they auto-play. This is great for feature highlights, onboarding flows, announcements, or tutorials presented in a visual, lightweight format.

Use Cases

• Onboarding flows

  • Introduce your app in 3–5 visual steps

  • Highlight “What you can do” with quick, snackable screens

• Feature & product highlights

  • Showcase new features with images + short copy

  • Display multiple product angles, USPs, or use-cases as separate story items

• Promotions & campaigns

  • Limited-time offers, festival campaigns, or seasonal sales

  • “Swipe through” style promo banners instead of static images

• Announcements & release notes

  • New version updates, changelog highlights, or important news

  • Show key changes one story at a time to avoid overwhelming text

• Quick tutorials & tips

  • Step-by-step mini-tutorials (“How to use X”)

  • Daily tips, growth hacks, or quick education content

Core Concepts

1. Story Layout (Header, Items, Footer)

   • Header: Optional top area (avatar, logo, title, time).

   • Items: Each item is one “story screen” – can be image, video, text, buttons, or any widget.

   • Footer: Optional bottom area for CTAs, captions, or extra actions.

2. Story Flow & Behaviour

   • Stories play one after another (auto-advance optional).

   • User gestures: tap left = previous, tap right = next.

   • A controller manages the current item and lets you react with callbacks (e.g., onStart, onEnd, onChange).

3. Indicators

   • Small bars at the top show how many stories and current position.

   • States: completed, current, upcoming.

   • Fully customizable (colors, size, spacing, radius) to match your brand.

Properties

Layout & Content

Header / Items / Footer

• Header Add any widget you like (avatar, text, icons, etc.). This is optional.

• Items Add one or more story items. Each item is a widget tree that will be shown as an individual story step.

• Footer Optional bottom area for buttons, secondary info, links, or actions.

Behaviour

These properties control how the stories play and progress.

Property	Description
Controller	Internal controller that manages the current story index and playback. Can be used in actions to programmatically change or control stories.
Initial Index	The zero-based index of the story item that should be shown first when the widget loads.
Restart on Completed	When enabled, the story sequence restarts from the first item after the last story finishes. When disabled, playback stops at the end.
Duration	Time each story stays visible before automatically moving to the next one. Applies when stories are auto-playing.

Navigation

These properties define how user gestures trigger actions.

Property	Description
On Slide Down	Triggered when the user slides the story down. Often used to close the story or navigate back.
On Slide Start	Called when the user first starts viewing/interacting with the story sequence. Useful for analytics or initializing logic.
On Left Tap	Triggered when the user taps on the left side of the story. Typically used to go to the previous story item.
On Right Tap	Triggered when the user taps on the right side of the story. Typically used to go to the next story item.

Callbacks

Callbacks give you hooks into key moments in the story lifecycle.

Property	Description
On Completed	Fired when the entire story sequence finishes. Useful for marking as seen, navigating away, or showing a final message.
On Previous Completed	Called when a previous story group/segment completes (if you use grouped logic). Can be used for step-wise tracking.
On Story Changed	Fired every time the active story index changes. Useful for analytics, loading data for the current story, or updating other UI based on the active slide.

Indicators

Indicator properties control the look and feel of the story progress bars.

Property	Description
Active Color	Color of the indicator for the currently active story item.
Completed Color	Color of indicators representing stories that have already been viewed.
Upcoming Color	Color of indicators for stories that have not yet been seen.
Height	Thickness of each indicator bar. Smaller values give a slim line; larger values create bold bars.
Border Radius	Roundness of the indicator corners. Higher values create pill-shaped bars; lower values create more rectangular ones.
Horizontal Gap	Space between each indicator bar. Controls how tightly or loosely they are spaced.

Default Properties

The Story widget supports all Default Properties.