|
| 1 | +# md-checkbox |
| 2 | + |
| 3 | +`md-checkbox` is a Material Design selection control that allows users to make a binary choice for |
| 4 | +a predetermined conditioned. It is modeled after the browser's native checkbox element, and behaves |
| 5 | +in the same way. Similar to the native checkbox element, it supports an indeterminate state for |
| 6 | +"mixed" checkboxes. |
| 7 | + |
| 8 | +A demo of the checkbox can be found at https://plnkr.co/edit/P7qce8lN9n2flS6kBhDy?p=preview. |
| 9 | + |
| 10 | +## Usage |
| 11 | + |
| 12 | +### Basic Usage |
| 13 | + |
| 14 | +`md-checkbox` can be used anywhere a normal checkbox would be used, and in the same way. |
| 15 | + |
| 16 | +```html |
| 17 | +<ul> |
| 18 | + <li *ngFor="#todo of todos"> |
| 19 | + <md-checkbox [checked]="todo.completed" |
| 20 | + (change)="todo.completed = $event"> |
| 21 | + {{todo.name}} |
| 22 | + </md-checkbox> |
| 23 | + </li> |
| 24 | +</ul> |
| 25 | +``` |
| 26 | + |
| 27 | +### Usage within Forms |
| 28 | + |
| 29 | +In addition to supporting native checkbox functionality, `md-checkbox` also supports `[(ngModel)]` |
| 30 | +and `ngControl` for use within forms. |
| 31 | + |
| 32 | +```html |
| 33 | +<form (submit)="saveUser()"> |
| 34 | + <!-- Form fields... --> |
| 35 | + <div> |
| 36 | + <md-checkbox [(ngModel)]="user.agreesToTOS"> |
| 37 | + I have read and agree to the terms of service. |
| 38 | + </md-checkbox> |
| 39 | + </div> |
| 40 | + <button type="submit" [disabled]="!user.agreesToTOS">Sign Up</button> |
| 41 | +</form> |
| 42 | +``` |
| 43 | + |
| 44 | +### Indeterminate Checkboxes |
| 45 | + |
| 46 | +Indeterminate checkboxes are useful when a checkbox needs to be in a "mixed" state |
| 47 | + |
| 48 | +```html |
| 49 | +<md-checkbox [checked]="false" |
| 50 | + [indeterminate]="isIndeterminate" |
| 51 | + (change)="isIndeterminate = false"> |
| 52 | + Click the Button Below to Make Me Indeterminate. |
| 53 | +</md-checkbox> |
| 54 | +<button type="button" (click)="isIndeterminate = true"> |
| 55 | + Make Indeterminate |
| 56 | +</button> |
| 57 | +``` |
| 58 | + |
| 59 | +### Alignment |
| 60 | + |
| 61 | +Note that checkboxes can be aligned to come at the "start" or the "end" of its corresponding label. |
| 62 | + |
| 63 | +```html |
| 64 | +<md-checkbox [checked]="true" align="end"> |
| 65 | + I come after my label. |
| 66 | +</md-checkbox> |
| 67 | +``` |
| 68 | + |
| 69 | +Note that this alignment is preserved within RTL layouts. |
| 70 | + |
| 71 | +### Accessibility |
| 72 | + |
| 73 | +By default, `md-checkbox` provides all the accessibility attributes needed. It also supports |
| 74 | +keyboard navigation and toggling via the spacebar. However, you can provide an `aria-label` to the |
| 75 | +checkbox if you do not wish to have any label text. |
| 76 | + |
| 77 | +```html |
| 78 | +<md-checkbox [checked]="false" aria-label="My standalone checkbox"></md-checkbox> |
| 79 | +``` |
0 commit comments