Flutter - Using SwitchListTile Widget Examples

This tutorial shows you how to use SwitchListTile in Flutter.

SwitchListTile is a widget that wraps a ListTile and a Switch. It's usually used as a child of a ListView where the content has a Switch widget. A common usage is for displaying an item in a setting page where the user can toggle a particular setting on and off. Below are the explanation and examples of how to use the widget.

Using SwitchListTile

Here's the constructor of SwitchListTile.

  const SwitchListTile({
    Key key,
    @required this.value,
    @required this.onChanged,
    this.activeColor,
    this.activeTrackColor,
    this.inactiveThumbColor,
    this.inactiveTrackColor,
    this.activeThumbImage,
    this.inactiveThumbImage,
    this.title,
    this.subtitle,
    this.isThreeLine = false,
    this.dense,
    this.contentPadding,
    this.secondary,
    this.selected = false,
    this.autofocus = false,
    this.controlAffinity = ListTileControlAffinity.platform,
  })

There are two arguments you have to pass. The first one is value which is a boolean that determines whether the switch is on or off. Usually you need a state variable to be passed as value. The other required argument is onChanged which is a callback function that will be called every time the user toggles the switch. The most common thing to do inside the function is updating the value of the state variable passed as value.

  SwitchListTile(
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Adding Title and Subtitle

The output of the previous example looks a bit empty. Besides the required arguments, it's very common to pass title argument which is a widget to be used as the primary content of the tile. It can be any Widget, but usually a Text widget.

  SwitchListTile(
    title: Text('Bluetooth'),
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

In addition, you can also pass another widget as subtitle to be displayed below the title. By default, Flutter will set the font size of the subtitle to be smaller than the title's.

  SwitchListTile(
    title: Text('Bluetooth'),
    subtitle: Text('Used to transfer data wirelessly'),
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Adding Secondary Widget

Another thing you can add is a secondary widget. It's a widget to be displayed at the opposite side of the switch. Usually, it's an icon that represents the content of the tile. You need to pass the widget as secondary argument.

  SwitchListTile(
    title: Text('Bluetooth'),
    secondary: Icon(Icons.bluetooth),
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Setting Colors

You can change the color of the switch's track and thumb. When the switch is active, pass Color values as activeColor and activeTrackColor to set the colors of the thumb and the track respectively. For setting the colors of the thumb and the track when the switch is inactive, pass inactiveThumbColor and inactiveTrackColor arguments respectively.

  SwitchListTile(
    title: Text('Bluetooth'),
    activeColor: Colors.teal,
    activeTrackColor: Colors.green,
    inactiveThumbColor: Colors.black,
    inactiveTrackColor: Colors.blueGrey,
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Setting Thumb Images

The thumb of the switch can be customized to display an image. To set the thumb image when the switch is active, pass an ImageProvider as activeThumbImage. For the thumb when the switch is inactive, pass an ImageProvider as inactiveThumbImage.

  SwitchListTile(
    title: Text('Bluetooth'),
    activeThumbImage: AssetImage('assets/images/bluetooth-on.png'),
    inactiveThumbImage: AssetImage('assets/images/bluetooth-off.png'),
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Setting Control Affinity

By default, Flutter places the control and the secondary widget depending on the platform. For example, the control is on the right of the title on Android which means the secondary widget is on the left of the title. If you don't want the position of the control to depend on the platform, you can pass ListTileControlAffinity enum as controlAffinity argument. The possible values are:

• leading: Position the control on the leading edge. If there's a secondary widget, it will be placed on the trailing edge.
• trailing: Position the control on the trailing edge. If there's a secondary widget, it will be placed on the leading edge.
• platform: Position the control depends on the platform. If there's a secondary widget, it will be placed on the opposite side.

  SwitchListTile(
    title: Text('Bluetooth'),
    secondary: Icon(Icons.bluetooth),
    controlAffinity: ListTileControlAffinity.leading,
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Setting Density

If the list tile is part of a vertically dense list, you can pass dense argument with the value set to true. By setting dense to true, Flutter will do some adjustments such as reducing the font size. If you don't pass the argument, the value defaults to ListTileTheme.dense.

  SwitchListTile(
    title: Text('Bluetooth'),
    dense: true,
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Setting Content Padding

To set the internal padding of the tile, pass an EdgeInsetsGeometry value as contentPadding argument.

  SwitchListTile(
    title: Text('Bluetooth'),
    contentPadding: EdgeInsets.all(30),
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

Output:

 

Using SwitchListTile.adaptive

SwitchListTile.adaptive creates a wrapped Switch using Switch.adaptive. It will create a CupertinoSwitch on iOS or a material design switch otherwise. The usage is very similar and it has the same parameters as using SwitchListTile. You only need to call the named constructor instead of the usual constructor.

  SwitchListTile.adaptive(
    value: _isBluetoothOn,
    onChanged: (bool value) {
      setState(() {
        _isBluetoothOn = value;
      });
    }
  )

 

SwitchListTile Parameters

• Key key: The widget's key.
• bool value *: Whether this switch is on or off.
• ValueChanged<bool> onChanged *: A callback called when the user toggles the switch.
• Color activeColor: The thumb color when this switch is on.
• Color activeTrackColor: The track color when this switch is on.
• Color inactiveThumbColor: The thumb color when this switch is off.
• Color inactiveTrackColor: The track color when this switch is off.
• ImageProvider<Object> activeThumbImage: An image to use on the thumb of this switch when the switch is on.
• ImageProvider<Object> inactiveThumbImage: An image to use on the thumb of this switch when the switch is off.
• Widget title: The primary content of the list tile.
• Widget subtitle: Additional content displayed below the title.
• 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.
• EdgeInsetsGeometry contentPadding: Internal padding of tht tile.
• Widget secondary: A widget to display on the opposite side of the tile from the switch.
• bool selected: Whether to render icons and text in activeColor. Defaults to false.
• bool autofocus: Whether this widget will be selected as the initial focus when no other node in its scope is currently focused. Defaults to false.
• ListTileControlAffinity controlAffinity: Used to set the position of control and secondary relative to text . Defaults to ListTileControlAffinity.platform.

*: required