The pull-to-refresh gesture is a popular UI mechanic that is used not only in Google’s Material Design, but also in Apple’s Human Interface Guidelines. No surprise this feature is also represented in the Flutter standard library. It’s called RefreshIndicator there.
But how do we use this handy UI element? And how does it play together with alternative state management solutions such as BLoC pattern?
How to use RefreshIndicator
RefreshIndicator is a usual widget that is supposed to be wrapped around the widget which you want to give the ability to be reloaded on pull down. Whenever the child‘s Scrollable ist overscrolled, the circular progress indicator is shown on top. When the user releases its finger / cursor and the indicator has been dragged far enough to the bottom, it will call the provided callback (onRefresh).
The widget’s constructor has two arguments. child represents the widget that should be refreshed on pull down. onRefresh is a callback function that is called when the refresh indicator has been dragged far enough to the bottom. This is the place where you typically trigger fetching new data.
Prerequisites
Before we jump right into the implementation, let’s build a sample widget we can test our implementation on.
Typically, there is a list of elements that is being refreshed when the indicator is shown. So let’s build a SampleListView widget that resembles this.
1import 'package:flutter/material.dart';
2
3class SampleListView extends StatelessWidget {
4 const SampleListView({Key? key, required this.entries}) : super(key: key);
5
6 final List<int> entries;
7
8 @override
9 Widget build(BuildContext context) {
10 return ListView(
11 children: entries
12 .map(
13 (int e) => ListTile(
14 leading: const Icon(Icons.android),
15 title: Text('List element ${e + 1}'),
16 ),
17 )
18 .toList(),
19 );
20 }
21}
The widget expects a list of int. For every element in this list, it shows a ListTile with “List element xy”, xy being the index (+1) of the element.
The scenario
Because we are not dealing with actual dynamic data here, we define a recurring scenario once the user pulls down, the view idles for 2 seconds, resulting in the list being expanded by one element.
RefreshIndicator and StatefulWidget
1import 'package:flutter/material.dart';
2import 'package:flutter_app/sample_list_view.dart';
3
4class RefreshWithStatefulWidget extends StatefulWidget {
5 const RefreshWithStatefulWidget({Key? key}) : super(key: key);
6
7 @override
8 State<RefreshWithStatefulWidget> createState() =>
9 _RefreshWithStatefulWidgetState();
10}
11
12class _RefreshWithStatefulWidgetState extends State<RefreshWithStatefulWidget> {
13 List<int> entries = List<int>.generate(5, (int i) => i);
14
15 @override
16 Widget build(BuildContext context) {
17 return Scaffold(
18 appBar: AppBar(
19 title: const Text('Refresh with StatefulWidget'),
20 ),
21 body: RefreshIndicator(
22 onRefresh: () async {
23 await Future.delayed(const Duration(seconds: 2));
24 setState(() {
25 entries.add(entries.length);
26 });
27 },
28 child: SampleListView(
29 entries: entries,
30 ),
31 ),
32 );
33 }
34}
The list (entries) is initiated with 5 elements. After the user interaction with the RefreshIndicator, we alter the state by adding one element to the entries.
Alternative loading animation
So far, so good. But right now, the animation of the RefreshIndicator is shown until everything’s ready. What if we did not want to show the default loading animation? If we had a branded loading indicator all across our app, we might wanted to show it during every occurrence of a loading state. What if we had our app-wide loading indicator in a dialog?
1import 'dart:async';
2
3import 'package:flutter/material.dart';
4import 'package:flutter_app/sample_list_view.dart';
5
6class RefreshWithStatefulWidget extends StatefulWidget {
7 const RefreshWithStatefulWidget({Key? key}) : super(key: key);
8
9 @override
10 State<RefreshWithStatefulWidget> createState() =>
11 _RefreshWithStatefulWidgetState();
12}
13
14class _RefreshWithStatefulWidgetState extends State<RefreshWithStatefulWidget> {
15 List<int> entries = List<int>.generate(5, (int i) => i);
16 bool loading = false;
17
18 @override
19 Widget build(BuildContext context) {
20 return Scaffold(
21 appBar: AppBar(
22 title: const Text('Refresh with StatefulWidget'),
23 ),
24 body: RefreshIndicator(
25 onRefresh: () async {
26 _indicateLoading();
27 Future.delayed(const Duration(seconds: 2)).then(
28 (_) => _refresh(),
29 );
30 },
31 child: loading
32 ? const Center(
33 child: CircularProgressIndicator(),
34 )
35 : SampleListView(
36 entries: entries,
37 ),
38 ),
39 );
40 }
41
42 void _refresh() {
43 return setState(
44 () {
45 entries.add(entries.length);
46 loading = false;
47 },
48 );
49 }
50
51 void _indicateLoading() {
52 setState(() {
53 loading = true;
54 });
55 }
56}
We add a state property called loading which indicates whether the data is being loaded. It is supposed to be set to true when the user pulls down and be set to false again when the asynchronous operation is finished.
Depending on the value of loading we weither show a CircularProgressIndicator or the SampleListView.
The RequestIndicator disappears as soon as the onRefresh() method returns. That’s why we avoid using await to wait for our Future to be finished and use then instead.
Using await instead of then()
What if we want to use await? Actually, I like it much more than then() if I have sequential operations anyways. Because with then(), there is a steadily increasing nesting level. This decreases the readability of our code drastically.
How about letting the caller decide when to hide the RequestIndicator?
1import 'dart:async';
2
3import 'package:flutter/material.dart';
4
5class RefreshableWidget extends StatelessWidget {
6 const RefreshableWidget({
7 Key? key,
8 required this.child,
9 required this.onRefresh,
10 }) : super(key: key);
11
12 final Widget child;
13 final Function(Completer<void>) onRefresh;
14
15 @override
16 Widget build(BuildContext context) {
17 return RefreshIndicator(
18 onRefresh: () {
19 final Completer<void> completer = Completer<void>();
20 onRefresh(completer);
21 return completer.future;
22 },
23 child: child,
24 );
25 }
26}
I created a wrapper around the RefreshIndicator. The onRefresh() function being its constructor argument, has a Completer<void> type.
Now, what does that mean?
Completer is a way to produce Future objects. This is exactly what we want, because we want the caller to decide when the RefreshIndicator disappears. And it disappears whenever the onRefresh() function finishes. It’s an async function that returns a Future. We create a new function that returns the future property of our newly created Completer which is then passed to the onRefresh function of our RefreshableWidget.
Using our RefreshableWidget, our list looks like this:
1@override
2 Widget build(BuildContext context) {
3 return Scaffold(
4 appBar: AppBar(
5 title: const Text('Refresh with StatefulWidget'),
6 ),
7 body: RefreshableWidget(
8 onRefresh: (Completer completer) async {
9 completer.complete();
10 _indicateLoading();
11 await Future.delayed(const Duration(seconds: 2));
12 _refresh();
13 },
14 child: loading
15 ? const Center(
16 child: CircularProgressIndicator(),
17 )
18 : SampleListView(
19 entries: entries,
20 ),
21 ),
22 );
23 }
In this case, we let the RefreshIndicator disappear directly because we call completer.complete() as the first statement inside our callback. Now we can safely use await to wait for our time-intense operation.
How about using BLoC?
Now that we have abstracted the control over the disappearance of the, we can also easily use any other state management solution apart from StatefulWidget without having to worry about await statements.
The following example demonstrates a solution using the BLoC package.
1part of 'refresh_cubit.dart';
2
3class RefreshState extends Equatable {
4 const RefreshState({this.entries = const []});
5
6 final List<int> entries;
7
8 @override
9 List<Object?> get props => [entries];
10}
11
12class RefreshLoaded extends RefreshState {
13 const RefreshLoaded({required List<int> entries}) : super(entries: entries);
14}
15
16class RefreshInitial extends RefreshState {
17 const RefreshInitial() : super(entries: const <int>[0, 1, 2, 3, 4]);
18}
19
20class RefreshLoading extends RefreshState {}
First, we create a State that is to be emitted from our Cubit. It has three possible states: RefreshInitial, RefreshLoading and RefreshLoaded. RefreshInitial carries a list with 5 elements. RefreshLoading is supposed to be emitted when the user pulls down. Finally, RefreshLoaded should be emitted, when the time-intense operation is done and the data is fetched.
1import 'package:bloc/bloc.dart';
2import 'package:equatable/equatable.dart';
3
4part 'refresh_state.dart';
5
6class RefreshCubit extends Cubit<RefreshState> {
7 RefreshCubit() : super(const RefreshInitial());
8
9 Future<void> refresh() async {
10 emit(RefreshLoading());
11 List<int> newList = List<int>.from(state.entries);
12 newList.add(newList.length);
13 await Future.delayed(const Duration(seconds: 2));
14 emit(RefreshLoaded(entries: newList));
15 }
16}
In our Cubit, we only provide a single method: refresh(). It emits a loading state, adds an element to the list, and emits a loaded state.
1import 'dart:async';
2
3import 'package:flutter/material.dart';
4import 'package:flutter_app/sample_list_view.dart';
5import 'package:flutter_app/with_refreshable_widget/refresh_cubit.dart';
6import 'package:flutter_app/with_refreshable_widget/refreshable_widget.dart';
7import 'package:flutter_bloc/flutter_bloc.dart';
8
9class RefreshWithRefreshableWidget extends StatelessWidget {
10 const RefreshWithRefreshableWidget({Key? key}) : super(key: key);
11
12 @override
13 Widget build(BuildContext context) {
14 return BlocProvider<RefreshCubit>(
15 create: (BuildContext context) => RefreshCubit(),
16 child: BlocBuilder<RefreshCubit, RefreshState>(
17 builder: (BuildContext context, RefreshState state) {
18 return RefreshableWidget(
19 onRefresh: (Completer<void> completer) async {
20 completer.complete();
21 context.read<RefreshCubit>().refresh();
22 },
23 child: _buildScaffold(context, state),
24 );
25 },
26 ),
27 );
28 }
29
30 Scaffold _buildScaffold(BuildContext context, RefreshState state) {
31 return Scaffold(
32 appBar: AppBar(
33 title: const Text('Refresh with RefreshableWidget'),
34 ),
35 body: _buildBody(context, state),
36 );
37 }
38
39 Widget _buildBody(BuildContext context, RefreshState state) {
40 if (state is RefreshLoading) {
41 return const Center(
42 child: CircularProgressIndicator(),
43 );
44 }
45
46 return SampleListView(
47 entries: state.entries,
48 );
49 }
50}
In the widget, we can now complete the future before calling the Cubit‘s refresh method. If we wanted to give the control over the disappearance of the indicator to the cubit, we could expect a parameter in the refresh method.
Conclusion
Flutter already provides a solution for handling the pull-to-refresh gesture which is very straightforward in its usage. However, when using await or there is the desire to show an alternative loading animation, there are some some things to consider.
Comment this 🤌