M3 Floating Toolbar

A Flutter package that provides a Material Design 3 floating pill-style toolbar widget. Perfect for creating action bars with icon-only or labeled buttons that follow Material You design principles.

Features

• 🎨 Material Design 3 styling with automatic theming
• 🎛️ Standard and vibrant color configurations
• ↔️ Horizontal and vertical layouts
• 🔘 Support for icon-only, label-only, and icon + label action buttons
• ✅ Selected state for toggle and navigation style toolbars
• ♿ Built-in accessibility with semantic labels, tooltips, and 48dp touch targets
• 🎯 Optional FloatingActionButton integration
• ⚙️ Customizable elevation, padding, spacing, and colors
• 📱 Responsive layout that adapts to content

Getting started

Add this package to your pubspec.yaml:

dependencies:
  m3_floating_toolbar: ^0.2.1

Then run:

flutter pub get

Import the package in your Dart code:

import 'package:m3_floating_toolbar/m3_floating_toolbar.dart';
import 'package:m3_floating_toolbar/m3_floating_toolbar_action.dart';

Usage

Basic toolbar with icon-only buttons

M3FloatingToolbar(
  actions: [
    M3FloatingToolbarAction(
      icon: Icons.home,
      semanticLabel: 'Home',
      tooltip: 'Home',
      onPressed: () => print('Home pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.explore,
      semanticLabel: 'Explore',
      tooltip: 'Explore',
      onPressed: () => print('Explore pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.person,
      semanticLabel: 'Profile',
      tooltip: 'Profile',
      onPressed: () => print('Profile pressed'),
    ),
  ],
)

Toolbar with labeled buttons

M3FloatingToolbar(
  actions: [
    M3FloatingToolbarAction(
      icon: Icons.home,
      label: 'Home',
      semanticLabel: 'Home tab',
      onPressed: () => print('Home pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.explore,
      label: 'Explore',
      semanticLabel: 'Explore tab',
      onPressed: () => print('Explore pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.person,
      label: 'Profile',
      semanticLabel: 'Profile tab',
      onPressed: () => print('Profile pressed'),
    ),
  ],
)

Omit icon to render a label-only button. Every action requires an icon, a label, or both.

M3FloatingToolbarAction(
  label: 'Profile',
  semanticLabel: 'Profile tab',
  onPressed: () => print('Profile pressed'),
)

Selected actions

Set selected: true to highlight an action with the variant's selected color roles. The standard variant uses secondaryContainer/onSecondaryContainer and the vibrant variant uses surfaceContainer/onSurface.

M3FloatingToolbar(
  actions: [
    M3FloatingToolbarAction(
      icon: Icons.home,
      semanticLabel: 'Home',
      tooltip: 'Home',
      onPressed: () => print('Home pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.explore,
      label: 'Explore',
      semanticLabel: 'Explore',
      selected: true,
      onPressed: () => print('Explore pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.person,
      semanticLabel: 'Profile',
      tooltip: 'Profile',
      onPressed: () => print('Profile pressed'),
    ),
  ],
)

With FloatingActionButton

M3FloatingToolbar(
  actions: [
    M3FloatingToolbarAction(
      icon: Icons.home,
      semanticLabel: 'Home',
      onPressed: () => print('Home pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.explore,
      semanticLabel: 'Explore',
      onPressed: () => print('Explore pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.notifications,
      semanticLabel: 'Notifications',
      onPressed: () => print('Notifications pressed'),
    ),
  ],
  floatingActionButton: FloatingActionButton(
    onPressed: () => print('Create post pressed'),
    child: Icon(Icons.add_box),
  ),
)

Vertical layout

Set direction to Axis.vertical for the vertical floating toolbar configuration, typically anchored to a side edge of the screen.

M3FloatingToolbar(
  direction: Axis.vertical,
  actions: [
    M3FloatingToolbarAction(
      icon: Icons.home,
      semanticLabel: 'Home',
      tooltip: 'Home',
      onPressed: () => print('Home pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.explore,
      semanticLabel: 'Explore',
      tooltip: 'Explore',
      onPressed: () => print('Explore pressed'),
    ),
    M3FloatingToolbarAction(
      icon: Icons.person,
      semanticLabel: 'Profile',
      tooltip: 'Profile',
      onPressed: () => print('Profile pressed'),
    ),
  ],
)

When a floatingActionButton is provided, it is placed below the toolbar.

Color variants

The toolbar follows the Material Design 3 toolbar color configurations. The standard variant (default) uses surfaceContainer, and vibrant uses primaryContainer.

M3FloatingToolbar(
  variant: M3FloatingToolbarVariant.vibrant,
  actions: [...],
)

Customization

Defaults follow the Material Design 3 specs: 64dp container height, full (stadium) corner shape, 8dp internal padding, and 4dp between items. The specs also call for a 16dp minimum margin from the screen edge, which is applied by the layout that positions the toolbar.

Floating toolbars are elevated by default. Set elevation: 0 when the content beneath the toolbar is already visually distinct.

M3FloatingToolbar(
  actions: [...],
  elevation: 4,
  internalPadding: EdgeInsets.symmetric(horizontal: 20, vertical: 16),
  spacing: 12,
  color: Colors.blue.shade100,
  foregroundColor: Colors.blue.shade900,
)

Additional information

For a complete working example, see the example directory.

VS Code command for Flutter previews

This workspace includes a VS Code launch configuration named Launch Flutter Previews.

Open Run and Debug and select:

1. Launch Flutter Previews
2. Start debugging

This runs:

flutter widget-preview start

To report issues or contribute to this package, visit the GitHub repository.