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.cn/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.

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:

• material-io.cn/design/components/buttons.html#toggle-button