# 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). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digia.tech/ui-building-blocks/widgets/content-display-widgets/story.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.