Switch branches/tags
chore/all/remove-event-handlers-from-adapters chore/button/alternates chore/checkbox/no-more-importants chore/image-list-screenshot chore/infra/high-contrast-rtl-screenshots chore/infra/not-old-ios chore/infrastructure/remove-normalize-css chore/license chore/list/list-item chore/package/update-sass-variables-to-default chore/select/update-adapter-value-methods chore/webpack/building-demos debugging-dumb-ios-tests docs/deploy-site docs/icon-button-meta-36 docs/survey-link-readmes-style docs/40 docs/41 drcampbell-fix/select-height experiment/drawer experimental/advorak/karma-cbt-runner experimental/browser-compat experimental/button-no-line-height experimental/card/ripple-surface experimental/drawer/ios-animation experimental/fab-mixins-kgf experimental_feat_extendedfab_issue2043 experimental_feat_extendedfab_transform experimental_feat_switch_colorscheme experimental/feature-targeting experimental/handlebars experimental/ie10-compat experimental/infra/button-flakiness experimental/lynnjepsen/screenshot-test experimental/m2-card-prototype experimental/menues1 experimental/outline-text-field experimental/ripple-cleanup-kgf experimental/ripple-ie-js-focus experimental/ripple-unbounded experimental/sassdoc experimental/screenshot-testing/cbt experimental/shape-ripple-ms experimental_shapes_system_mvp_single_radius experimental_shapes_system_mvp experimental/sliders/arrow-motions experimental/sliders/continuous experimental/sliders/discrete experimental/sliders/eventhandlers experimental/sliders/mixins experimental/sliders/ripple-states experimental/states-kgf experimental/states-nofocusripple-kgf experimental/states/selected experimental/text-field-outlined-flex experimental/textfield-improvements-prototype experimental_textfield_error_state_proposed experimental/theme/demo experimental/theme/disabled experimental/typescript-definitions feat/card/states-ripple-surface feat/chips/elevation-mixin feat/dialog feat_extendedfab_issue2043_roboto_font feat/invalid-input-label feat/list_toggle_tabindex feat/navigation-drawer-dismissible-foundation-update feat/navigation-drawer-modal feat/navigation-drawer-new feat/navigation-drawer-sass-improve feat/navigation-drawer-water feat/navigation-drawer feat/new-switch feat/rail-drawer feat/side-sheet-scss-cleanup feat/side-sheet feat/slider feat/sliders/arrow-motion feat/sliders/disabled feat/sliders/discrete feat/sliders/tick-mark-coloring feat/snackbar--prototype feat/tabs/tab-bar feat/tabs/tab-compute-dimensions feat/tabs/tab-handlers feat/tabs/tab-indicator-content feat/tabs/tab-indicator-in-tab feat/tabs/tab-scroller feat/tabs/tab feat/tabs/tabs-params-matching feat/test/button-assets-2-gcs feat/theme-emphasis fix/button/stroke-lineheight fix/checkbox/css-background-fade fix/chips/select fix/dialog-spec fix/drawer/fixture-js fix/drawer/page-scroll-issue fix/infrastructure/closure-module-declarations fix/list_checkbox_selectedindex fix/menu-surface-z-index fix/menu-surface/move-event-registration fix/menu/selection-group-styles fix/node-version-travisci fix/notched-outline/fix-overflow fix/outlined-shape-radius fix/slider/center fix/text-field/outline-color fix/textarea-center greenkeeper/autoprefixer-9.2.0 greenkeeper/autoprefixer-9.2.1 greenkeeper/autoprefixer-9.3.0 greenkeeper/autoprefixer-9.3.1 greenkeeper/autoprefixer-9.4.0 greenkeeper/autoprefixer-9.4.1 greenkeeper/autoprefixer-9.4.2 greenkeeper/babel-loader-8.0.0 greenkeeper/babel-loader-8.0.1 greenkeeper/babel-loader-8.0.2 greenkeeper/babel-loader-8.0.3 greenkeeper/babel-loader-8.0.4 greenkeeper/colors-1.3.3 greenkeeper/conventional-commits-parser-3.0.1 greenkeeper/css-loader-2.0.1 greenkeeper/dart-sass-1.15.0 greenkeeper/dart-sass-1.15.1 greenkeeper/dart-sass-1.15.2 greenkeeper/detect-port-1.3.0 greenkeeper/fibers-3.1.0 greenkeeper/fibers-3.1.1 greenkeeper/fs-extra-7.0.1 greenkeeper/google-closure-compiler-20181028.0.0 greenkeeper/google-closure-compiler-20181028.0.1 greenkeeper/google-closure-compiler-20181125.0.1 greenkeeper/google-closure-compiler-20181125.1.0 greenkeeper/google-closure-compiler-20181210.0.0 greenkeeper/husky-1.1.2 greenkeeper/husky-1.1.3 greenkeeper/husky-1.1.4 greenkeeper/husky-1.2.0 greenkeeper/husky-1.2.1 greenkeeper/karma-3.1.0 greenkeeper/karma-3.1.1 greenkeeper/karma-3.1.2 greenkeeper/karma-3.1.3 greenkeeper/karma-sauce-launcher-2.0.0 greenkeeper/karma-sauce-launcher-2.0.1 greenkeeper/karma-sauce-launcher-2.0.2 greenkeeper/karma-webpack-3.0.5 greenkeeper/lerna-2.10.1 greenkeeper/lerna-3.0.0 greenkeeper/lerna-3.0.1 greenkeeper/lerna-3.0.2 greenkeeper/lerna-3.0.3 greenkeeper/lerna-3.0.4 greenkeeper/lerna-3.0.5 greenkeeper/lerna-3.0.6 greenkeeper/lerna-3.1.0 greenkeeper/lerna-3.1.1 greenkeeper/lerna-3.1.2 greenkeeper/lerna-3.2.0 greenkeeper/lerna-3.2.1 greenkeeper/lerna-3.3.0 greenkeeper/lerna-3.3.1 greenkeeper/lerna-3.3.2 greenkeeper/lerna-3.4.0 greenkeeper/lerna-3.4.1 greenkeeper/lerna-3.4.2 greenkeeper/lerna-3.4.3 greenkeeper/lerna-3.5.0 greenkeeper/lerna-3.5.1 greenkeeper/lerna-3.6.0 greenkeeper/npm-run-all-4.1.4 greenkeeper/npm-run-all-4.1.5 greenkeeper/@octokit/rest-16.2.0 greenkeeper/recast-0.16.1 greenkeeper/semver-5.6.0 greenkeeper/simple-git-1.98.0 greenkeeper/simple-git-1.99.0 greenkeeper/simple-git-1.100.0 greenkeeper/simple-git-1.101.0 greenkeeper/simple-git-1.102.0 greenkeeper/simple-git-1.103.0 greenkeeper/simple-git-1.104.0 greenkeeper/simple-git-1.105.0 greenkeeper/simple-git-1.106.0 greenkeeper/simple-git-1.107.0 greenkeeper/standard-changelog-2.0.3 greenkeeper/standard-changelog-2.0.4 greenkeeper/standard-changelog-2.0.5 greenkeeper/standard-changelog-2.0.6 greenkeeper/stylelint-9.6.0 greenkeeper/stylelint-9.7.0 greenkeeper/stylelint-9.7.1 greenkeeper/stylelint-9.8.0 greenkeeper/stylelint-9.9.0 greenkeeper/stylelint-scss-3.3.1 greenkeeper/stylelint-scss-3.3.2 greenkeeper/stylelint-scss-3.4.0 greenkeeper/stylelint-scss-3.4.1 greenkeeper/stylelint-selector-bem-pattern-2.0.0 greenkeeper/testdouble-3.8.2 greenkeeper/testdouble-3.9.0 greenkeeper/testdouble-3.9.1 greenkeeper/webpack-4.0.0 greenkeeper/webpack-4.0.1 greenkeeper/webpack-4.1.0 greenkeeper/webpack-4.1.1 greenkeeper/webpack-4.2.0 greenkeeper/webpack-4.3.0 greenkeeper/webpack-4.4.0 greenkeeper/webpack-4.5.0 greenkeeper/webpack-4.6.0 greenkeeper/webpack-4.7.0 greenkeeper/webpack-4.8.2 greenkeeper/webpack-4.8.3 greenkeeper/webpack-4.9.0 greenkeeper/webpack-4.9.1 greenkeeper/webpack-4.9.2 greenkeeper/webpack-4.10.0 greenkeeper/webpack-4.10.1 greenkeeper/webpack-4.10.2 greenkeeper/webpack-4.11.0 greenkeeper/webpack-4.11.1 greenkeeper/webpack-4.12.0 greenkeeper/webpack-4.12.1 greenkeeper/webpack-4.12.2 greenkeeper/webpack-4.13.0 greenkeeper/webpack-4.14.0 greenkeeper/webpack-4.15.0 greenkeeper/webpack-4.15.1 greenkeeper/webpack-4.16.0 greenkeeper/webpack-4.16.1 greenkeeper/webpack-4.16.2 greenkeeper/webpack-4.16.3 greenkeeper/webpack-4.16.4 greenkeeper/webpack-4.16.5 greenkeeper/webpack-4.17.0 greenkeeper/webpack-4.17.1 greenkeeper/webpack-4.17.2 greenkeeper/webpack-4.17.3 greenkeeper/webpack-4.18.0 greenkeeper/webpack-4.18.1 greenkeeper/webpack-4.19.0 greenkeeper/webpack-4.19.1 greenkeeper/webpack-4.20.0 greenkeeper/webpack-4.20.1 greenkeeper/webpack-4.20.2 greenkeeper/webpack-4.21.0 greenkeeper/webpack-4.22.0 greenkeeper/webpack-4.23.0 greenkeeper/webpack-4.23.1 greenkeeper/webpack-4.24.0 greenkeeper/webpack-4.25.0 greenkeeper/webpack-4.25.1 greenkeeper/webpack-4.26.0 greenkeeper/webpack-4.26.1 greenkeeper/webpack-4.27.0 greenkeeper/webpack-4.27.1 greenkeeper/webpack-dev-server-3.0.0 greenkeeper/webpack-dev-server-3.1.0 greenkeeper/webpack-dev-server-3.1.1 greenkeeper/webpack-dev-server-3.1.2 greenkeeper/webpack-dev-server-3.1.3 greenkeeper/webpack-dev-server-3.1.4 greenkeeper/webpack-dev-server-3.1.5 greenkeeper/webpack-dev-server-3.1.6 greenkeeper/webpack-dev-server-3.1.7 greenkeeper/webpack-dev-server-3.1.8 greenkeeper/webpack-dev-server-3.1.9 greenkeeper/webpack-dev-server-3.1.10 latest-release list_custom_event_issue3481 list_custom_event_menu_update_issue3481 list_twolines_baseline_issue3038 maintenance/text-field master mock/crane origin/experimental/sliders patrickrodee-patch-1 patrickrodee-patch-2 refactor/text-field/opacity refactor/theme/color ripple/events ripple/prototype slider/mixins tabzzzzzzzzz test/switch-update textfields/verticalAlignment theme_alpha_variables_issue3066 typography_text_baseline
Nothing to show
Find file History
mathiasschopmans and acdvorak feat(checkbox): Declare all Sass variables as `!default`
All Sass variables are now declared as `!default` so they can be overridden by clients.

Refs #3708
Latest commit de6c833 Dec 14, 2018

README.md

Checkboxes

Checkboxes allow the user to select one or more items from a set.

Design & API Documentation

Installation

npm install @material/checkbox

Basic Usage

We recommend using MDC Checkbox with MDC Form Field for enhancements such as label alignment, label activation of the ripple interaction effect, and RTL-awareness.

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

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

Styles

@import "@material/form-field/mdc-form-field";
@import "@material/checkbox/mdc-checkbox";

JavaScript Instantiation

The checkbox will work without JavaScript, but you can enhance it with a ripple interaction effect by instantiating MDCCheckbox on the mdc-checkbox element. To activate the ripple effect upon interacting with the label, you must also instantiate MDCFormField on the mdc-form-field element and set the MDCCheckbox instance as its input.

import {MDCFormField} from '@material/form-field';
import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
const formField = new MDCFormField(document.querySelector('.mdc-form-field'));
formField.input = checkbox;

See Importing the JS component for more information on how to import JavaScript.

Variants

Disabled

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"
            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>

Style Customization

MDC Checkbox uses MDC 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.

Mixin Description
mdc-checkbox-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-stroke-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-stroke-color, $marked-fill-color, $generate-keyframes)

Stroke and fill color may be customized independently in both the marked and unmarked state.

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.

MDCCheckbox Properties and Methods

Property Name Type Description
checked Boolean Setter/getter for the checkbox's checked state
indeterminate Boolean Setter/getter for the checkbox's indeterminate state
disabled Boolean Setter/getter for the checkbox's disabled state
value String Setter/getter for the checkbox's

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Checkbox for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCCheckboxAdapter

Method Signature Description
addClass(className: string) => void Adds a class to the root element.
removeClass(className: string) => void Removes a class from the root element.
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() => void Force-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() => boolean Returns true if the component is currently attached to the DOM, false otherwise.
isIndeterminate() => boolean Returns true if the component is in the indeterminate state.
isChecked() => boolean Returns true if the component is checked.
hasNativeControl() => boolean Returns true if the input is present in the component.
setNativeControlDisabled(disabled: boolean) => void Sets the input to disabled.

MDCCheckboxFoundation

Method Signature Description
setDisabled(disabled: boolean) => void Updates the disabled property on the underlying input. Does nothing when the underlying input is not present.
handleAnimationEnd() => void animationend event handler that should be applied to the root element.
handleChange() => void change event handler that should be applied to the checkbox element.