FloatingActionButton in Flutter

What is FloatingActionButton in Flutter?

FloatingActionButton (FAB) is a Flutter Material widget that renders a prominent button floating above a screen's content, intended for that screen’s single most important action. In Material 3 (the default since Flutter 3.16), it uses a rounded-square shape by default; the classic circular look from Material 2 is still available via shape: CircleBorder().

It's typically placed through Scaffold's floatingActionButton slot rather than directly inside the body layout. Material 3 provides three standard sizes – FloatingActionButton.small, the default size, and .large – as well as .extended, which displays an icon and label in a wider, pill-shaped button.

Key facts at a glance

• FloatingActionButton in Flutter is part of the core Material library and requires no additional package.
• It's placed through Scaffold.floatingActionButton, not as a regular child widget in the body.
• Material guidance recommends at most one FAB per screen.
• FloatingActionButton.extended adds a label next to the icon; .small and .large change only the FAB’s size.
• Every FAB has a default heroTag. Using more than one FAB with the default tag on the same route causes a runtime error; assign unique heroTag values when multiple FABs are needed.

How do I add a FloatingActionButton in Flutter?

A FloatingActionButton needs an onPressed callback and usually an Icon as its child.

import 'package:flutter/material.dart';

class NoteEditorScreen extends StatelessWidget {
  const NoteEditorScreen({super.key, required this.onAddNote});

  final VoidCallback onAddNote;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: const Center(child: Text('Notes')),
      floatingActionButton: FloatingActionButton(
        onPressed: onAddNote,
        tooltip: 'Add note',
        child: const Icon(Icons.add),
      ),
    );
  }
}

Scaffold positions the FAB automatically. By default, it uses FloatingActionButtonLocation.endFloat, which places the FAB near the bottom end of the Scaffold (typically the bottom-right). You can customize its position through Scaffold.floatingActionButtonLocation, for example with FloatingActionButtonLocation.centerFloat or FloatingActionButtonLocation.centerDocked.

See the FloatingActionButtonLocation documentation for the available positioning options.

How do I use multiple FloatingActionButtons in Flutter without crashing?

Two FABs on the same route without a distinct heroTag trigger "there are multiple heroes that share the same tag" at runtime, because Flutter derives a default tag from the FAB's type.

Row(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: [
    FloatingActionButton(
      heroTag: 'fab-camera',
      onPressed: () {},
      child: const Icon(Icons.camera_alt),
    ),
    FloatingActionButton(
      heroTag: 'fab-gallery',
      onPressed: () {},
      child: const Icon(Icons.photo_library),
    ),
  ],
),

Give each FAB a unique heroTag if you want to keep Hero animations. Alternatively, set heroTag: null to disable the Hero for a FAB.

When should I use a FloatingActionButton – and when not?

Use it when

• The screen has a clear primary action, such as creating, adding, sharing, or composing.
• The action benefits from being kept prominently accessible above the screen's content.
• You want .extended to pair the icon with a short label for clarity.

Avoid it when

• The action is better represented by a standard button within the screen's content or by an action in the AppBar.
• The screen needs several equally important actions – consider using regular buttons, an AppBar, or a BottomAppBar instead.
• The action isn't important enough to deserve the visual prominence of a FAB.

Best practices

1. Keep one FAB per screen – Material guidance treats this as the norm, and a second FAB usually signals the design needs a rethink, not a second heroTag.
2. Provide a meaningful tooltip for icon-only FABs – it describes the action and provides a textual representation that can improve accessibility.
3. Use unique heroTag values when multiple FABs share a route – the default tag is shared, so multiple FABs on the same route otherwise cause a Hero tag conflict. Set heroTag: null instead if you don't want a FAB to participate in Hero animations.
4. Use .extended when the action isn't self-evident from an icon alone – a label removes the guesswork.
5. Let Scaffold position the FAB – use Scaffold.floatingActionButtonLocation for standard positioning rather than manually positioning the FAB with Stack or Positioned.
6. Use floatingActionButtonTheme for consistent styling – configure ThemeData.floatingActionButtonTheme when you want to apply shared FAB properties such as colors, shape, or elevation across the app instead of repeating them on individual buttons.

Common mistakes

• Adding a second FAB without a unique heroTag. By default, FABs use a shared hero tag. If multiple FABs with the default tag are present on the same route, Flutter throws a Hero tag conflict. Give each FAB a unique heroTag, or set heroTag: null if it should not participate in Hero animations.
• Placing FloatingActionButton inside the body instead of Scaffold.floatingActionButton. This bypasses Scaffold's standard FAB positioning and its integration with locations such as centerDocked, where a BottomAppBar can provide a notch for the FAB.
• Using a FAB for a secondary action. A FAB is intended to promote a primary action, so a less important action is often better represented by an appropriate standard button, such as a FilledButton or OutlinedButton, depending on its emphasis.
• Forgetting tooltip because "the icon is obvious." A tooltip describes the action and provides a textual representation that can improve accessibility, especially when the action is represented by an icon alone.