third_party/ot-br-posix/repo/third_party/mdl/repo/src/checkbox/README.md

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **checkbox** component is an enhanced version of the standard HTML `<input type="checkbox">` element. A checkbox consists of a small square and, typically, text that clearly communicates a binary condition that will be set or unset when the user clicks or touches it. Checkboxes typically, but not necessarily, appear in groups, and can be selected and deselected individually. The MDL checkbox component allows you to add display and click effects.
   4
   5 Checkboxes are a common feature of most user interfaces, regardless of a site's content or function. Their design and use is therefore an important factor in the overall user experience. See the checkbox component's [Material Design specifications page](https://www.google.com/design/spec/components/selection-controls.html#selection-controls-checkbox) for details.
   6
   7 The enhanced checkbox component has a more vivid visual look than a standard checkbox, and may be initially or programmatically *disabled*.
   8
   9 ### To include an MDL **checkbox** component:
  10
  11 &nbsp;1. Code a `<label>` element and give it a `for` attribute whose value is the unique id of the checkbox it will contain. The `for` attribute is optional when the `<input>` element is contained inside the `<label>` element, but is recommended for clarity.
  12 ```html
  13 <label for="chkbox1">
  14 ...
  15 </label>
  16 ```
  17 &nbsp;2. Inside the label, code an `<input>` element and give it a `type` attribute whose value is `"checkbox"`. Also give it an `id` attribute whose value matches the label's `for` attribute value.
  18 ```html
  19 <label for="chkbox1">
  20   <input type="checkbox" id="chkbox1">
  21 </label>
  22 ```
  23 &nbsp;3. Also inside the label, after the checkbox, code a `<span>` element containing the checkbox's text caption.
  24 ```html
  25 <label for="chkbox1">
  26   <input type="checkbox" id="chkbox1">
  27   <span>Enable AutoSave</span>
  28 </label>
  29 ```
  30 &nbsp;4. Add one or more MDL classes, separated by spaces, to the label, checkbox, and caption using the `class` attribute.
  31 ```html
  32 <label for="chkbox1" class="mdl-checkbox mdl-js-checkbox">
  33   <input type="checkbox" id="chkbox1" class="mdl-checkbox__input">
  34   <span class="mdl-checkbox__label">Enable AutoSave</span>
  35 </label>
  36 ```
  37
  38 The checkbox component is ready for use.
  39
  40 #### Example
  41
  42 A checkbox with a ripple click effect.
  43
  44 ```html
  45 <label for="chkbox1" class="mdl-checkbox mdl-js-checkbox mdl-js-ripple-effect">
  46   <input type="checkbox" id="chkbox1" class="mdl-checkbox__input">
  47   <span class="mdl-checkbox__label">Enable AutoSave</span>
  48 </label>
  49 ```
  50
  51 ## Configuration options
  52
  53 The MDL CSS classes apply various predefined visual and behavioral enhancements to the checkbox. The table below lists the available classes and their effects.
  54
  55 | MDL class | Effect | Remarks |
  56 |-----------|--------|---------|
  57 | `mdl-checkbox` | Defines label as an MDL component | Required on label element|
  58 | `mdl-js-checkbox` | Assigns basic MDL behavior to label | Required on label element |
  59 | `mdl-checkbox__input` | Applies basic MDL behavior to checkbox | Required on input element (checkbox) |
  60 | `mdl-checkbox__label` | Applies basic MDL behavior to caption | Required on span element (caption) |
  61 | `mdl-js-ripple-effect` | Applies *ripple* click effect | Optional; goes on label element, not input element (checkbox) |
  62
  63 >**Note:** Disabled versions of all the available checkbox types are provided, and are invoked with the standard HTML boolean attribute `disabled`. `<input type="checkbox" id="checkbox-5" class="mdl-checkbox__input" disabled>`
  64 >This attribute may be added or removed programmatically via scripting.