spotlight_tutorial

A lightweight Flutter package for interactive feature tutorials with spotlight overlays, coach marks, and sequential guided steps.

Screenshots

Project layout

Path	What it is
lib/spotlight_tutorial.dart	Package entry — import this in your app
lib/src/...	Library implementation (private details)
example/lib/main.dart	Runnable demo + copy-paste usage sample

There is no main.dart in the package root — that is expected. Flutter packages publish library code; the demo app lives under example/.

Try it now:

cd example
flutter run

Installation

Add to pubspec.yaml:

dependencies:
  spotlight_tutorial: ^1.0.3
  shared_preferences: ^2.5.3

Then run flutter pub get.

Quick start

1. Initialize SharedPreferences in your app (needed when persisting completion):

final prefs = await SharedPreferences.getInstance();

2. Add SpotlightTutorialTheme to your ThemeData (optional):

MaterialApp(
  theme: ThemeData(
    extensions: const [SpotlightTutorialTheme()],
  ),
  // ...
);

3. Wrap your screen with TutorialScope and attach GlobalKeys to targets:

class HomeTutorialTargets {
  final fabKey = GlobalKey();
  final appBarKey = GlobalKey();
}

final keys = HomeTutorialTargets();

TutorialScope<HomeTutorialTargets>(
  completionKey: 'home_tutorial_v1',
  sharedPreferences: prefs,
  targets: keys,
  stepsBuilder: (context, targets) {
    final t = targets!;
    return [
      TutorialStep(
        targetKey: t.fabKey,
        title: 'Create item',
        body: ['Tap here to add a new item.'],
        arrowEdge: TutorialArrowEdge.top, // tooltip below FAB
      ),
      TutorialStep(
        targetKey: t.appBarKey,
        title: 'Navigation',
        body: ['Use the app bar to go back.'],
        arrowEdge: TutorialArrowEdge.bottom, // tooltip above app bar
      ),
    ];
  },
  child: Scaffold(
    appBar: AppBar(
      key: keys.appBarKey,
      title: const Text('Home'),
    ),
    floatingActionButton: FloatingActionButton(
      key: keys.fabKey,
      onPressed: () {},
      child: const Icon(Icons.add),
    ),
  ),
);

Full working sample: example/lib/main.dart.

API overview

Type	Purpose
TutorialScope	Runs the tutorial over a widget subtree
TutorialStep	Defines one step (target key, copy, arrow)
TutorialOverlayCallbacks	Hooks for scroll-into-view, missing targets, etc.
SpotlightTutorialTheme	Colors and styling via ThemeData.extensions

Set persistCompletion: false to show the tutorial every time without SharedPreferences.

Example app

The example/ folder is a complete Flutter app (with main.dart) that demonstrates every feature. Open it in your IDE or run:

cd example && flutter run

License

MIT — see LICENSE.