connected_button_group | Flutter package

GitHub stars GitHub license

connected_button_group is a Flutter widget that arranges multiple related controls into a single continuous pill‑shaped container, following the Material 3 Expressive design pattern. The widget supports single‑selection and action‑only modes, split‑buttons, attached menus and automatic overflow handling.

🚀 Features #

Unified control: Arrange a series of buttons into one pill container with coordinated interactions.
Flexible content: Each segment can display text, an icon, or an icon+label combination.
Selection and actions: Use a value and onChanged callback to enable single selection or omit them to treat the group as a toolbar where each segment invokes onPressed.
Menus & split‑buttons: Attach a menu to any item; if a ConnectedButtonItem supplies both a menu and a primary action, it renders as a split‑button with distinct tap targets.
Automatic overflow: When items exceed the available width, the trailing buttons collapse into a “More” menu. If still too wide the group wraps to additional rows.
Customisable layout: Configure overflow strategy, maximum rows, row spacing and internal padding. You can also supply a custom overflow handle.
Theming support: Override colours and styles via a ConnectedButtonGroupThemeData or globally through a ThemeExtension.

🏁 Getting Started #

Add this package to your pubspec.yaml:

dependencies:
  connected_button_group: ^0.0.1

Then install with flutter pub get. To see the widget in action, clone this repository and run the example:

cd example
flutter run

🔧 Usage #

Import the package and create a ConnectedButtonGroup with a list of ConnectedButtonItems. Provide a value and onChanged callback to enable single selection. Omit value and onChanged to use the group in action‑only mode where each item triggers onPressed.

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

enum ViewMode { list, grid, map, settings }

class ExampleWidget extends StatefulWidget {
  const ExampleWidget({super.key});
  @override
  State<ExampleWidget> createState() => _ExampleWidgetState();
}

class _ExampleWidgetState extends State<ExampleWidget> {
  ViewMode _mode = ViewMode.list;

  @override
  Widget build(BuildContext context) {
    return ConnectedButtonGroup<ViewMode>(
      items: [
        ConnectedButtonItem(
          value: ViewMode.list,
          icon: Icons.view_list,
          label: 'List',
        ),
        ConnectedButtonItem(
          value: ViewMode.grid,
          icon: Icons.grid_view,
          label: 'Grid',
        ),
        // Split‑button: default action + menu
        ConnectedButtonItem(
          value: ViewMode.map,
          icon: Icons.map,
          label: 'Map',
          isSplit: true,
          onPrimaryPressed: () {
            // perform default map action
          },
          menu: [
            ConnectedMenuEntry(label: 'Default', value: ViewMode.map),
            ConnectedMenuEntry(label: 'Satellite', value: ViewMode.map),
            ConnectedMenuEntry(label: 'Terrain', value: ViewMode.map),
          ],
        ),
        // Overflow / menu item
        ConnectedButtonItem(
          value: ViewMode.settings,
          icon: Icons.settings,
          label: 'Settings',
          menu: [
            ConnectedMenuEntry(label: 'Profile', value: ViewMode.settings),
            ConnectedMenuEntry(label: 'Logout', value: ViewMode.settings, destructive: true),
          ],
        ),
      ],
      value: _mode,
      onChanged: (mode) => setState(() => _mode = mode),
      onMenuItemSelected: (pair) {
        // Called when a menu entry is selected.
        debugPrint('Selected ${pair.$2.label} from ${pair.$1}');
      },
    );
  }
}

🎯 Examples #

You can find a full example in the example directory. Run it with

flutter run -d chrome

The demo shows a connected group with a split‑button and an overflow menu. Resize the window to watch items collapse into the More menu and wrap to new lines.

⚙️ Parameters #