storify #

A Flutter package for Instagram-like stories: scrollable thumbnail tray, full-screen viewer, RTL support, theming, transitions, and cached video.

Tray → tap → full viewer → gestures → next user

Table of contents #

• Features
• Installation
• Migrating
• Quick start
• Seen state
• Widgets
• Models
• Theming
• Transitions
• Story content helpers
• Gestures
• RTL
• Video setup
• API reference
• Example app
• Comparison
• Contributing
• License

Features #

Installation #

Add to pubspec.yaml:

dependencies:
  storify: ^0.4.0

Then:

flutter pub get

Requirements: Dart ^3.5.0, Flutter >=3.24.0. Supports Android, iOS, Web, Windows, macOS, and Linux.

Import:

import 'package:storify/storify.dart';

See CHANGELOG.md for release notes.

Migrating #

From 0.3.0 → 0.4.0 #

No breaking changes. The story viewer now auto-pauses when the app is backgrounded.

From 0.2.0 → 0.3.0 #

No breaking API changes. Video slides without duration now match the video length automatically. To keep a fixed timer, pass duration explicitly.

From 0.1.0 → 0.2.0+ #

// 0.1.0
StoryItem.imageUrl('https://example.com/1.jpg')

// 0.2.0+
StoryItem.imageUrl('https://example.com/1.jpg', id: 'story_1')

Quick start #

import 'package:flutter/material.dart';
import 'package:storify/storify.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        extensions: [StoriesThemeData.light],
      ),
      home: Scaffold(
        body: StoriesPanel(
          users: [
            StoryUser(
              id: '1',
              name: 'Alex',
              avatar: NetworkImage('https://example.com/avatar.jpg'),
              stories: [
                StoryItem.imageUrl(
                  'https://example.com/story1.jpg',
                  id: 'alex_story_1',
                  title: 'Alex',
                  subtitle: '2h ago',
                  caption: 'Hello!',
                ),
              ],
            ),
          ],
          onUserSeen: (userId) {
            // Persist per-user seen state (tray ring)
          },
          onSeenStory: (storyId) {
            // Persist per-slide seen state
          },
          onUsersChanged: (users) {
            // Optional: sync tray when the panel updates seen rings
          },
        ),
      ),
    );
  }
}

Seen state #

Storify does not keep a global list of seen users or stories. You persist ids in callbacks:

StoriesPanel(
  users: users,
  onUserSeen: (userId) async {
    await prefs.setBool('user_seen_$userId', true);
    setState(() => /* rebuild tray with StoryUser.seen */);
  },
  onSeenStory: (storyId) async {
    await prefs.setBool('story_seen_$storyId', true);
  },
)

Set StoryUser.seen: true on users you have already marked seen so the tray shows gray rings on launch.

Widgets #

StoriesPanel #

Combines tray + viewer. Tapping a user opens StoryViewer; completing their stories marks them seen.

StoriesTray #

Thumbnail strip only (no viewer). Use onUserTap to open your own flow or StoryViewer.show.

StoryViewer #

Full-screen story player.

Static method: StoryViewer.show(context, users: …) opens a full-screen route.

StoryAvatar #

Standalone circular avatar with seen/unseen ring (used inside StoriesTray).

StoryProgressBar #

Segmented top progress indicators.

StoriesScope #

Wraps a subtree with optional textDirection and/or StoriesThemeData.

StoryGestureLayer #

Low-level gesture overlay (tap start/end, hold pause). Usually used internally.

StorySlideOverlay #

Renders StoryItem.title and StoryItem.subtitle at the top of a slide.

StoryVideoSlide #

Video slide widget with caching; syncs pause with StoryPlaybackScope.

Models #

StoryUser #

copyWith() updates seen state after viewing.

StoryItem #

Factories: imageUrl, imageAsset, videoUrl, videoFile, videoAsset, widget — each requires id.

resolveDuration(BuildContext) returns effective duration from theme.

Theming #

Use StoriesThemeData as a ThemeExtension or via StoriesScope(theme: …).

MaterialApp(
  theme: ThemeData(
    extensions: [
      StoriesThemeData.light.copyWith(
        trayAvatarSize: 72,
        unseenRingGradient: LinearGradient(
          colors: [Color(0xFF833AB4), Color(0xFFE1306C)],
        ),
        defaultStoryDuration: Duration(seconds: 6),
        storyItemTransition: StoryItemTransition.slide,
        userTransition: StoryUserTransition.cube,
      ),
    ],
  ),
);

Tray #

Avatar ring #

Slides #

Progress bar #

Viewer #

Add story tile #

Video #

Transitions #

Presets: StoriesThemeData.light, StoriesThemeData.dark.

Transitions #

Story slides — StoryItemTransition #

Users — StoryUserTransition #

Story content helpers #

// Every slide needs a stable id (used by onSeenStory)
StoryItem.imageUrl('https://…/photo.jpg', id: 'news_1', title: 'News')

StoryItem.imageAsset('assets/story.png', id: 'local_1')

// Uses video length for progress (override with duration: …)
StoryItem.videoUrl('https://…/clip.mp4', id: 'clip_1', caption: 'Watch')

// Fixed 8s even if the file is longer
StoryItem.videoUrl('https://…/clip.mp4', id: 'clip_2', duration: Duration(seconds: 8))

StoryItem.widget(MySlide(), id: 'poll_1', title: 'Poll')

StoryItem(
  id: 'custom_1',
  duration: Duration(seconds: 3),
  builder: (context) => MyCustomContent(),
)

Gestures #

Tap zones mirror automatically in RTL.

RTL #

Wrap the app or a subtree:

Directionality(
  textDirection: TextDirection.rtl,
  child: StoriesPanel(users: users),
)

Or:

StoriesScope(
  textDirection: TextDirection.rtl,
  child: StoriesPanel(users: users),
)

Video setup #

This package uses cached_video_player_plus for network video caching.

1. Follow the video_player installation for Android and iOS (required by the player).
2. Use StoryItem.videoUrl, videoFile, or videoAsset.
3. Video pauses when the user holds to pause stories.

Story duration for video #

Progress waits until the video is initialized so the bar matches the real length. Set duration to cap or extend how long a slide stays open.

Network videos are cached via flutter_cache_manager. Asset and file sources play directly without caching.

API reference #

Full API docs: pub.flutter-io.cn/documentation/storify

Generate locally:

dart doc .
open doc/api/index.html

Example app #

cd example
flutter run

The example includes transition pickers, RTL toggle, and themed tray. See example/README.md.

Comparison #

Contributing #

Issues and pull requests are welcome on GitHub.

License #

MIT — see LICENSE.