ToggleButtons class

A set of toggle buttons.

The list of children are laid out along direction. The state of each button is controlled by isSelected, which is a list of bools that determine if a button is in an unselected or selected state. They are both correlated by their index in the list. The length of isSelected has to match the length of the children list.

There is a Material 3 version of this component, SegmentedButton, that's preferred for applications that are configured for Material 3 (see ThemeData.useMaterial3).

Updating to SegmentedButton

There is a Material 3 version of this component, SegmentedButton, that's preferred for applications that are configured for Material 3 (see ThemeData.useMaterial3). The SegmentedButton widget's visuals are a little bit different, see the Material 3 spec at m3.material.io/components/segmented-buttons/overview for more details. The SegmentedButton widget's API is also slightly different. While the ToggleButtons widget can have list of widgets, the SegmentedButton widget has a list of ButtonSegments with a type value. While the ToggleButtons uses a list of boolean values to determine the selection state of each button, the SegmentedButton uses a set of type values to determine the selection state of each segment. The SegmentedButton.style is a ButtonStyle style field, which can be used to customize the entire segmented button and the individual segments.

This sample shows how to migrate ToggleButtons that allows multiple or no selection to SegmentedButton that allows multiple or no selection.
link

To create a local project with this code sample, run:
flutter create --sample=material.ToggleButtons.1 mysample

This example showcase ToggleButtons in various configurations.
link

To create a local project with this code sample, run:
flutter create --sample=material.ToggleButtons.2 mysample

Customizing toggle buttons

Each toggle's behavior can be configured by the onPressed callback, which can update the isSelected list however it wants to.

Here is an implementation that allows for multiple buttons to be simultaneously selected, while requiring none of the buttons to be selected.

ToggleButtons(
  isSelected: isSelected,
  onPressed: (int index) {
    setState(() {
      isSelected[index] = !isSelected[index];
    });
  },
  children: const <Widget>[
    Icon(Icons.ac_unit),
    Icon(Icons.call),
    Icon(Icons.cake),
  ],
),

Here is an implementation that requires mutually exclusive selection while requiring at least one selection. This assumes that isSelected was properly initialized with one selection.

ToggleButtons(
  isSelected: isSelected,
  onPressed: (int index) {
    setState(() {
      for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
        if (buttonIndex == index) {
          isSelected[buttonIndex] = true;
        } else {
          isSelected[buttonIndex] = false;
        }
      }
    });
  },
  children: const <Widget>[
    Icon(Icons.ac_unit),
    Icon(Icons.call),
    Icon(Icons.cake),
  ],
),

Here is an implementation that requires mutually exclusive selection, but allows for none of the buttons to be selected.

ToggleButtons(
  isSelected: isSelected,
  onPressed: (int index) {
    setState(() {
      for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
        if (buttonIndex == index) {
          isSelected[buttonIndex] = !isSelected[buttonIndex];
        } else {
          isSelected[buttonIndex] = false;
        }
      }
    });
  },
  children: const <Widget>[
    Icon(Icons.ac_unit),
    Icon(Icons.call),
    Icon(Icons.cake),
  ],
),

Here is an implementation that allows for multiple buttons to be simultaneously selected, while requiring at least one selection. This assumes that isSelected was properly initialized with one selection.

ToggleButtons(
  isSelected: isSelected,
  onPressed: (int index) {
    int count = 0;
    for (final bool value in isSelected) {
      if (value) {
        count += 1;
      }
    }
    if (isSelected[index] && count < 2) {
      return;
    }
    setState(() {
      isSelected[index] = !isSelected[index];
    });
  },
  children: const <Widget>[
    Icon(Icons.ac_unit),
    Icon(Icons.call),
    Icon(Icons.cake),
  ],
),

ToggleButton Borders

The toggle buttons, by default, have a solid, 1 logical pixel border surrounding itself and separating each button. The toggle button borders' color, width, and corner radii are configurable.

The selectedBorderColor determines the border's color when the button is selected, while disabledBorderColor determines the border's color when the button is disabled. borderColor is used when the button is enabled.

To remove the border, set renderBorder to false. Setting borderWidth to 0.0 results in a hairline border. For more information on hairline borders, see BorderSide.width.

See also:

Inheritance

Constructors

ToggleButtons({Key? key, required List<Widget> children, required List<bool> isSelected, void onPressed(int index)?, MouseCursor? mouseCursor, MaterialTapTargetSize? tapTargetSize, TextStyle? textStyle, BoxConstraints? constraints, Color? color, Color? selectedColor, Color? disabledColor, Color? fillColor, Color? focusColor, Color? highlightColor, Color? hoverColor, Color? splashColor, List<FocusNode>? focusNodes, bool renderBorder = true, Color? borderColor, Color? selectedBorderColor, Color? disabledBorderColor, BorderRadius? borderRadius, double? borderWidth, Axis direction = Axis.horizontal, VerticalDirection verticalDirection = VerticalDirection.down})
Creates a set of toggle buttons.
const

Properties

borderColor Color?
The border color to display when the toggle button is enabled and not selected.
final
borderRadius BorderRadius?
The radii of the border's corners.
final
borderWidth double?
The width of the border surrounding each toggle button.
final
children List<Widget>
The toggle button widgets.
final
color Color?
The color for descendant Text and Icon widgets if the button is enabled and not selected.
final
constraints BoxConstraints?
Defines the button's size.
final
direction Axis
The direction along which the buttons are rendered.
final
disabledBorderColor Color?
The border color to display when the toggle button is disabled.
final
disabledColor Color?
The color for descendant Text and Icon widgets if the button is disabled.
final
fillColor Color?
The fill color for selected toggle buttons.
final
focusColor Color?
The color to use for filling the button when the button has input focus.
final
focusNodes List<FocusNode>?
The list of FocusNodes, corresponding to each toggle button.
final
hashCode int
The hash code for this object.
no setterinherited
highlightColor Color?
The highlight color for the button's InkWell.
final
hoverColor Color?
The color to use for filling the button when the button has a pointer hovering over it.
final
isSelected List<bool>
The corresponding selection state of each toggle button.
final
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
mouseCursor MouseCursor?
The cursor for a mouse pointer when it enters or is hovering over the button.
final
onPressed → (void Function(int index)?)
The callback that is called when a button is tapped.
final
renderBorder bool
Whether or not to render a border around each toggle button.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
selectedBorderColor Color?
The border color to display when the toggle button is selected.
final
selectedColor Color?
The color for descendant Text and Icon widgets if the button is selected.
final
splashColor Color?
The splash color for the button's InkWell.
final
tapTargetSize MaterialTapTargetSize?
Configures the minimum size of the area within which the buttons may be pressed.
final
textStyle TextStyle?
The TextStyle to apply to any text in these toggle buttons.
final
verticalDirection VerticalDirection
If direction is Axis.vertical, this parameter determines whether to lay out the buttons starting from the first or last child from top to bottom.
final

Methods

build(BuildContext context) Widget
Describes the part of the user interface represented by this widget.
override
createElement() StatelessElement
Creates a StatelessElement to manage this widget's location in the tree.
inherited
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited