> For the complete documentation index, see [llms.txt](https://docs.digia.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digia.tech/ui-building-blocks/widgets/content-display-widgets/story.md). # 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. {% embed url="" %} Watch this on Youtube: ### 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](/ui-building-blocks/widgets/default-properties.md).