Switch class

A Material Design switch.

Used to toggle the on/off state of a single setting.

The switch itself does not maintain any state. Instead, when the state of the switch changes, the widget calls the onChanged callback. Most widgets that use a switch will listen for the onChanged callback and rebuild the switch with a new value to update the visual appearance of the switch.

If the onChanged callback is null, then the switch will be disabled (it will not respond to input). A disabled switch's thumb and track are rendered in shades of grey by default. The default appearance of a disabled switch can be overridden with inactiveThumbColor and inactiveTrackColor.

Requires one of its ancestors to be a Material widget.

Material Design 3 provides the option to add icons on the thumb of the Switch. If ThemeData.useMaterial3 is set to true, users can use Switch.thumbIcon to add optional Icons based on the different WidgetStates of the Switch.

This example shows a toggleable Switch. When the thumb slides to the other side of the track, the switch is toggled between on/off.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Switch].

void main() => runApp(const SwitchApp());

class SwitchApp extends StatelessWidget {
  const SwitchApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Switch Sample')),
        body: const Center(child: SwitchExample()),
      ),
    );
  }
}

class SwitchExample extends StatefulWidget {
  const SwitchExample({super.key});

  @override
  State<SwitchExample> createState() => _SwitchExampleState();
}

class _SwitchExampleState extends State<SwitchExample> {
  bool light = true;

  @override
  Widget build(BuildContext context) {
    return Switch(
      // This bool value toggles the switch.
      value: light,
      activeThumbColor: Colors.red,
      onChanged: (bool value) {
        // This is called when the user toggles the switch.
        setState(() {
          light = value;
        });
      },
    );
  }
}

This example shows how to customize Switch using WidgetStateProperty switch properties.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Switch].

void main() => runApp(const SwitchApp());

class SwitchApp extends StatelessWidget {
  const SwitchApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Switch Sample')),
        body: const Center(child: SwitchExample()),
      ),
    );
  }
}

class SwitchExample extends StatefulWidget {
  const SwitchExample({super.key});

  @override
  State<SwitchExample> createState() => _SwitchExampleState();
}

class _SwitchExampleState extends State<SwitchExample> {
  bool light = true;

  @override
  Widget build(BuildContext context) {
    // This object sets amber as the track color when the switch is selected.
    // Otherwise, it resolves to null and defers to values from the theme data.
    const WidgetStateProperty<Color?> trackColor =
        WidgetStateProperty<Color?>.fromMap(<WidgetStatesConstraint, Color>{
          WidgetState.selected: Colors.amber,
        });
    // This object sets the track color based on two WidgetState attributes.
    // If neither state applies, it resolves to null.
    final WidgetStateProperty<Color?> overlayColor =
        WidgetStateProperty<Color?>.fromMap(<WidgetState, Color>{
          WidgetState.selected: Colors.amber.withValues(alpha: 0.54),
          WidgetState.disabled: Colors.grey.shade400,
        });

    return Switch(
      // This bool value toggles the switch.
      value: light,
      overlayColor: overlayColor,
      trackColor: trackColor,
      thumbColor: const WidgetStatePropertyAll<Color>(Colors.black),
      onChanged: (bool value) {
        // This is called when the user toggles the switch.
        setState(() {
          light = value;
        });
      },
    );
  }
}

This example shows how to add icons on the thumb of the Switch using the Switch.thumbIcon property.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Switch].

void main() => runApp(const SwitchApp());

class SwitchApp extends StatelessWidget {
  const SwitchApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Switch Sample')),
        body: const Center(child: SwitchExample()),
      ),
    );
  }
}

class SwitchExample extends StatefulWidget {
  const SwitchExample({super.key});

  @override
  State<SwitchExample> createState() => _SwitchExampleState();
}

class _SwitchExampleState extends State<SwitchExample> {
  bool light0 = true;
  bool light1 = true;

  static const WidgetStateProperty<Icon> thumbIcon =
      WidgetStateProperty<Icon>.fromMap(<WidgetStatesConstraint, Icon>{
        WidgetState.selected: Icon(Icons.check),
        WidgetState.any: Icon(Icons.close),
      });

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: .center,
      children: <Widget>[
        Switch(
          value: light0,
          onChanged: (bool value) {
            setState(() {
              light0 = value;
            });
          },
        ),
        Switch(
          thumbIcon: thumbIcon,
          value: light1,
          onChanged: (bool value) {
            setState(() {
              light1 = value;
            });
          },
        ),
      ],
    );
  }
}

This example shows how to use the ambient CupertinoThemeData to style all widgets which would otherwise use iOS defaults.

To see it in action, copy and run this code snippet on DartPad.

import 'package:cupertino_ui/cupertino_ui.dart';
import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Switch].

void main() => runApp(const SwitchApp());

class SwitchApp extends StatelessWidget {
  const SwitchApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        // Use the ambient CupertinoThemeData to style all widgets which would
        // otherwise use iOS defaults.
        cupertinoOverrideTheme: const CupertinoThemeData(applyThemeToAll: true),
      ),
      home: Scaffold(
        appBar: AppBar(title: const Text('Switch Sample')),
        body: const Center(child: SwitchExample()),
      ),
    );
  }
}

class SwitchExample extends StatefulWidget {
  const SwitchExample({super.key});

  @override
  State<SwitchExample> createState() => _SwitchExampleState();
}

class _SwitchExampleState extends State<SwitchExample> {
  bool light = true;

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: .center,
      children: <Widget>[
        Switch.adaptive(
          value: light,
          onChanged: (bool value) {
            setState(() {
              light = value;
            });
          },
        ),
        Switch.adaptive(
          // Don't use the ambient CupertinoThemeData to style this switch.
          applyCupertinoTheme: false,
          value: light,
          onChanged: (bool value) {
            setState(() {
              light = value;
            });
          },
        ),
      ],
    );
  }
}

See also:

• SwitchListTile, which combines this widget with a ListTile so that you can give the switch a label.
• Checkbox, another widget with similar semantics.
• Radio, for selecting among a set of explicit values.
• Slider, for selecting a value in a range.
• WidgetStateProperty, an interface for objects that "resolve" to different values depending on a widget's material state.
• material.io/design/components/selection-controls.html#switches

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• Switch

Constructors

Switch({Key? key, required bool value, required ValueChanged<bool>? onChanged, @Deprecated('Use activeThumbColor instead. ' 'This feature was deprecated after v3.31.0-2.0.pre.') Color? activeColor, Color? activeThumbColor, Color? activeTrackColor, Color? inactiveThumbColor, Color? inactiveTrackColor, ImageProvider<Object>? activeThumbImage, ImageErrorListener? onActiveThumbImageError, ImageProvider<Object>? inactiveThumbImage, ImageErrorListener? onInactiveThumbImageError, WidgetStateProperty<Color?>? thumbColor, WidgetStateProperty<Color?>? trackColor, WidgetStateProperty<Color?>? trackOutlineColor, WidgetStateProperty<double?>? trackOutlineWidth, WidgetStateProperty<Icon?>? thumbIcon, MaterialTapTargetSize? materialTapTargetSize, DragStartBehavior dragStartBehavior = DragStartBehavior.start, MouseCursor? mouseCursor, Color? focusColor, Color? hoverColor, WidgetStateProperty<Color?>? overlayColor, double? splashRadius, FocusNode? focusNode, ValueChanged<bool>? onFocusChange, bool autofocus = false, EdgeInsetsGeometry? padding})

Creates a Material Design switch.

const

Switch.adaptive({Key? key, required bool value, required ValueChanged<bool>? onChanged, @Deprecated('Use activeThumbColor or activeTrackColor instead. ' 'This feature was deprecated after v3.31.0-2.0.pre.') Color? activeColor, Color? activeThumbColor, Color? activeTrackColor, Color? inactiveThumbColor, Color? inactiveTrackColor, ImageProvider<Object>? activeThumbImage, ImageErrorListener? onActiveThumbImageError, ImageProvider<Object>? inactiveThumbImage, ImageErrorListener? onInactiveThumbImageError, MaterialTapTargetSize? materialTapTargetSize, WidgetStateProperty<Color?>? thumbColor, WidgetStateProperty<Color?>? trackColor, WidgetStateProperty<Color?>? trackOutlineColor, WidgetStateProperty<double?>? trackOutlineWidth, WidgetStateProperty<Icon?>? thumbIcon, DragStartBehavior dragStartBehavior = DragStartBehavior.start, MouseCursor? mouseCursor, Color? focusColor, Color? hoverColor, WidgetStateProperty<Color?>? overlayColor, double? splashRadius, FocusNode? focusNode, ValueChanged<bool>? onFocusChange, bool autofocus = false, EdgeInsetsGeometry? padding, bool? applyCupertinoTheme})

Creates an adaptive Switch based on whether the target platform is iOS or macOS, following Material design's Cross-platform guidelines.

const

Properties

activeColor → Color?

The color to use when this switch is on.

final

activeThumbColor → Color?

The color to use when this switch is on.

final

activeThumbImage → ImageProvider<Object>?

An image to use on the thumb of this switch when the switch is on.

final

activeTrackColor → Color?

The color to use on the track when this switch is on.

final

applyCupertinoTheme → bool?

Whether to apply the ambient CupertinoThemeData.

final

autofocus → bool

True if this widget will be selected as the initial focus when no other node in its scope is currently focused.

final

dragStartBehavior → DragStartBehavior

Determines the way that drag start behavior is handled.

final

focusColor → Color?

The color for the button's Material when it has the input focus.

final

focusNode → FocusNode?

An optional focus node to use as the focus node for this widget.

final

hashCode → int

The hash code for this object.

no setter, inherited

hoverColor → Color?

The color for the button's Material when a pointer is hovering over it.

final

inactiveThumbColor → Color?

The color to use on the thumb when this switch is off.

final

inactiveThumbImage → ImageProvider<Object>?

An image to use on the thumb of this switch when the switch is off.

final

inactiveTrackColor → Color?

The color to use on the track when this switch is off.

final

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

materialTapTargetSize → MaterialTapTargetSize?

Configures the minimum size of the tap target.

final

mouseCursor → MouseCursor?

The cursor for a mouse pointer when it enters or is hovering over the widget.

final

onActiveThumbImageError → ImageErrorListener?

An optional error callback for errors emitted when loading activeThumbImage.

final

onChanged → ValueChanged<bool>?

Called when the user toggles the switch on or off.

final

onFocusChange → ValueChanged<bool>?

Handler called when the focus changes.

final

onInactiveThumbImageError → ImageErrorListener?

An optional error callback for errors emitted when loading inactiveThumbImage.

final

overlayColor → WidgetStateProperty<Color?>?

The color for the switch's Material.

final

padding → EdgeInsetsGeometry?

The amount of space to surround the child inside the bounds of the Switch.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

splashRadius → double?

The splash radius of the circular Material ink response.

final

thumbColor → WidgetStateProperty<Color?>?

The color of this Switch's thumb.

final

thumbIcon → WidgetStateProperty<Icon?>?

The icon to use on the thumb of this switch

final

trackColor → WidgetStateProperty<Color?>?

The color of this Switch's track.

final

trackOutlineColor → WidgetStateProperty<Color?>?

The outline color of this Switch's track.

final

trackOutlineWidth → WidgetStateProperty<double?>?

The outline width of this Switch's track.

final

value → bool

Whether this switch is on or off.

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, int wrapWidth = 65}) → 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