Future Debounce Button (FDB)

Button for asynchronous calls. Keeps your code clean, improves UI/UX through visual indication.

Future Debounce Button

Features

A button widget that provides complete boilerplate for handling and debouncing of asynchronous requests (API calls etc.). The FDB button handles the future (debounce, abort, block) and indicates its state based on the state of that future and other provided parameters.

Getting started

The only required parameter for this button is the onPressed future. Everything else is optional.

// A button that handles a future of type `Future<int>`
FutureDebounceButton<int>(
    onPressed: // TODO: (required) a future to handle
    onSuccess: // TODO: (optional) what to do with the result of the future
    onError: // TODO: (optional) your error handler
    onAbort: // TODO: (optional) what to do if the user canceled the request
);

The following example displays a "Submit" OutlinedButton widget, which triggers a future. If the future fails - the button will enter the error state for 2 seconds. If the future completes successfully - the button will enter success state forever, preventing user from calling the future again.

/// Submit request to server
Future<bool> submit() async {
    // ...
}

   // ...

/// A button that says 'Submit'
FutureDebounceButton<bool>(
    buttonType: FDBType.outlined, // Shows OutlinedButton widget
    onPressed: submit,
    actionCallText: 'Submit',
    errorStateDuration: Duration(seconds:2), // show 'Error' for 2 seconds
    successStateDuration: null // will lock in 'Success!' forever
);

Button Types

The button type can be selected from one of the following values: elevated, filled, filledTonal, outlined and text. See buttonType property of FDB:

Value Material Widget
FDBType.elevated ElevatedButton
FDBType.filled FilledButton
FDBType.filledTonal FilledButton.tonal
FDBType.outlined OutlinedButton
FDBType.text TextButton

Future Debounce Button Types

States

The button manages its own state based on the state of the future provided to it. The possible states are:

  • disabled - button is either completely disabled, or disabled for the duration of debounceDuration value after the button was pressed (see Properties > debounceDuration).
  • ready - the button is in its normal "call to action" state. In this state it displays either actionCallChild widget, actionCallText text, or text 'Go' if none of those values are provided.
  • loading - the button has been pressed and the future is executing. The onAbort handler is not provided to the button. The button in this state displays either loadingChid widget, loadingText text, or the default CircularProgressIndicator widget if none of the former is provided. Clicking on the button in this state does nothing. The button awaits for the future to complete or time out.
  • abort - the abort button has been pressed while the future was executing. The button displays either abortPressedChild widget, abortPressedText text, or Cancelled text if none of the former are provided. See the abortStateDuration property for more options on this state. When the user presses the abort button - the future is abandoned.
  • success - the future has completed with a value. The value is passed to the onSuccess handler if one is provided. The button displays either successChild widget, successText text, or Success! text if none of the former are provided. See the successStateDuration property for more options on this state
  • error - the future has completed with an error or timed out. The error and the stack trace are passed to the onError handler if one is provided. The button displays either errorChild widget, errorText text, or Error text if none of the former are provided. See the errorStateDuration property for more options on this state

API

The following handlers and properties are available for customization:

Handlers

The following handlers are available:

Handler Required Description
onPressed required a future to handle
onSuccess optional called when the onPressed future has completed with a value.
onError optional The future has produced an error. The error and stackTrace objects are passed to the method.
onAbort optional If onAbort handler is provided, the button becomes "abortable" (the future could be abandoned and the possible result is dropped instead of being fed to onSuccess handler). If onAbort is not provided - the button will lock in the "loading" state until the future completes with success, error, or times out (see timeout property).
onStateChange optional Notifies its listeners about the button's state changes. The possible values as per FDBState enum

Properties

Property Type Default value Description
General
enabled bool true if enabled is false - the button will be disabled
buttonType enum FDBType.filled Allows you to choose from one of the five avaliable button widgets. See Button Types above
Ready state
actionCallChild Widget? null Call to action (ready) state widget. This widget is displayed when the button is ready to be pressed. This overrides the actionCallText text
actionCallText String? null Displays provided text. Defaults to Go if left null
actionCallButtonStyle ButtonStyle? null Button style for the ready/disabled state. Uses theme defaults if left null
Loading state
loadingChild Widget? null Widget to show when the future is running (non-abortable). This overrides loadingText text
loadingText String? null Text to display when the future is running (non-abortable). Displays CircularProgressIndicator widget if left null
loadingButtonStyle ButtonStyle? null Button style for the loading state. Uses theme defaults if left null
Abort state
abortChild Widget? null Widget to show when the future is running (abortable), This overrides abortText text
abortPressedChild Widget? null Widget to show when the user presses abort button, This overrides abortPressedText text
abortText String? null Text to display when the future is running (abortable). Displays CircularProgressIndicator widget with Abort text if left null
abortPressedText String? null Text to display when the user presses abort button. Displays text widget with Cancelled text if left null
abortButtonStyle ButtonStyle? null Button style for the abort state. Uses theme defaults if left null
abortStateDuration Duration 1s The duration for which the abort state is maintained. If abortStateDuration is set to null - the abort state will never clear. If abortStateDuration is set to Duration.zero - the abort state will clear instantly
Error state
errorChild Widget? null Widget to show when the future has failed or timed out. This overrides errorText text
errorText String? null Text to display when the future has failed or timed out. Displays Error text if left null
errorButtonStyle ButtonStyle? null Button style for the error state. Uses theme internal static style if left null
errorStateDuration Duration 1s The duration for which the error state is maintained. If errorStateDuration is set to null - the error state will never clear. If errorStateDuration is set to Duration.zero - the error state will clear instantly
Success state
successChild Widget? null Widget to show when the future has completed with a value. This overrides successText text
successText String? null Text to display when the future has completed with a value. Displays Success! text if left null
successButtonStyle ButtonStyle? null Button style for the success state. Uses theme internal static style if left null
successStateDuration Duration 1s The duration for which the error state is maintained. If successStateDuration is set to null - the success state will never clear. If successStateDuration is set to Duration.zero - the error state will clear instantly
Debounce and Timeout
debounceDuration Duration 250ms A delay between the first hit of the button and until the button starts accepting Abort hits (debounce). This is needed to prevent users from double-clicking the button.
timeout Duration? null Maximum duration of a future. If timeout is set and the time ran out - the FDB will produce TimeoutException and port it to onError handler if one is provided

Libraries

button_controller
fdb_widget
future_debounce_button