Skip to content

Commit 32c04f0

Browse files
traviskaufmanjelbourn
authored andcommitted
docs(MdCheckbox): Create README for MdCheckbox.
Closes #185
1 parent 70ab791 commit 32c04f0

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed

src/components/checkbox/README.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
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

Comments
 (0)