diff --git a/docs/components/Switch.md b/docs/components/Switch.md
index a1785d872dc..b2a9316d128 100644
--- a/docs/components/Switch.md
+++ b/docs/components/Switch.md
@@ -31,7 +31,7 @@ Material Components for Android library. For more information, go to the
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
page.
-**Note:** The `SwitchMaterial` widget provides a complete implementation of
+**Note:** The `MaterialSwitch` 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
@@ -56,8 +56,193 @@ 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.
+**Note:** Since version 1.7.0, the new `MaterialSwitch` class will replace the
+obsolete `SwitchMaterial` class. In most cases you should be able to just
+replace all `SwitchMaterial` class reference with `MaterialSwitch` to enjoy the
+default look and feel. Please refer to the following sections if you need to
+customize the new styles.
+
+**Note:** For the old `SwitchMaterial` documentation, please refer to
+[Switch (deprecated)](#switch-deprecated) and
+[Theming switches (deprecated)](#theming-switches-deprecated).
+
### Switches example
+The following example shows a list of five switches.
+
+![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example.png)
+
+In the layout:
+
+```xml
+
+
+
+
+
+```
+
+In code:
+
+```kt
+// To check a switch
+materialSwitch.isChecked = true
+
+// To listen for a switch's checked/unchecked state changes
+materialSwitch.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:
+
+![Switch anatomy diagram](assets/switch/switch_anatomy.png)
+
+1. Thumb
+2. Track
+3. Icon (optional)
+
+### Switch attributes
+
+Element | Attribute | Related method(s) | Default value
+-------------- | ------------------- | --------------------------------- | -------------
+**Min height** | `android:minHeight` | `setMinHeight`
`getMinHeight` | `?attr/minTouchTargetSize`
+
+### Thumb attributes
+
+Element | Attribute | Related method(s) | Default value
+--------- | --------------- | ----------------------------------------- | -------------
+**Thumb** | `android:thumb` | `setThumbDrawable`
`getThumbDrawable` | `@drawable/mtrl_switch_thumb`
+**Color** | `app:thumbTint` | `setThumbTintList`
`getThumbTintList` | `?attr/colorOutline` (unchecked)
`?attr/colorOnPrimary` (checked)
+
+### Icon attributes
+
+Element | Attribute | Related method(s) | Default value
+--------- | ------------------- | ------------------------------------------------- | -------------
+**Icon** | `app:thumbIcon` | `setThumbIconDrawable`
`getThumbIconDrawable` | `null`
+**Color** | `app:thumbIconTint` | `setThumbIconTintList`
`getThumbIconTintList` | `?attr/colorSurfaceVariant` (unchecked)
`?attr/colorOnPrimaryContainer` (checked)
+
+You can add an optional icon to enhance the on/off indication of your custom
+switch by assiging `app:thumbIcon`. This icon will be centered and displayed on
+top of the thumb drawable.
+
+### Track attributes
+
+Element | Attribute | Related method(s) | Default value
+-------------------- | ------------------------- | ------------------------------------------------------------- | -------------
+**Track** | `app:track` | `setTrackDrawable`
`getTrackDrawable` | `@drawable/mtrl_switch_track`
+**Color** | `app:trackTint` | `setTrackTintList`
`getTrackTintList` | `?attr/colorSurfaceVariant` (unchecked)
`?attr/colorPrimary` (checked)
+**Decoration** | `app:trackDecoration` | `setTrackDecorationDrawable`
`getTrackDecorationDrawable` | `@drawable/mtrl_switch_track_decoration`
(Shows an outline of the track.)
+**Decoration color** | `app:trackDecorationTint` | `setTrackDecorationTintList`
`getTrackDecorationTintList` | `?attr/colorOutline` (unchecked)
`@android:color/transparent` (checked)
+
+### Text label attributes
+
+Element | Attribute | Related method(s) | Default value
+-------------- | ------------------------ | ----------------------------------------- | -------------
+**Text label** | `android:text` | `setText`
`getText` | `null`
+**Color** | `android:textColor` | `setTextColor`
`getTextColors` | `?android:attr/textColorPrimaryDisableOnly`
+**Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceBodyMedium`
+**Padding** | `app:switchPadding` | `setSwitchPadding`
`getSwitchPadding` | `16dp`
+
+### Switch states
+
+Switches can be on or off. Switches have enabled, hover, focused, and pressed
+states.
+
+![Switch states in an array. Columns are enabled, disabled, hover, focused,
+pressed. Rows are on or off](assets/switch/switch_states.png)
+
+### Styles
+
+Element | Style
+----------------- | ------------------------------------------------
+**Default style** | `Widget.Material3.CompoundButton.MaterialSwitch`
+
+Default style theme attribute: `?attr/materialSwitchStyle`
+
+See the full list of
+[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/materialswitch/res/values/styles.xml)
+and
+[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/materialswitch/res/values/attrs.xml).
+
+## Theming switches
+
+Switches support
+[Material Theming](https://material.io/components/selection-controls#theming),
+which can customize color and typography.
+
+### Switch theming example
+
+The following example shows a list of switches with Material Theming.
+
+!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming.png)
+
+#### Implementing switch theming
+
+Use theme attributes in `res/values/styles.xml`, which applies to all switches
+and affects other components:
+
+```xml
+
+
+```
+
+Use default style theme attributes, styles and theme overlays, which apply to
+all switches but do not affect other components:
+
+```xml
+
+
+
+
+
+```
+
+Use the styles in the layout, which affects only this switch:
+
+```xml
+
+```
+
+## Switch (deprecated)
+
+### Switches example (deprecated)
+
API and source code:
* `SwitchMaterial`
@@ -66,7 +251,7 @@ API and source code:
The following example shows a list of five switches.
-![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example.png)
+![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example_deprecated.png)
In the layout:
@@ -99,25 +284,25 @@ In code:
```kt
// To check a switch
-switchMaterial.isChecked = true
+switchmaterial.isChecked = true
// To listen for a switch's checked/unchecked state changes
-switchMaterial.setOnCheckedChangeListener { buttonView, isChecked
+switchmaterial.setOnCheckedChangeListener { buttonView, isChecked
// Responds to switch being checked/unchecked
}
```
-## Anatomy and key properties
+## Anatomy and key properties (deprecated)
The following is an anatomy diagram that shows a switch thumb and a switch
track:
-![Switch anatomy diagram](assets/switch/switch_anatomy.png)
+![Switch anatomy diagram](assets/switch/switch_anatomy_deprecated.png)
1. Thumb
2. Track
-### Switch attributes
+### Switch attributes (deprecated)
Element | Attribute | Related method(s) | Default value
-------------------------- | ------------------------------------------ | ---------------------------------------------------------- | -------------
@@ -137,7 +322,7 @@ with a custom drawable that should not be tinted, set
/>
```
-### Thumb attributes
+### Thumb attributes (deprecated)
Element | Attribute | Related method(s) | Default value
------------- | --------------- | ----------------------------------------- | -------------
@@ -145,14 +330,14 @@ Element | Attribute | Related method(s) | De
**Color** | `app:thumbTint` | `setThumbTintList`
`getThumbTintList` | `?attr/colorOnSurface` (unchecked)
`?attr/colorPrimary` (checked)
**Elevation** | N/A | N/A | `4dp`
-### Track attributes
+### Track attributes (deprecated)
Element | Attribute | Related method(s) | Default value
--------- | --------------- | ----------------------------------------- | -------------
**Track** | `app:track` | `setTrackDrawable`
`getTrackDrawable` | inherits from `SwitchCompat`
**Color** | `app:trackTint` | `setTrackTintList`
`getTrackTintList` | `?attr/colorOutline` (unchecked)
`?attr/colorPrimaryContainer` (checked)
-### Text label attributes
+### Text label attributes (deprecated)
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | ---------------------------------- | -------------
@@ -160,7 +345,7 @@ Element | Attribute | Related method(s) |
**Color** | `android:textColor` | `setTextColor`
`getTextColors` | `?android:attr/textColorPrimaryDisableOnly`
**Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceBodyMedium`
-### Switch states
+### Switch states (deprecated)
Switches can be on or off. Switches have enabled, hover, focused, and pressed
states.
@@ -171,9 +356,9 @@ interaction may obstruct the element completely.
For desktop, the radial reaction isn't needed.
![Switch states in an array. Columns are enabled, disabled, hover, focused,
-pressed. Rows are on or off](assets/switch/switch_states.png)
+pressed. Rows are on or off](assets/switch/switch_states_deprecated.png)
-### Styles
+### Styles (deprecated)
Element | Style
----------------- | ----------------------------------------
@@ -186,13 +371,13 @@ See the full list of
and
[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/switchmaterial/res/values/attrs.xml).
-## Theming switches
+## Theming switches (deprecated)
Switches support
[Material Theming](https://material.io/components/selection-controls#theming),
which can customize color and typography.
-### Switch theming example
+### Switch theming example (deprecated)
API and source code:
@@ -202,9 +387,9 @@ API and source code:
The following example shows a list of switches with Material Theming.
-!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming.png)
+!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming_deprecated.png)
-#### Implementing switch theming
+#### Implementing switch theming (deprecated)
Use theme attributes in `res/values/styles.xml`, which applies to all switches
and affects other components:
diff --git a/docs/components/assets/switch/switch_anatomy.png b/docs/components/assets/switch/switch_anatomy.png
index 0605b251a71..39cc16ae2c2 100644
Binary files a/docs/components/assets/switch/switch_anatomy.png and b/docs/components/assets/switch/switch_anatomy.png differ
diff --git a/docs/components/assets/switch/switch_anatomy_deprecated.png b/docs/components/assets/switch/switch_anatomy_deprecated.png
new file mode 100644
index 00000000000..0605b251a71
Binary files /dev/null and b/docs/components/assets/switch/switch_anatomy_deprecated.png differ
diff --git a/docs/components/assets/switch/switch_example.png b/docs/components/assets/switch/switch_example.png
index 6e696efa950..69d2252b198 100644
Binary files a/docs/components/assets/switch/switch_example.png and b/docs/components/assets/switch/switch_example.png differ
diff --git a/docs/components/assets/switch/switch_example_deprecated.png b/docs/components/assets/switch/switch_example_deprecated.png
new file mode 100644
index 00000000000..6e696efa950
Binary files /dev/null and b/docs/components/assets/switch/switch_example_deprecated.png differ
diff --git a/docs/components/assets/switch/switch_hero.png b/docs/components/assets/switch/switch_hero.png
index 018a4572aed..ab95ffc123b 100644
Binary files a/docs/components/assets/switch/switch_hero.png and b/docs/components/assets/switch/switch_hero.png differ
diff --git a/docs/components/assets/switch/switch_hero_deprecated.png b/docs/components/assets/switch/switch_hero_deprecated.png
new file mode 100644
index 00000000000..018a4572aed
Binary files /dev/null and b/docs/components/assets/switch/switch_hero_deprecated.png differ
diff --git a/docs/components/assets/switch/switch_states.png b/docs/components/assets/switch/switch_states.png
index b3166533891..94c3d4b7fc1 100644
Binary files a/docs/components/assets/switch/switch_states.png and b/docs/components/assets/switch/switch_states.png differ
diff --git a/docs/components/assets/switch/switch_states_deprecated.png b/docs/components/assets/switch/switch_states_deprecated.png
new file mode 100644
index 00000000000..b3166533891
Binary files /dev/null and b/docs/components/assets/switch/switch_states_deprecated.png differ
diff --git a/docs/components/assets/switch/switch_theming.png b/docs/components/assets/switch/switch_theming.png
index 83c72766317..a15b4f5631e 100644
Binary files a/docs/components/assets/switch/switch_theming.png and b/docs/components/assets/switch/switch_theming.png differ
diff --git a/docs/components/assets/switch/switch_theming_deprecated.png b/docs/components/assets/switch/switch_theming_deprecated.png
new file mode 100644
index 00000000000..83c72766317
Binary files /dev/null and b/docs/components/assets/switch/switch_theming_deprecated.png differ