MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Styles
Frameworks
Components
Avatar Badge BottomAppBar Button ButtonIcon Card Checkbox Chip CircularProgress Collapse Dialog Divider Dropdown Fab Icon Layout LinearProgress List Menu NavigationBar NavigationDrawer NavigationRail Radio RangeSlider Select SegmentedButton Slider Snackbar Switch Tabs TextField Tooltip TopAppBar
Functions
Libraries

Switch

The Switch component is utilized to toggle the state of a single setting between on and off.

Usage

Import the component:

import 'mdui/components/switch.js';

Import the TypeScript type:

import type { Switch } from 'mdui/components/switch.js';

Example:

<mdui-switch></mdui-switch>

Examples

Checked State

The checked attribute indicates whether the switch is on or off. To set the switch to the on state by default, add the checked attribute.

Disabled State

The disabled attribute can be used to disable the switch.

Icons

The unchecked-icon and checked-icon attributes can be used to set the Material Icons for the unchecked and checked states, respectively. Alternatively, the unchecked-icon and checked-icon slots can be used to set the icons for the unchecked and checked states.

API

Properties

AttributePropertyReflectTypeDefault
disableddisabledbooleanfalse

Disables the switch.

checkedcheckedbooleanfalse

Sets the switch to the checked state.

defaultCheckedbooleanfalse

The default checked state. The switch resets to this state when the form is reset. This can only be set via a JavaScript property.

unchecked-iconuncheckedIconstring-

The Material Icons name for the unchecked state. Alternatively, use slot="unchecked-icon".

checked-iconcheckedIconstring-

The Material Icons name for the checked state. Alternatively, use slot="checked-icon". Defaults to the check icon; an empty string removes the default icon.

requiredrequiredbooleanfalse

The switch must be checked when submitting the form.

formformstring-

Associates the switch with a <form> element. The value should be the id of a <form> in the same document. If not set, the switch is associated with its parent <form>, if any.

This attribute allows switch elements to be associated with <form>s anywhere in the document, not just inside a <form>.

namenamestring''

The name of the switch, which is submitted with form data.

valuevaluestring'on'

The value of the switch, which is submitted with form data.

validityValidityState-

A ValidityState object that represents the element's validity states.

validationMessagestring-

The element's validation message. This is empty if the element meets its constraints.

autofocusautofocusbooleanfalse

Determines if the element should be focused when the page loads.

tabindextabIndexnumber-

Specifies the order in which the element receives focus when navigating with the Tab key.

Methods

NameParametersReturns
checkValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.

reportValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.

setCustomValidity
  • message: string
void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.

click
void

Simulates a mouse click on the element.

focus
  • options: FocusOptions (Optional)
void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.

blur
void

Removes focus from the element.

Events

Name
focus

Emitted when the switch gains focus.

blur

Emitted when the switch loses focus.

change

Emitted when the checked state changes.

input

Emitted when the checked state changes.

invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.

Slots

Name
unchecked-icon

Element for the unchecked state.

checked-icon

Element for the checked state.

CSS Parts

Name
track

Track.

thumb

Icon container.

unchecked-icon

Icon for the unchecked state.

checked-icon

Icon for the checked state.

CSS Custom Properties

Name
--shape-corner

The corner size of the track. You can use a specific pixel value, but it's recommended to reference design tokens.

--shape-corner-thumb

The corner size of the icon container. You can use a specific pixel value, but it's recommended to reference design tokens.

On this page