Checkbox

Checkboxes allow users to select one or more options from a set. Each checkbox can toggle between checked and unchecked states.

Usage

Import the component:

import 'mdui/components/checkbox.js';

Import the TypeScript type:

import type { Checkbox } from 'mdui/components/checkbox.js';

Example:

Checkbox
<mdui-checkbox>Checkbox</mdui-checkbox>

Examples

Checked State

The checked property is true when the checkbox is checked. Add the checked attribute to set the checkbox to the checked state by default.

Disabled State

Use the disabled attribute to disable the checkbox.

Indeterminate State

The indeterminate attribute indicates an indeterminate state for the checkbox.

Icons

Use the unchecked-icon, checked-icon, and indeterminate-icon attributes to set Material Icons for the checkbox in unchecked, checked, and indeterminate states, respectively. Alternatively, use the corresponding slots for setting icons.

API

Properties

AttributePropertyReflectTypeDefault
disableddisabledbooleanfalse

Dsiables the checkbox.

checkedcheckedbooleanfalse

Sets the checkbox to the checked state.

defaultCheckedbooleanfalse

Sets the default checked state. Resets to this state when the form is reset. Can only be set via JavaScript property.

indeterminateindeterminatebooleanfalse

Sets the checkbox to an indeterminate state.

requiredrequiredbooleanfalse

Requires the checkbox to be checked for form submission.

formformstring-

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

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

namenamestring''

Sets the checkbox's name, which is submitted with form data.

valuevaluestring'on'

Sets the checkbox's value, which is submitted with form data.

unchecked-iconuncheckedIconstring-

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

checked-iconcheckedIconstring-

Sets the Material Icons name for the checked state. Alternatively, use slot="checked-icon".

indeterminate-iconindeterminateIconstring-

Sets the Material Icons name for the indeterminate state. Alternatively, use slot="indeterminate-icon".

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 checkbox gains focus.

blur

Emitted when the checkbox 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
(default)

Text.

unchecked-icon

Icon for the unchecked state.

checked-icon

Icon for the checked state.

indeterminate-icon

Icon for the indeterminate state.

CSS Parts

Name
control

Container for the left icon.

unchecked-icon

Icon for the unchecked state.

checked-icon

Icon for the checked state.

indeterminate-icon

Icon for the indeterminate state.

label

Text.

MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons