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.

Core Concepts

1. Story Structure: Header, Items, Footer

A Story widget is divided into three main parts:

• Header Optional area at the top of the story. Commonly used for:

  • User avatar or logo

  • Title / username

  • Time or label

• Items These are the individual stories shown one after another. Each item can contain:

  • Images

  • Videos

  • Text

  • Buttons or any other widgets

• Footer Optional area at the bottom. Useful for:

  • Call-to-action buttons (e.g., “Learn More”, “Try Now”)

  • Captions or descriptions

  • Navigation or secondary actions

Together, these create a story layout similar to modern social media stories, but fully customizable.

2. Story Flow & Behaviour

The Story widget plays items in sequence. It can:

• Auto-advance after a certain duration

• Restart when completed (optional)

• React to user gestures:

  • Tap left → go to previous

  • Tap right → go to next

  • Slide down → close / custom action

Under the hood, a controller manages which story is active and how it progresses, giving you hooks and callbacks to react to user activity.

3. Indicators

At the top of the Story widget, you can show progress indicators—small horizontal bars representing each story:

• Active story (currently visible)

• Completed stories (already seen)

• Upcoming stories (not seen yet)

You can customize the colors, size, spacing, and border radius for a polished, on-brand look.

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.

Use Cases

The Story widget is ideal for:

• Onboarding flows with short, visual steps

• Feature or product highlights

• Release notes and announcements

• Promotional campaigns and offers

• Quick tutorials or tips shown as tappable slides