Switch.md

Selection controls: switches

Selection controls allow the user to select options.

Switches toggle the state of a single setting on or off. They are the preferred way to adjust settings on mobile.

Contents

• Using switches
• Switch
• Theming switches

Using switches

Before you can use Material switches, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Note: The SwitchMaterial widget provides a complete implementation of Material Design's switch component. It extends from the support library's SwitchCompat widget, but not from the framework Switch widget. As such, it does not auto-inflate, unlike other selection controls, and must be explicitly specified in layouts.

Use switches to:

• Toggle a single item on or off, on mobile and tablet
• Immediately activate or deactivate something

Making switches accessible

Switches support content labeling for accessibility and are readable by most screen readers, such as TalkBack. Text rendered in switches is automatically provided to accessibility services. Additional content labels are usually unnecessary.

Switch

A Switch represents a button with two states, on and off. Switches are most often used on mobile devices to enable and disable options in an options menu. A switch consists of a track and thumb; the thumb moves along the track to indicate its current state.

Switches example

API and source code:

• SwitchMaterial
  • Class definition
  • Class source

The following example shows a list of five switches.

In the layout:

<com.google.android.material.switchmaterial.SwitchMaterial
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:checked="true"
    android:text="@string/label_1"/>
<com.google.android.material.switchmaterial.SwitchMaterial
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:text="@string/label_2"/>
<com.google.android.material.switchmaterial.SwitchMaterial
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:text="@string/label_3"/>
<com.google.android.material.switchmaterial.SwitchMaterial
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:text="@string/label_4"/>
<com.google.android.material.switchmaterial.SwitchMaterial
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:enabled="false"
    android:text="@string/label_5"/>

In code:

// To check a switch
switchMaterial.isChecked = true

// To listen for a switch's checked/unchecked state changes
switchMaterial.setOnCheckedChangeListener { buttonView, isChecked
    // Responds to switch being checked/unchecked
}

Anatomy and key properties

The following is an anatomy diagram that shows a switch thumb and a switch track:

1. Thumb
2. Track

Switch attributes

	Attribute	Related method(s)	Default value
To use material colors	app:useMaterialThemeColors	setUseMaterialThemeColors isUseMaterialThemeColors	true (ignored if specific tint attrs are set)
Min size	android:minWidth android:minHeight	(set/get)MinWidth (set/get)MinHeight	?attr/minTouchTargetSize

The color of the switch defaults to using ?attr/colorSurface, ?attr/colorOnSurface, and ?attr/colorSecondary defined in your app theme. If you want to override this behavior, as you might with a custom drawable that should not be tinted, set app:useMaterialThemeColors to false:

<com.google.android.material.switchmaterial.SwitchMaterial
        ...
    app:useMaterialThemeColors="false"
    />

Thumb attributes

	Attribute	Related method(s)	Default value
Thumb	android:thumb	setThumbDrawable getThumbDrawable	inherits from SwitchCompat
Color	app:thumbTint	setThumbTintList getThumbTintList	?attr/colorSurface (unchecked) ?attr/colorSecondary (checked)
Elevation	N/A	N/A	4dp

Track attributes

	Attribute	Related method(s)	Default value
Track	app:track	setTrackDrawable getTrackDrawable	inherits from SwitchCompat
Color	app:trackTint	setTrackTintList getTrackTintList	?attr/colorOnSurface (unchecked) ?attr/colorSecondary (checked)

Text label attributes

	Attribute	Related method(s)	Default value
Text label	android:text	setText getText	null
Color	android:textColor	setTextColor getTextColors	inherits from SwitchCompat
Typography	android:textAppearance	setTextAppearance	inherits from SwitchCompat

Switch states

Switches can be on or off. Switches have enabled, hover, focused, and pressed states.

Display the outer radial reaction only on form factors that use touch, where interaction may obstruct the element completely.

For desktop, the radial reaction isn't needed.

Styles

	Style
Default style	Widget.MaterialComponents.CompoundButton.Switch

Default style theme attribute: ?attr/switchStyle

See the full list of styles and attrs.

Theming switches

Switches support Material Theming and can be customized in terms of color and typography.

Switch theming example

API and source code:

• SwitchMaterial
  • Class definition
  • Class source

The following example shows a list of switches with Material Theming.

Implementing switch theming

Using theme attributes in res/values/styles.xml (themes all switches and affects other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="colorSecondary">@color/shrine_pink_100</item>
</style>

or using default style theme attributes, styles and theme overlays (themes all switches but does not affect other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="switchStyle">@style/Widget.App.Switch</item>
</style>

<style name="Widget.App.Switch" parent="Widget.MaterialComponents.CompoundButton.Switch">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Switch</item>
</style>

<style name="ThemeOverlay.App.Switch" parent="">
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="colorSecondary">@color/shrine_pink_100</item>
</style>

or using the styles in the layout (affects only this switch):

<com.google.android.material.switchmaterial.SwitchMaterial
        ...
    style="@style/Widget.App.Switch"
    />