Skip to content

Cancellation

A cancelled request returns a RequestCanceledException, like any other error, so cancelling never needs a try/catch either.

With a cancel token

Pass a Dio CancelToken:

final token = CancelToken();
final future = client.get<User>('me', fromJson: User.fromJson, cancelToken: token);

token.cancel('left the screen');

final result = await future;
print(result.error is RequestCanceledException); // true

With a tag

For anything bigger than one request, give requests a cancelTag and cancel the tag:

client.get<Feed>('feed', fromJson: Feed.fromJson, cancelTag: 'home');
client.getList<Story>('stories', fromJson: Story.fromJson, cancelTag: 'home');

// When the screen is disposed:
client.cancelRequestsByTag('home', reason: 'screen disposed');

client.cancelAllRequests() cancels every tagged request, for example on sign-out.

One request per tag

By default a new request with a tag cancels the previous one with the same tag, which is exactly what search-as-you-type needs:

Future<void> onQueryChanged(String query) async {
  final result = await client.getList<Product>(
    'search',
    query: {'q': query},
    fromJson: Product.fromJson,
    cancelTag: 'search', // cancels the previous search
  );
  if (result.error is RequestCanceledException) return; // superseded, ignore it
  // ...
}

Pass cancelOld: false to let requests with the same tag run side by side. They share one token, so cancelling the tag still cancels them all.

While the response is being parsed

Cancelling is honoured while the response is mapped to your model, not only while it is in flight. If the token is cancelled before fromJson finishes, the result is a RequestCanceledException and the parsed value is dropped, even if the mapping was running in an isolate.

Streams

Tokens and tags work for streams too: cancelling ends the stream with a RequestCanceledException and aborts the HTTP request.