An onboarding tour sounds simple: dim the screen, cut a hole around a button, show a card that says what the button does, then move to the next one. The details are where it goes wrong. The card lands on top of the thing it explains. The target is below the fold, so the hole highlights nothing. A widget is not mounted and the tour throws. The user rotates the phone and the hole stays where the button used to be. The back button closes the page under the overlay.
coach_tour is a Flutter package for spotlight tours that handles those cases. The hole morphs from one target to the next, a ring breathes around it, and the card places itself so it never covers what it is explaining.
What it does
Targets. You point at a widget by GlobalKey, or by id through a CoachTourRegistry. The second way lets you declare the steps in one place while the widgets live anywhere in the tree.
Shapes. rect, rrect, circle and stadium, with per-step padding and radius. The hole morphs between targets, shape included, so a rectangle can become a circle. A breathing ring around the hole is optional.
Card auto-placement. The card goes above, below, at the start or at the end of the hole. It never covers the hole, stays inside the SafeArea, and flips to the other side when there is no room. When no side has room for the whole card, it is shortened and scrolls.
Scroll into view. Off-screen targets are brought on screen with Scrollable.ensureVisible first. Targets that are unmounted or cannot be made visible are skipped and reported through onTargetSkipped, instead of throwing.
Rotation and resize. The target is measured again whenever window metrics change.
A controller. next, previous, goTo, skip and finish, plus onStepChanged, onFinish and onSkip callbacks and a result future.
Configurable input. Taps in the hole are blocked or pass through to the target. Taps on the dimmed barrier go to the next step, dismiss the tour or do nothing. The back button and predictive back skip the tour, go back one step or are ignored, through PopScope.
Show once. CoachTour.startOnce works with a pluggable CoachTourStore (hasSeen and markSeen). The package has no storage dependency.
Localized buttons. Next, Back, Skip and Done come in English, French and Arabic, and all of them can be overridden. RTL layouts are supported: the start and end placements, directional padding and the button order follow the text direction.
Accessibility. The overlay is a modal route scope that hides the page from screen readers. Focus moves to the card, each step is announced ("Step 2 of 5. Title. Body."), and Escape skips the tour.
Reduced motion. When the platform asks for it (MediaQueryData.disableAnimations), or when you pass reduceMotion: true, the pulse, the morph and animated scrolling are turned off.
How to use it
Add it from GitHub:
dependencies: coach_tour: git: https://github.com/AbdeldjalilChougui/coach_tour It needs Flutter 3.27 or later. There is no builder around your app and no widget wrapping each target. You pass the GlobalKey you already have:
final _search = GlobalKey(); final _add = GlobalKey(); void _startTour() { final controller = CoachTour.start( context, [ const CoachTarget.centered(title: 'Welcome', body: 'A quick tour.'), CoachTarget( key: _search, title: 'Search', body: 'Find anything by name.', shape: CoachShape.stadium, ), CoachTarget( key: _add, title: 'Add', body: 'Create a new item.', shape: CoachShape.circle, placement: CoachPlacement.above, ), ], options: const CoachTourOptions( barrierAction: CoachBarrierAction.next, holeTap: CoachHoleTap.block, backAction: CoachBackAction.previous, ), onStepChanged: (index, target) => debugPrint('step $index'), onFinish: () => debugPrint('finished'), onSkip: (index) => debugPrint('skipped at $index'), onTargetSkipped: (s) => debugPrint('could not show ${s.index}: ${s.reason}'), ); controller.result.then((r) => debugPrint('result: $r')); } If you prefer ids, wrap the target with CoachAnchor and refer to it by name:
// Anywhere in the tree: CoachAnchor(id: 'profile.avatar', child: const CircleAvatar()); // Where the tour is declared: CoachTour.start(context, const [ CoachTarget(id: 'profile.avatar', title: 'Your profile'), ]); Without a CoachTourRegistryScope, CoachAnchor and CoachTour.start share CoachTourRegistry.global. Each id can be mounted only once at a time.
Showing a tour once
CoachTour.startOnce asks a CoachTourStore whether the tour was seen. It marks the tour seen when it finishes, and when it is skipped unless you pass markSeenOnSkip: false. A tour that had nothing to show is not marked, so it tries again next time.
The package ships MemoryCoachTourStore. For real persistence you implement three methods (hasSeen, markSeen, reset) over your own storage. The README shows a version with shared_preferences, which you add to your own app:
await CoachTour.startOnce( context, tourId: 'home.v1', store: PrefsCoachTourStore(SharedPreferencesAsync()), steps: steps, ); Bump the id to home.v2 when the tour changes enough to show it again.
Custom cards and labels
contentBuilder on a CoachTarget lets you put your own content inside CoachTourCard, or return any widget to replace the card entirely and drive the tour through details.controller. Button texts follow the app locale, with English as the fallback, and you can override them with CoachTourOptions(labels: CoachTourLabels.fr.copyWith(done: "C'est parti")).
The defaults are sensible: a tap on the barrier goes to the next step, a tap in the hole is blocked, back skips the tour, the morph lasts 450 ms with easeInOutCubic, and the card is at most 360 wide. The README has the full options table.
If you come from tutorial_coach_mark or showcaseview, the README also has a table that maps their names to CoachTarget, CoachShape, placement, holeTap and barrierAction. It warns that both packages have renamed parameters across major releases, so check your installed version.
Things to know
- Lazy lists. A target inside a
ListView.builderthat was never built has no context, so it cannot be scrolled to. It is skipped as unmounted. Scroll it into existence first, or keep the target outside the lazy part. - Visibility is judged against the screen. At least half the target must be on it. A target hidden by clipping inside its own parent, or covered by another widget, is not detected.
- Circles and wide targets. A
circlehole uses the longer side of the padded target as its diameter, so the corners of a wide target fall outside it. Usestadiumorrrectfor wide targets. - Very large targets. When no side has room for a card, for example with a full-screen list, the card is placed at the bottom and overlaps the hole.
- During the morph. The card is placed relative to where the hole ends up. While the hole is still moving, it can pass under the card for a moment.
- Pass-through taps. With
CoachHoleTap.passThrough, a tap that navigates away leaves the tour open on the previous route. Callcontroller.finish()from the target's handler first. - Early calls. Navigation calls made before the overlay's first frame are ignored.
Why I built it
The README's comparison with the other tour packages says what was missing. A tour should not need a builder around the whole app or a wrapper around each target. The hole should move between steps instead of cutting. The card should never cover the hole. A target that is off screen should be scrolled to, and one that is missing should be skipped and reported, not crash the tour. "Show once" should be built in, with a store you control. And the back button, Escape, focus, screen-reader announcements, RTL and reduced motion should be handled by the package.
I wanted one package where all of that is the default behavior.
Get the code
The source, the options table, the migration table and the tests are on GitHub: https://github.com/AbdeldjalilChougui/coach_tour. It is MIT licensed.
Originally published at abdeldjalilchougui.biz.
