Flutter - Using CheckboxListTile Widget Examples

This tutorial shows you how to use CheckboxListTile widget in Flutter.

If you need to have an input where the user can select multiple choices, using checkbox is the common solution. Flutter has a widget called Checkbox for that purpose. However, in many cases, you may also want to add text or icon to the checkbox. Using Checkbox with Icon and Text can be the solution, but Flutter provides an alternative that makes it much easier for us.

CheckboxListTile is a widget that combines a checkbox and a list tile. It allows you to create a checkbox along with the title, subtitle, and icon without the need of creating a separate widget for each part.

Creating CheckboxListTile

The constructor of CheckboxListTile has a lot of parameters, you can see the list on the properties section. But there are only two required parameters. You have to pass value (bool) and onChanged (void Function(bool)).

For example, there is a state variable _isChecked which is passed as value property.

   bool _isChecked = false;

Below is the basic example of how to create a CheckboxListTile.

  CheckboxListTile(
    value: _isChecked,
    onChanged: (bool value) {
      setState(() {
        _isChecked = value;
      });
    },
  )

Output:

 

As you can see, the code above only generates a plain CheckboxListTile. Usually we also need to set the title property. In addition, we can also add a border so that the user can see the area of a CheckboxListTile more clearly. To perform check or uncheck, tap any area of the CheckboxListTile (in this example, any area inside the border). No need to tap exactly on the checkbox icon.

  Container(
    decoration: BoxDecoration(border: Border.all(color: Colors.teal)),
    child: CheckboxListTile(
      title: const Text('Woolha.com'),
      value: _isChecked,
      onChanged: (bool value) {
        setState(() {
          _isChecked = value;
        });
      },
    ),
  ),

Output:

 

Adding Subtitle

The subtitle property can be used to add a Widget below the title. Usually it's used for adding description.

  Container(
    decoration: BoxDecoration(border: Border.all(color: Colors.teal)),
    child: CheckboxListTile(
      title: const Text('Woolha.com'),
      subtitle: const Text('A programming blog'),
      value: _isChecked,
      onChanged: (bool value) {
        setState(() {
          _isChecked = value;
        });
      },
    ),
  ),

Output:

 

Adding Secondary Widget (Icon)

You can pass a Widget as secondary property. It will be rendered on the opposite side of the check box. Typically it's used to add an Icon or an image.

  Container(
    decoration: BoxDecoration(border: Border.all(color: Colors.teal)),
    child: CheckboxListTile(
      title: const Text('Woolha.com'),
      subtitle: const Text('A programming blog'),
      secondary: const Icon(Icons.web),
      value: _isChecked,
      onChanged: (bool value) {
        setState(() {
          _isChecked = value;
        });
      },
    ),
  ),

Output:

 

Customizing Colors

You can use activeColors to set the color of the checkbox when it's checked. For changing the color of the check icon, set the value of checkboxColor property. You can apply the activeColors to the text and icon when the checkbox is checked by setting selected property value to true. Please be careful because Flutter doesn't synchronize the values of value and selected properties or check if both values are the same.

  Container(
    decoration: BoxDecoration(border: Border.all(color: Colors.teal)),
    child: CheckboxListTile(
      title: const Text('Woolha.com'),
      subtitle: const Text('A programming blog'),
      secondary: const Icon(Icons.web),
      activeColor: Colors.red,
      checkColor: Colors.yellow,
      selected: _isChecked,
      value: _isChecked,
      onChanged: (bool value) {
        setState(() {
          _isChecked = value;
        });
      },
    ),
  )

Output:

 

Properties

Here's the list of properties of CheckboxListTile you can pass in the constructor.

• Key key: The widget key, used to control if it should be replaced.
• bool value *: If true, the checkbox is checked. If false, the checkbox is unchecked.
• void Function(bool) onChanged *: A callback function that will be called when the user checks or unchecks the checkbox.
• Color activeColor : The color when the checkbox is checked.
• Color checkColor : The color of the check icon when the checkbox is checked.
• Widget title : The primary content of the list tile.
• Widget subtitle : Additional content below the title.
• Widget secondary : A widget to be displayed on the opposite side of the checkbox.
• bool isThreeLine : Whether this list tile is intended to display three lines of text.. Defaults to false.
• bool dense : Whether this list tile is part of a vertically dense list.
• bool selected : Whether to render icons and text in the activeColor. Defaults to false.
• ListTileControlAffinity controlAffinity : Where to place the control relative to the text. Defaults to ListTileControlAffinity.platform.

*: required