flutter_tipkit 0.1.1
flutter_tipkit: ^0.1.1 copied to clipboard
Contextual feature tips for Flutter: rules, parameters, events, display frequency, tip groups, inline and popover tips, with a pluggable datastore.
flutter_tipkit #
Try the live demo, a chapter for each feature, from a one-line tip to tours and custom themes.
Contextual feature tips for Flutter: tips with rules, parameters and events, a display frequency, tip groups, inline and popover tips, and a pluggable datastore.
Inspired by Apple's TipKit. This is an independent package, not affiliated with or endorsed by Apple.
- Pure models. A
Tipis plain data: an id, its text, its rules and options. It never builds widgets. How tips look is up toTipWidget,PopoverTipWidgetandTipTheme. - No dependencies beyond Flutter. Popovers use Flutter's own
OverlayPortal, so they inherit your theme, localizations and state management scopes. - Persist anywhere. Tip state goes through a small
TipDatastoreinterface.flutter_tipkit_shared_preferencesprovides one for shared preferences.
Installation #
flutter pub add flutter_tipkit
# To keep tip state across app restarts:
flutter pub add flutter_tipkit_shared_preferences
Getting started #
Configure once, before the first tip shows:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Tips.configure(
datastore: SharedPreferencesTipDatastore.async(SharedPreferencesAsync()),
displayFrequency: TipDisplayFrequency.daily,
onEvent: (event) => analytics.log(event),
);
runApp(const MyApp());
}
Define a tip:
class FavoriteTip extends Tip {
const FavoriteTip();
@override
String get id => 'favorite';
@override
TipContent get content => const TipContent(
title: 'Keep the good ones',
message: 'Star a note to pin it to the top.',
actions: [TipAction(id: 'gotIt', label: 'Got it')],
);
@override
List<TipRule> get rules => [
TipRule.event(addedNote, (donations) => donations.count >= 3),
];
}
Show it inline, or pointing at a widget:
const TipWidget(tip: FavoriteTip());
PopoverTipWidget(
tip: const FavoriteTip(),
arrowEdge: TipArrowEdge.top, // the arrow points up: opens below the star
child: IconButton(icon: const Icon(Icons.star), onPressed: favorite),
);
The id is what the tip's state is stored under: never change it once a tip
has shipped.
Inline tips #
While a tip may not be displayed, TipWidget takes no space (it builds a
SizedBox.shrink). Give the space around an inline tip in its padding, not
in a Padding around it, so the space goes away with the tip. In a
CustomScrollView, use SliverTipWidget, which has no extent while hidden:
TipWidget(tip: const FavoriteTip(), padding: const EdgeInsets.only(bottom: 12));
SliverTipWidget(tip: const FeedTip(), padding: const EdgeInsets.all(12));
Popovers #
A PopoverTipWidget adds nothing but two lightweight wrappers around its
child while its tip may not be displayed: the bubble and the barrier exist
only while the tip shows. Only one popover shows at a time; the others wait
until it closes.
arrowEdgeis the edge of the tip that carries the arrow, so it also says where the tip opens:topopens below the target,bottomabove,startandendbeside it. Left out, the tip opens below or above, wherever there is more room.arrowAlignmentputs the arrow near the start, centre or end of that edge. The tip is shifted to stay on screen, and the arrow follows so it keeps pointing at the target.barrierBehaviorsays what a tap outside the tip does:close(the default) invalidates the tip,dismisshides it until thePopoverTipWidgetis rebuilt from scratch, andblockignores the tap.
Only on the visible screen #
A TipWidget or PopoverTipWidget shows its tip only while it is on the
visible screen: its tickers are enabled (so not in an inactive tab kept alive
by an IndexedStack-style tab bar) and its route is the current one (so not
under another screen, dialog or bottom sheet). Elsewhere it shows nothing,
counts no displays and does not hold the one-popover slot, so a hidden popover
can never leave a barrier over the visible screen. When the screen comes back,
so does the tip.
Rules, parameters and events #
A tip shows once all its rules hold. Rules can look at parameters, events and other tips:
const isLoggedIn = TipParameter<bool>('isLoggedIn', false);
const addedNote = TipEvent('addedNote');
isLoggedIn.value = true; // when it changes
addedNote.donate(); // each time it happens
@override
List<TipRule> get rules => [
TipRule.parameter(isLoggedIn, (loggedIn) => loggedIn),
TipRule.event(addedNote, (d) => d.within(const Duration(days: 7)) >= 3),
TipRule.tipInvalidated(const WelcomeTip(), minAge: const Duration(days: 1)),
];
TipRule.tipInvalidated(other, minAge:)shows a tip some time after another one, at another place in the app. Time-based rules re-evaluate by themselves when their time comes.TipRule.allOf,anyOfandnotcombine rules.- Rules are synchronous and see only tip state: pass anything else in through
a parameter. Write your own by extending
TipRule.
Groups #
A TipGroup shows its tips one at a time: TipGroup.ordered in the order
given, TipGroup.firstAvailable whichever is available first.
final tour = TipGroup.ordered([
const ComposeTip(),
if (remoteConfig.showsAttachments) const AttachmentsTip(),
const SendTip(),
]);
TipWidget.group(tour); // shows the current tip, then the next
// Or show each tip of the group at its own place:
TipWidget(tip: const ComposeTip(), group: tour);
PopoverTipWidget(tip: const SendTip(), group: tour, child: sendButton);
A group keeps no state of its own. Its current tip follows from the tips'
stored state, so the order can be decided at runtime and the group resumes
where the user left off. With both tip: and group:, a view shows its tip
only while it is the group's current one, so a group's tips can point at
different widgets.
Display frequency and limits #
displayFrequencyinTips.configurelimits how often a tip that has never been displayed may appear:immediate,hourly,daily,weeklyormonthly. Tips displayed before are not held back.TipOption.ignoresDisplayFrequency()lets a tip show regardless, for example the steps of a tour that follow each other right away.TipOption.maxDisplayCount(n)invalidates a tip once it has been displayedntimes. Coming back to its screen counts as displaying it again.
@override
List<TipOption> get options => const [TipOption.maxDisplayCount(3)];
Actions and closing #
- A
TipActioninvalidates its tip by default, since "Next" and "Got it" end most tips.invalidatesTip: falsekeeps the tip. - The close button invalidates the tip as closed.
- React to an action where the tip shows, with
onAction: (tip, action). - Invalidate a tip from anywhere once the user did what it suggests:
const FavoriteTip().invalidate(TipInvalidationReason.actionPerformed). Tips.suppress()hides every tip for a while, without invalidating any, for example while a full-screen dialog is open. Callrelease()on what it returns to show them again.
Customizing the look #
There are three levels, from light to full. All of them can be set for a
subtree with TipTheme (for example in MaterialApp.builder), and the
builders can also be given to a single tip widget.
1. Restyle the default card with colors, a gradient, the outline, corner radius, shadows, arrow shape, text styles and spacing:
TipTheme(
data: TipThemeData(
backgroundColor: colors.surface,
gradient: null, // or a LinearGradient
borderSide: BorderSide(color: colors.outlineVariant),
borderRadius: BorderRadius.circular(16),
arrowShape: const TipArrowShape.rounded(size: Size(22, 11), tipRadius: 3),
popoverShadows: const [BoxShadow(blurRadius: 24, spreadRadius: 2)],
leading: const Icon(Icons.lightbulb_outline),
),
child: child,
)
The bubble is a ShapeBorder, TipBubbleBorder, so it works anywhere a
shape does, for example in your own ShapeDecoration. Implement
TipArrowShape for arrows the built-in triangle and rounded shapes cannot
draw.
2. Replace parts of the card: leading, actionBuilder (for your own
buttons) and closeButtonBuilder.
TipThemeData(
actionBuilder: (context, action, onPressed) =>
TextButton(onPressed: onPressed, child: Text(action.label)),
)
3. Replace the whole card with cardBuilder. The tip widgets still decide
when the tip shows, place popovers and animate them; the builder only draws:
TipThemeData(
cardBuilder: (context, details) => MyTipCard(
title: details.content.title,
message: details.content.message,
onClose: details.onClose,
onAction: details.onAction,
),
)
To keep a popover's arrow on its target when the tip is shifted to stay on
screen, draw it with a TipBubble given details.arrowPosition. To decorate
the default card, return TipCard.fromDetails(details) inside your own
widgets. TipBubble, TipContentLayout and TipActionBar are public too.
Animations #
transitionDuration and transitionCurve set the timing. To change the
animation itself, give a TipTransitionBuilder, like
AnimatedSwitcher.transitionBuilder: inlineTransitionBuilder and
popoverTransitionBuilder in the theme, or transitionBuilder on a widget.
TipThemeData(
popoverTransitionBuilder: (context, animation, details, child) =>
SlideTransition(
position: Tween(begin: const Offset(0, 0.1), end: Offset.zero)
.animate(animation),
child: FadeTransition(opacity: animation, child: child),
),
)
The animation runs from 0 (hidden) to 1 (shown) and is already curved.
details.arrowAlignment says where the arrow is, the natural origin for a
scale. TipTransitions has the built-in ones: reveal (the inline default),
scale (the popover default), fade and slide.
Localization #
Tip.content is read each time the tip renders, so localization that needs no
BuildContext works in it directly:
@override
TipContent get content => TipContent(title: LocaleKeys.favoriteTitle.tr());
With context-based localization, provide the content where the tip shows:
TipWidget(
tip: const FavoriteTip(),
content: (context, tip) =>
TipContent(title: AppLocalizations.of(context).favoriteTitle),
);
Set TipThemeData.closeButtonLabel to the translated word, so screen readers
announce the default close button in the user's language.
State management #
flutter_tipkit has no state management dependency. It talks in plain Flutter types, so it fits any of them:
- Reading:
Tips.centeris aListenablethat notifies on every change, andTips.statusListenable(tip)is aValueListenable<TipStatus>. Plain reads (tip.status,group.currentTip,group.isCompleted) are synchronous. - Writing: set a parameter (
isLoggedIn.value = true), donate an event (addedNote.donate()) or invalidate a tip (tip.invalidate(...)) from wherever your logic lives.
The widgets need nothing else. To use tip state in your own logic:
// No package at all.
ValueListenableBuilder(
valueListenable: Tips.statusListenable(const FavoriteTip()),
builder: (context, status, _) => Text('$status'),
);
// Riverpod.
final tipStatusProvider = Provider.family<TipStatus, Tip>((ref, tip) {
final status = Tips.statusListenable(tip);
void onChange() => ref.invalidateSelf();
status.addListener(onChange);
ref.onDispose(() => status.removeListener(onChange));
return status.value;
});
// Feeding a parameter from a provider.
ref.listen(noteCountProvider, (_, count) => noteCount.value = count,
fireImmediately: true);
// Bloc.
class TipStatusCubit extends Cubit<TipStatus> {
TipStatusCubit(Tip tip)
: _status = Tips.statusListenable(tip),
super(Tips.status(tip)) {
_status.addListener(_onChange);
}
final ValueListenable<TipStatus> _status;
void _onChange() => emit(_status.value);
@override
Future<void> close() {
_status.removeListener(_onChange);
return super.close();
}
}
// provider.
ChangeNotifierProvider.value(value: Tips.center, child: app);
Listeners are notified once per microtask, never in the middle of a build, so updating state from them is safe.
Persistence #
Tips.configure loads everything once, keeps it in memory, and writes changes
in the background, one at a time and in order. Implement TipDatastore to
store tips anywhere; every value it receives is JSON-encodable. The default,
InMemoryTipDatastore, forgets everything on restart.
Testing #
setUp(Tips.resetForTesting);
testWidgets('shows the tip', (tester) async {
await Tips.configure();
Tips.showAllTipsForTesting();
...
});
Tips.configure(clock: ...) replaces the clock for time-based rules, and
Tips.flush() waits for pending writes. Tips.resetDatastore() clears every
tip's state, for example behind a debug menu item.