14.0.0 • Published 4 months ago

@material/checkbox v14.0.0

Weekly downloads
51,101
License
MIT
Repository
github
Last release
4 months ago

Checkboxes

The MDC Checkbox component is a spec-aligned checkbox component adhering to the Material Design checkbox requirements. It works without JavaScript with basic functionality for all states. If you use the JavaScript object for a checkbox, it will add more intricate animation effects when switching between states.

Design & API Documentation

Installation

npm install @material/checkbox

Usage

Standalone Checkbox

<div class="mdc-checkbox">
  <input type="checkbox"
         class="mdc-checkbox__native-control"/>
  <div class="mdc-checkbox__background">
    <svg class="mdc-checkbox__checkmark"
         viewBox="0 0 24 24">
      <path class="mdc-checkbox__checkmark-path"
            fill="none"
            stroke="white"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
    <div class="mdc-checkbox__mixedmark"></div>
  </div>
</div>

The checkbox component is driven by an underlying native checkbox element. This element is sized and positioned the same way as the checkbox component itself, allowing for proper behavior of assistive devices.

Additionally, the checkbox can be used in conjunction with mdc-form-field to easily position checkboxes and their labels.

<div class="mdc-form-field">
  <div class="mdc-checkbox">
    <input type="checkbox"
           id="my-checkbox"
           class="mdc-checkbox__native-control"/>
    <div class="mdc-checkbox__background">
      <svg class="mdc-checkbox__checkmark"
           viewBox="0 0 24 24">
        <path class="mdc-checkbox__checkmark-path"
              fill="none"
              stroke="white"
              d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
      </svg>
      <div class="mdc-checkbox__mixedmark"></div>
    </div>
  </div>

  <label for="my-checkbox">My Checkbox Label</label>
</div>

Note: If you are using IE, you need to include a closing </path> tag if you wish to avoid console warnings.

Disabled Checkboxes

Note that mdc-checkbox--disabled is necessary on the root element of CSS-only checkboxes to prevent hover states from activating. Checkboxes that use the JavaScript component do not need this class; a disabled attribute on the <input> element is sufficient.

<div class="mdc-checkbox mdc-checkbox--disabled">
  <input type="checkbox"
         id="basic-disabled-checkbox"
         class="mdc-checkbox__native-control"
         disabled />
  <div class="mdc-checkbox__background">
    <svg class="mdc-checkbox__checkmark"
         viewBox="0 0 24 24">
      <path class="mdc-checkbox__checkmark-path"
            fill="none"
            stroke="white"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
    <div class="mdc-checkbox__mixedmark"></div>
  </div>
</div>
<label for="basic-disabled-checkbox" id="basic-disabled-checkbox-label">This is my disabled checkbox</label>

Using the JS Component

MDC Checkbox ships with a Component / Foundation combo which progressively enhances the checkbox state transitions to achieve full parity with the Material Design motion for switching checkbox states.

Including in code

ES2015
import {MDCCheckbox, MDCCheckboxFoundation} from '@material/checkbox';
CommonJS
const mdcCheckbox = require('mdc-checkbox');
const MDCCheckbox = mdcCheckbox.MDCCheckbox;
const MDCCheckboxFoundation = mdcCheckbox.MDCCheckboxFoundation;
AMD
require(['path/to/mdc-checkbox'], mdcCheckbox => {
  const MDCCheckbox = mdcCheckbox.MDCCheckbox;
  const MDCCheckboxFoundation = mdcCheckbox.MDCCheckboxFoundation;
});
Global
const MDCCheckbox = mdc.checkbox.MDCCheckbox;
const MDCCheckboxFoundation = mdc.checkbox.MDCCheckboxFoundation;

Automatic Instantiation

If you do not care about retaining the component instance for the checkbox, simply call attachTo() and pass it a DOM element.

mdc.checkbox.MDCCheckbox.attachTo(document.querySelector('.mdc-checkbox'));

Manual Instantiation

Checkboxes can easily be initialized using their default constructors as well, similar to attachTo.

import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));

MDCCheckbox API

The MDCCheckbox API provides accessor properties similar to those found on a native checkbox element.

MDCCheckbox.checked

Boolean. Returns whether or not the checkbox is checked. Setting this property will update the underlying checkbox element.

MDCCheckbox.indeterminate

Boolean. Returns whether or not the checkbox is indeterminate. Setting this property will update the underlying checkbox element.

MDCCheckbox.disabled

Boolean. Returns whether or not the checkbox is disabled. Setting this property will update the underlying checkbox element.

MDCCheckbox.value

String. Returns the checkbox's value. Setting this property will update the underlying checkbox element.

Using the Foundation Class

MDC Checkbox ships with an MDCCheckboxFoundation class that external frameworks and libraries can use to integrate the component. As with all foundation classes, an adapter object must be provided. The adapter for checkboxes must provide the following functions, with correct signatures:

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
registerAnimationEndHandler(handler: EventListener) => voidRegisters an event handler to be called when an animationend event is triggered on the root element. Note that you must account for vendor prefixes in order for this to work correctly.
deregisterAnimationEndHandler(handler: EventListener) => voidDeregisters an event handler from an animationend event listener. This will only be called with handlers that have previously been passed to registerAnimationEndHandler calls.
registerChangeHandler(handler: EventListener) => voidRegisters an event handler to be called when a change event is triggered on the native control (not the root element).
deregisterChangeHandler(handler: EventListener) => voidDeregisters an event handler that was previously passed to registerChangeHandler.
getNativeControl() => HTMLInputElement?Returns the native checkbox control, if available. Note that if this control is not available, the methods that rely on it will exit gracefully.
forceLayout() => voidForce-trigger a layout on the root element. This is needed to restart animations correctly. If you find that you do not need to do this, you can simply make it a no-op.
isAttachedToDOM() => booleanReturns true if the component is currently attached to the DOM, false otherwise.

MDCCheckboxFoundation API

MDCCheckboxFoundation.isChecked() => boolean

Returns whether or not the underlying input is checked. Returns false when no input is available.

MDCCheckboxFoundation.setChecked(checked: boolean)

Updates the checked property on the underlying input. Does nothing when the underlying input is not present.

MDCCheckboxFoundation.isIndeterminate() => boolean

Returns whether or not the underlying input is indeterminate. Returns false when no input is available.

MDCCheckboxFoundation.setIndeterminate(indeterminate: boolean)

Updates the indeterminate property on the underlying input. Does nothing when the underlying input is not present.

MDCCheckboxFoundation.isDisabled() => boolean

Returns whether or not the underlying input is disabled. Returns false when no input is available.

MDCCheckboxFoundation.setDisabled(disabled: boolean)

Updates the disabled property on the underlying input. Does nothing when the underlying input is not present.

MDCCheckboxFoundation.getValue() => string

Returns the value of adapter.getNativeControl().value. Returns null if getNativeControl() does not return an object.

MDCCheckboxFoundation.setValue(value: string) => void

Sets the value of adapter.getNativeControl().value. Does nothing if getNativeControl() does not return an object.

Theming

MDC Checkboxes use the theme's secondary color by default for "marked" states (i.e., checked or indeterminate).

Sass Mixins

The following mixins apply only to enabled checkboxes. It is not currently possible to customize the color of a disabled checkbox.

MixinDescription
mdc-checkbox-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-fill-color, $generate-keyframes)Generates CSS classes to set and animate the stroke color and/or container fill color of a checkbox
mdc-checkbox-ink-color($color)Sets the ink color of the checked and indeterminate icons
mdc-checkbox-focus-indicator-color($color)Sets the color of the focus indicator

The ripple effect for the Checkbox component is styled using MDC Ripple mixins.

mdc-checkbox-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-fill-color, $generate-keyframes)

Generates CSS classes to set the container stroke color and/or fill color of a checkbox in its marked and unmarked states. In the unmarked state, stroke and fill color may be customized independently; in the marked state, only the fill color may be customized, and the stroke will automatically match the fill color.

All parameters are optional, and if left unspecified will use their default values.

If you plan to use CSS-only checkboxes, set $generate-keyframes to false to prevent the mixin from generating @keyframes and CSS classes used by the JavaScript component.

Caveat: Edge and CSS Variables

In browsers that fully support CSS variables, MDC Checkbox references CSS variables wherever theme properties are used. However, due to Edge's buggy CSS variable support, the background-color for .mdc-checkbox__background::before will not honor CSS variables in Edge. This means you will need to override this style manually for Edge if you alter the CSS variable for the primary color.

@vuemdc/checkbox@material/data-table@material/chipsmdwrapper@beezydev/checkboxtest-web-componentstest-web-componetsmaterial-components-web@everything-registry/sub-chunk-584@arterial/checkbox@authentic/mwc-checkbox@aurelia2-mdc-web/checkbox@aurelia-mdc-web/checkboxcomponents-library-v1@defense-unicorns/unicorn-ui@detachhead/smui-checkboxcore-react-components@bitchin/react-material-web@betazuul/checkbox@bringhub/fabric.jspug-material-designpreact-material-componentspreact-material-components-mgrreact-mdcreact-boardroomreact-material-web-componentszarinpal-story-bookvue-material-design-componentstransposed-gridvegatrosnabbdom-material-componentssvmdsolid-material-componentstest-chipstest-rsmdc@codeadraas/vue3-materialclosure-react-checkbox@ied/dashboard@ied/image-posting.web@dolphin-kiss/material-wc-checkbox@angular/material@angular/material-experimental@emuanalytics/flow-rdf@infinitebrahmanuniverse/nolb-_mate@inovex.de/elements@finastra/checkbox@gmvdev/materials@labstack/data-table@listo-paye/sdk-ui@mhamrah/svelte-material-ui@mdc-react/checkbox@mdc-stencil/checkbox@mcwv/checkbox@mcwv/data-table@material/react-checkbox@morioh/material@mirana/materialize@lucasecdb/rmdc@materialr/checkbox@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@material-react-web/checkbox@o-rango/orango-material-design@preact-material-components/checkbox@onecomponent/checkbox@openremote/or-input@pmwcs/checkboxhyperapp-mdc@react-material/checkbox@react-mdc/checkboximage-posting.web@plonquo/ember-material-components@react.native.material/checkbox@react.material/checkbox@rmwc/checkbox@robertkern/vue-materialmyg-checkbox@xolvio/plate-ui-commentseasyfyv3-presentationdepsmcr-checkboxmdc-react-gumball@xdam/ember-partials@pitaya-components/checkbox@pitaya-components/list@smui/checkboxmaple-material-vue@types/material__checkboxember-material-componentsember-cli-mdc-checkboxfrt-mth-webcomponents@tylertech/forgematerial-imbamaterial-react-jsmaterial-toolboxatajo-web-componentsatajo-web-componetsgesdisc-componentsaurelia-material-ui
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.0

5 years ago

2.1.1

5 years ago

2.1.0

5 years ago

2.0.0

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.0

5 years ago

0.42.0

5 years ago

0.41.0

5 years ago

0.40.1

5 years ago

0.40.0

6 years ago

0.39.3

6 years ago

0.39.2

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.38.1

6 years ago

0.38.0

6 years ago

0.37.1

6 years ago

0.37.0

6 years ago

0.36.1

6 years ago

0.36.0

6 years ago

0.36.0-0

6 years ago

0.35.0

6 years ago

0.34.1

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.32.0

6 years ago

0.31.0

6 years ago

0.30.0

6 years ago

0.29.0

6 years ago

0.28.0

6 years ago

0.27.0

6 years ago

0.26.0

6 years ago

0.25.0

6 years ago

0.24.0

6 years ago

0.23.0

6 years ago

0.4.8

6 years ago

0.4.7

7 years ago

0.4.6

7 years ago

0.4.5

7 years ago

0.4.4

7 years ago

0.4.3

7 years ago

0.4.2

7 years ago

0.4.1

7 years ago

0.4.0

7 years ago

0.3.7

7 years ago

0.3.6

7 years ago

0.3.5

7 years ago

0.3.4

7 years ago

0.3.3

7 years ago

0.3.2

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.3

7 years ago

0.2.2

7 years ago

0.2.1

7 years ago

0.2.0

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago