fab_dial: a Material 3 speed-dial FAB for Flutter built on OverlayPortal

A speed dial is the floating action button that opens into a short list of actions: tap “+”, then pick “Note” or “Photo”. It is a small piece of UI, but it has to cooperate with a lot of the framework. It draws a scrim over the page, so it needs an overlay. It sits in the Scaffold’s FAB slot, so it moves when a snack bar or the keyboard appears. The back button should close it. And it should go away cleanly when the user navigates to another page.

Those are the places where a speed dial tends to break: an overlay left on top of the next page, an assertion when the widget is disposed, a label on the wrong side in Arabic. fab_dial is a Flutter package that rebuilds the speed dial around OverlayPortal and Material 3. The README describes it as a clean-room replacement for flutter_speed_dial, with keyboard, screen-reader, RTL and predictive-back support.

What it does

It stays a real FAB. The main button is a real FloatingActionButton in Scaffold.floatingActionButton. Every FloatingActionButtonLocation works, including centerDocked and endContained. The dial follows the button when a snack bar, a bottom bar or the keyboard moves it.

The overlay is an OverlayPortal. There is no manual OverlayEntry bookkeeping. The overlay goes away when the dial is disposed, and it closes when another route (a page, a dialog or a bottom sheet) is pushed on top.

Material 3 defaults. It uses M3 FAB shapes and colours: a 56dp main button and 40dp small child buttons with a 48dp tap target. Label chips use surfaceContainerHigh. A FabDialTheme ThemeExtension sets app-wide defaults.

Four directions. up, down, left and right. Labels can go at the start, at the end, above or below each button, and you can flip them with switchLabelPosition.

RTL. start and end labels mirror in right-to-left layouts, and an extended button anchors its children on the correct end.

Keyboard and semantics. The main button reports an expanded or collapsed state. Opening the dial moves focus into it. Tab walks the children in order, and focus stays inside the open dial. Escape closes the dial and returns focus to the main button. The scrim has a “Dismiss” action for screen readers.

Back handling. A PopScope makes back close the dial first. Predictive back is disabled only while the dial is open.

Reduced motion. When MediaQuery.disableAnimations is set, the dial opens and closes instantly. Otherwise the animations are staggered and curve-driven, and the nearest child animates in first.

Two-way control. Pass a ValueNotifier<bool> as openCloseDial to open and close the dial from code. The dial writes back when it opens or closes by itself, and it survives rapid toggling and notifier swaps.

Children can change while the dial is open. You can add, remove or hide them, even from a child’s own onTap.

There is also an extended variant, animatedIcon, a rotation animation, hero tag, tooltips, buttonSize and childrenButtonSize, spacing and child padding.

How to use it

Add it from GitHub:

dependencies:
  fab_dial:
    git: https://github.com/AbdeldjalilChougui/fab_dial

Put a FabDial where you would put a FloatingActionButton:

import 'package:fab_dial/fab_dial.dart';
import 'package:flutter/material.dart';

class NotesPage extends StatelessWidget {
  const NotesPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: const Center(child: Text('Notes')),
      floatingActionButton: FabDial(
        icon: Icons.add,
        activeIcon: Icons.close,
        tooltip: 'Create',
        children: [
          FabDialChild(
            child: const Icon(Icons.note_add_outlined),
            label: 'Note',
            onTap: () => debugPrint('note'),
          ),
          FabDialChild(
            child: const Icon(Icons.photo_camera_outlined),
            label: 'Photo',
            onTap: () => debugPrint('photo'),
          ),
        ],
      ),
    );
  }
}

For a button with a text label, use the extended constructor:

FabDial.extended(
  icon: Icons.add,
  label: const Text('Create'),
  activeLabel: const Text('Close'),
  children: [/* ... */],
)

To open it from code:

final dialOpen = ValueNotifier<bool>(false);

FabDial(openCloseDial: dialOpen, children: [/* ... */]);

dialOpen.value = true; // opens; the dial sets it back to false when it closes

And to set defaults for the whole app:

MaterialApp(
  theme: ThemeData(
    extensions: const [
      FabDialTheme(
        overlayOpacity: 0.6,
        spaceBetweenChildren: 16,
        animationDuration: Duration(milliseconds: 200),
      ),
    ],
  ),
);

Values set on a FabDial win over the theme, and theme values win over the Material 3 defaults. The example/ folder has a runnable demo of every option.

Migrating from flutter_speed_dial

Most code only needs its names changed: SpeedDial becomes FabDial, SpeedDialChild becomes FabDialChild, and SpeedDialDirection becomes FabDialDirection. The README has a full table, parameter by parameter. Most parameters keep their names: icon, activeIcon, openCloseDial, onOpen, onClose, overlayColor, closeDialOnPop, spacing, tooltip, heroTag and the rest.

A few things are different:

  • mini: true becomes buttonSize: const Size(40, 40).
  • labelShadow is gone. Use FabDialTheme.labelElevation.
  • gradient, dialRoot, onOpenBuilder and labelTransitionBuilder are not supported. The table gives the alternative for each, such as a custom child or updating children with setState.
  • Child buttons default to 40dp instead of 56dp. spacing defaults to 16 and spaceBetweenChildren to 12.
  • When a route is pushed, the dial closes without animating, even with closeManually: true. It no longer leaves a scrim over the next page.
  • children[0] is still the child nearest the main button.

Things to know

  • Screen readers can still reach the page under the scrim. OverlayPortal reports the dial’s semantics at the button’s position in the tree. So the scrim cannot hide the page underneath from screen readers the way a modal route does. Keyboard focus is trapped inside the open dial, but a screen reader can still reach page content.
  • Directions are physical. left does not become right in RTL. Only labels mirror.
  • No scrolling. A very long list of children can run off-screen. There is no scrolling or wrapping.
  • Extended buttons align differently. Children align on an end square of the button, one button-height wide. On a regular button they align on the button’s centre.
  • Tested on one Flutter version. The README says it was tested on Flutter 3.35.6 only. The declared minimum, Flutter 3.24, has not been verified by running the tests on it.

Why I built it

The README lists the upstream problems this package fixes, with the issue numbers from the flutter_speed_dial tracker. They fall into a few groups: the overlay stays on top after pushing a route or a sheet and the next page is unclickable; OverlayEntry asserts on dispose; the overlay does not cover the bottom navigation bar; the dial does not follow the FAB when a snack bar appears; changing the children breaks or closes the dial; the ValueNotifier gets out of sync; labels are misplaced in RTL; WillPopScope is deprecated; and widgets under the overlay stay focusable.

Most of these share a cause: the overlay is managed by hand, apart from the widget that owns it. OverlayPortal ties the overlay’s life to the widget, so a whole group of bugs has nowhere to live. Starting from that, I rebuilt the dial with the things a FAB should have today: Material 3 sizes and colours, focus handling, semantics, RTL and predictive back. Each fix has a regression test in test/regressions_test.dart or test/layout_test.dart.

It is a clean-room implementation: it keeps the parameter names so migration is mostly a rename, but it does not reuse the other package’s code.

Get the code

The source, the README with the full migration table and the list of fixed issues, the example app and the tests are on GitHub: https://github.com/AbdeldjalilChougui/fab_dial. It’s MIT licensed. Issues and pull requests are welcome.

Originally published at abdeldjalilchougui.biz.

Leave a Reply