|
1 |
| -# mdInput / mdTextarea |
| 1 | +**NOTE: The <code>md-input</code> element is deprecated. <code>md-input-container</code> should be |
| 2 | +used instead.** |
2 | 3 |
|
3 |
| -Inputs are the basic input component of Material 2. The spec can be found [here](https://www.google.com/design/spec/components/text-fields.html). |
| 4 | +# md-input-container |
4 | 5 |
|
| 6 | +Inputs are the basic input component of Material 2. The spec can be found |
| 7 | +[here](https://www.google.com/design/spec/components/text-fields.html). `md-input-container` acts as |
| 8 | +a wrapper for native `input` and `textarea` elements. The native element wrapped by the |
| 9 | +`md-input-container` must be marked with the `md-input` directive. |
5 | 10 |
|
| 11 | +Simple `input` example: |
| 12 | +```html |
| 13 | +<md-input-container> |
| 14 | + <input md-input> |
| 15 | +</md-input-container> |
| 16 | +``` |
6 | 17 |
|
7 |
| -## Notes |
8 |
| -* The `<md-input>` / `<md-textarea>` component fully support two-way binding of `ngModel`, as if it was a normal `<input>` and `<textarea>`. |
9 |
| - |
10 |
| - |
| 18 | +Simple `textarea` example: |
| 19 | +```html |
| 20 | +<md-input-container> |
| 21 | + <textarea md-input></textarea> |
| 22 | +</md-input-container> |
| 23 | +``` |
11 | 24 |
|
12 |
| -## Type |
| 25 | +## Usage |
13 | 26 |
|
14 |
| -At the time of writing this README, the `[type]` attribute is copied to the actual `<input>` element in the `<md-input>`. |
| 27 | +### `input` and `textarea` attributes |
15 | 28 |
|
16 |
| -The valid `type` attribute values are any supported by your browser, with the exception of `file`, `checkbox` and `radio`. File inputs aren't supported for now, while check boxes and radio buttons have their own components. |
| 29 | +All of the attributes that can be used with normal `input` and `textarea` elements can be used on |
| 30 | +elements within the `md-input-container` as well. This includes angular specific ones such as |
| 31 | +`ngModel` and `formControl`. |
17 | 32 |
|
| 33 | +The only limitations are that the `type` attribute can only be one of the values supported by |
| 34 | +`md-input-container` and the native element cannot specify a `placeholder` attribute if the |
| 35 | +`md-input-container` also contains a `md-placeholder` element. |
18 | 36 |
|
19 |
| -## Placeholder |
| 37 | +#### Supported `input` types |
20 | 38 |
|
21 |
| -A placeholder is an indicative text displayed in the input zone when the input does not contain text. When text is present, the indicative text will float above this input zone. |
| 39 | +The following [input types](http://www.w3schools.com/TAGs/att_input_type.asp) can be used with |
| 40 | +`md-input-container`: |
| 41 | +* date |
| 42 | +* datetime-local |
| 43 | +* email |
| 44 | +* month |
| 45 | +* number |
| 46 | +* password |
| 47 | +* search |
| 48 | +* tel |
| 49 | +* text |
| 50 | +* time |
| 51 | +* url |
| 52 | +* week |
22 | 53 |
|
23 |
| -You can set the `floatingPlaceholder` attribute to `false` to hide the indicative text instead when text is present in the input. |
| 54 | +### Placeholder |
24 | 55 |
|
25 |
| -You can specify a placeholder for the input in one of two ways; either using the `placeholder` attribute, or using an `<md-placeholder>` directive in the `<md-input>`. Using both will raise an error. |
| 56 | +A placeholder is an indicative text displayed in the input zone when the input does not contain |
| 57 | +text. When text is present, the indicative text will float above this input zone. |
26 | 58 |
|
| 59 | +You can set the `floatingPlaceholder` attribute of `md-input-container` to `false` to hide the |
| 60 | +indicative text instead when text is present in the input. |
27 | 61 |
|
28 |
| -## Prefix and Suffix |
| 62 | +You can specify a placeholder for the input in one of two ways; either using the `placeholder` |
| 63 | +attribute on the `input` or `textarea`, or using an `md-placeholder` element in the |
| 64 | +`md-input-container`. Using both will raise an error. |
29 | 65 |
|
30 |
| -You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as per the Material specification, and clicking it will focus the input. |
| 66 | +### Prefix and Suffix |
31 | 67 |
|
32 |
| -To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the `md-suffix` attribute. For example, in a template: |
| 68 | +You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as |
| 69 | +per the Material specification, and clicking it will focus the input. |
33 | 70 |
|
34 |
| -#### Example |
| 71 | +To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the |
| 72 | +`md-suffix` attribute. For example, in a template: |
35 | 73 |
|
36 | 74 | ```html
|
37 |
| -<md-input placeholder="amount" align="end"> |
| 75 | +<md-input-container align="end"> |
| 76 | + <input md-input placeholder="amount"> |
38 | 77 | <span md-prefix>$ </span>
|
39 | 78 | <span md-suffix>.00</span>
|
40 |
| -</md-input> |
| 79 | +</md-input-container> |
41 | 80 | ```
|
42 | 81 |
|
43 |
| -Will result in this: |
44 |
| - |
45 | 82 | <img src="https://material.angularjs.org/material2_assets/input/prefix-suffix.png">
|
46 | 83 |
|
| 84 | +### Hint Labels |
47 | 85 |
|
| 86 | +Hint labels are the labels that show below the underline. You can have up to two hint labels; one on |
| 87 | +the `start` of the line (left in an LTR language, right in RTL), and one on the `end`. |
48 | 88 |
|
49 |
| -## Hint Labels |
50 |
| - |
51 |
| -Hint labels are the labels that shows the underline. You can have up to two hint labels; one on the `start` of the line (left in an LTR language, right in RTL), or one on the `end`. |
52 |
| - |
53 |
| -You specify a hint-label in one of two ways; either using the `hintLabel` attribute, or using an `<md-hint>` directive in the `<md-input>`, which takes an `align` attribute containing the side. The attribute version is assumed to be at the `start`. |
54 |
| - |
| 89 | +You specify a hint label in one of two ways; either using the `hintLabel` attribute of |
| 90 | +`md-input-container`, or using an `md-hint` element inside the `md-input-container`, which takes an |
| 91 | +`align` attribute containing the side. The attribute version is assumed to be at the `start`. |
55 | 92 | Specifying a side twice will result in an exception during initialization.
|
56 | 93 |
|
57 |
| -#### Example |
58 |
| - |
59 |
| -A simple character counter can be made like the following: |
60 |
| - |
| 94 | +For example, a simple character counter can be made like the following: |
61 | 95 | ```html
|
62 |
| -<md-input placeholder="Character count (100 max)" maxlength="100" class="demo-full-width" |
63 |
| - value="Hello world. How are you?" |
64 |
| - #characterCountHintExample> |
65 |
| - <md-hint align="end">{{characterCountHintExample.characterCount}} / 100</md-hint> |
66 |
| -</md-input> |
| 96 | +<md-input-container> |
| 97 | + <input md-input |
| 98 | + placeholder="Character count (100 max)" |
| 99 | + maxlength="100" |
| 100 | + value="Hello world. How are you?" |
| 101 | + #characterCountHintExample> |
| 102 | + <md-hint align="end">{{characterCountHintExample.value.length}} / 100</md-hint> |
| 103 | +</md-input-container> |
67 | 104 | ```
|
68 | 105 |
|
69 | 106 | <img src="https://material.angularjs.org/material2_assets/input/character-count.png">
|
70 | 107 |
|
| 108 | +### Divider Color |
71 | 109 |
|
72 |
| - |
73 |
| -## Divider Color |
74 |
| - |
75 |
| -The divider (line under the `<md-input>` content) color can be changed by using the `dividerColor` attribute. A value of `primary` is the default and will correspond to your theme primary color. Alternatively, you can specify `accent` or `warn`. |
76 |
| - |
77 |
| -#### Example |
78 |
| - |
79 |
| -^((please note that this example has been doctored to show the colors; they would normally show only on focus)^) |
80 |
| - |
81 |
| -<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png"> |
82 |
| - |
83 |
| - |
84 |
| - |
85 |
| -## Labelling |
86 |
| - |
87 |
| -You can label the `<md-input>` as you would a regular `<input>`. |
88 |
| - |
89 |
| -## Focus |
90 |
| - |
91 |
| -You can put the focus on an input component using the `focus()` method. |
92 |
| - |
93 |
| -### Example |
| 110 | +The divider (line under the `input` content) color can be changed by using the `dividerColor` |
| 111 | +attribute of `md-input-container`. A value of `primary` is the default and will correspond to your |
| 112 | +theme primary color. Alternatively, you can specify `accent` or `warn`. |
94 | 113 |
|
95 | 114 | ```html
|
96 |
| -<md-input #nameInput placeholder="name"></md-input> |
| 115 | +<md-input-container> |
| 116 | + <input md-input placeholder="Default color" value="example"> |
| 117 | +</md-input-container> |
| 118 | +<md-input-container dividerColor="accent"> |
| 119 | + <input md-input placeholder="Accent color" value="example"> |
| 120 | +</md-input-container> |
| 121 | +<md-input-container dividerColor="warn"> |
| 122 | + <input md-input placeholder="Warn color" value="example"> |
| 123 | +</md-input-container> |
97 | 124 | ```
|
98 | 125 |
|
99 |
| -```ts |
100 |
| -export class MyComponent implements AfterViewInit { |
101 |
| - @ViewChild('nameInput') nameInput: MdInput; |
| 126 | +_please note that this image has been doctored to show each `input` as if it were focused:_ |
| 127 | +<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png"> |
102 | 128 |
|
103 |
| - ngAfterViewInit() { |
104 |
| - this.nameInput.focus(); |
105 |
| - } |
106 |
| -} |
107 |
| -``` |
| 129 | +### Full Forms |
108 | 130 |
|
109 |
| -## Textareas |
| 131 | +You can make a full form using inputs, and they will support autofill natively. |
110 | 132 |
|
111 | 133 | ```html
|
112 |
| -<md-textarea placeholder="Textarea with autosize"></md-textarea> |
| 134 | +<form> |
| 135 | + <md-input-container style="width: 100%"> |
| 136 | + <input md-input placeholder="Company (disabled)" disabled value="Google"> |
| 137 | + </md-input-container> |
| 138 | + |
| 139 | + <table style="width: 100%" cellspacing="0"><tr> |
| 140 | + <td><md-input-container style="width: 100%"> |
| 141 | + <input md-input placeholder="First name"> |
| 142 | + </md-input-container></td> |
| 143 | + <td><md-input-container style="width: 100%"> |
| 144 | + <input md-input placeholder="Long Last Name That Will Be Truncated"> |
| 145 | + </md-input-container></td> |
| 146 | + </tr></table> |
| 147 | + |
| 148 | + <p> |
| 149 | + <md-input-container width="100%"> |
| 150 | + <textarea md-input placeholder="Address" value="1600 Amphitheatre Pkway"></textarea> |
| 151 | + </md-input-container> |
| 152 | + <md-input-container width="100%"> |
| 153 | + <textarea md-input placeholder="Address 2"></textarea> |
| 154 | + </md-input-container> |
| 155 | + </p> |
| 156 | + |
| 157 | + <table style="width: 100%" cellspacing="0"><tr> |
| 158 | + <td><md-input-container width="100%"> |
| 159 | + <input md-input placeholder="City"> |
| 160 | + </md-input-container></td> |
| 161 | + <td><md-input-container width="100%"> |
| 162 | + <input md-input placeholder="State"> |
| 163 | + </md-input-container></td> |
| 164 | + <td><md-input-container width="100%"> |
| 165 | + <input md-input #postalCode maxlength="5" placeholder="Postal Code" value="94043"> |
| 166 | + <md-hint align="end">{{postalCode.value.length}} / 5</md-hint> |
| 167 | + </md-input-container></td> |
| 168 | + </tr></table> |
| 169 | +</form> |
113 | 170 | ```
|
114 | 171 |
|
115 |
| -### Example |
116 |
| - |
117 |
| -## Full Forms |
118 |
| - |
119 |
| -You can make a full form using inputs, and it will support autofill natively. |
120 |
| - |
121 |
| -#### Example |
| 172 | +<img src="https://material.angularjs.org/material2_assets/input/full-form.png"> |
122 | 173 |
|
123 |
| -```html |
124 |
| -<md-card class="demo-card demo-basic"> |
125 |
| - <md-toolbar color="primary">Basic</md-toolbar> |
126 |
| - <md-card-content> |
127 |
| - <form> |
128 |
| - <md-input class="demo-full-width" placeholder="Company (disabled)" disabled value="Google"> |
129 |
| - </md-input> |
130 |
| - |
131 |
| - <table style="width: 100%" cellspacing="0"><tr> |
132 |
| - <td><md-input placeholder="First name" style="width: 100%"></md-input></td> |
133 |
| - <td><md-input placeholder="Long Last Name That Will Be Truncated" style="width: 100%"></md-input></td> |
134 |
| - </tr></table> |
135 |
| - <p> |
136 |
| - <md-textarea class="demo-full-width" placeholder="Address" value="1600 Amphitheatre Pkway"></md-textarea> |
137 |
| - <md-textarea class="demo-full-width" placeholder="Address 2"></md-textarea> |
138 |
| - </p> |
139 |
| - <table style="width: 100%" cellspacing="0"><tr> |
140 |
| - <td><md-input class="demo-full-width" placeholder="City"></md-input></td> |
141 |
| - <td><md-input class="demo-full-width" placeholder="State"></md-input></td> |
142 |
| - <td><md-input #postalCode class="demo-full-width" maxlength="5" |
143 |
| - placeholder="Postal Code" |
144 |
| - value="94043"> |
145 |
| - <md-hint align="end">{{postalCode.characterCount}} / 5</md-hint> |
146 |
| - </md-input></td> |
147 |
| - </tr></table> |
148 |
| - </form> |
149 |
| - </md-card-content> |
150 |
| -</md-card> |
151 |
| -``` |
| 174 | +## API Summary |
152 | 175 |
|
153 |
| -Will result in this: |
| 176 | +### Inputs |
154 | 177 |
|
155 |
| -<img src="https://material.angularjs.org/material2_assets/input/full-form.png"> |
| 178 | +| Name | Type | Description | |
| 179 | +| --- | --- | --- | |
| 180 | +| `align` | `"start" | "end"` | The alignment of the `input` or `textarea`. Default = `"start"`. | |
| 181 | +| `dividerColor` | `"primary" | "accent" | "warn"` | The color of the placeholder and underline. Default = `"primary"`. | |
| 182 | +| `floatingPlaceholder` | boolean | Whether the placeholder should float above the input after text is entered. Default = `true`. | |
| 183 | +| `hintLabel` | string | The hint text to show on the start end of the `md-input-container`. | |
0 commit comments