Skip to content

docs(input): update docs to describe md-input-container rather than md-input #2256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 16, 2016
Merged

docs(input): update docs to describe md-input-container rather than md-input #2256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
608be47
Update input docs and add note that md-input and md-sidenav-layout are
mmalerba Dec 16, 2016
f8a48c8
style fix
mmalerba Dec 16, 2016
78060e8
use bold since github doesn't like color
mmalerba Dec 16, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 135 additions & 107 deletions src/lib/input/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,155 +1,183 @@
# mdInput / mdTextarea
**NOTE: The <code>md-input</code> element is deprecated. <code>md-input-container</code> should be
used instead.**

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).
# md-input-container

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). `md-input-container` acts as
a wrapper for native `input` and `textarea` elements. The native element wrapped by the
`md-input-container` must be marked with the `md-input` directive.

Simple `input` example:
```html
<md-input-container>
<input md-input>
</md-input-container>
```

## Notes
* The `<md-input>` / `<md-textarea>` component fully support two-way binding of `ngModel`, as if it was a normal `<input>` and `<textarea>`.


Simple `textarea` example:
```html
<md-input-container>
<textarea md-input></textarea>
</md-input-container>
```

## Type
## Usage

At the time of writing this README, the `[type]` attribute is copied to the actual `<input>` element in the `<md-input>`.
### `input` and `textarea` attributes

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.
All of the attributes that can be used with normal `input` and `textarea` elements can be used on
elements within the `md-input-container` as well. This includes angular specific ones such as
`ngModel` and `formControl`.

The only limitations are that the `type` attribute can only be one of the values supported by
`md-input-container` and the native element cannot specify a `placeholder` attribute if the
`md-input-container` also contains a `md-placeholder` element.

## Placeholder
#### Supported `input` types

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.
The following [input types](http://www.w3schools.com/TAGs/att_input_type.asp) can be used with
`md-input-container`:
* date
* datetime-local
* email
* month
* number
* password
* search
* tel
* text
* time
* url
* week

You can set the `floatingPlaceholder` attribute to `false` to hide the indicative text instead when text is present in the input.
### Placeholder

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

You can set the `floatingPlaceholder` attribute of `md-input-container` to `false` to hide the
indicative text instead when text is present in the input.

## Prefix and Suffix
You can specify a placeholder for the input in one of two ways; either using the `placeholder`
attribute on the `input` or `textarea`, or using an `md-placeholder` element in the
`md-input-container`. Using both will raise an error.

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.
### Prefix and Suffix

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:
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.

#### Example
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:

```html
<md-input placeholder="amount" align="end">
<md-input-container align="end">
<input md-input placeholder="amount">
<span md-prefix>$&nbsp;</span>
<span md-suffix>.00</span>
</md-input>
</md-input-container>
```

Will result in this:

<img src="https://material.angularjs.org/material2_assets/input/prefix-suffix.png">

### Hint Labels

Hint labels are the labels that show below 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), and one on the `end`.

## Hint Labels

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`.

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`.

You specify a hint label in one of two ways; either using the `hintLabel` attribute of
`md-input-container`, or using an `md-hint` element inside the `md-input-container`, which takes an
`align` attribute containing the side. The attribute version is assumed to be at the `start`.
Specifying a side twice will result in an exception during initialization.

#### Example

A simple character counter can be made like the following:

For example, a simple character counter can be made like the following:
```html
<md-input placeholder="Character count (100 max)" maxlength="100" class="demo-full-width"
value="Hello world. How are you?"
#characterCountHintExample>
<md-hint align="end">{{characterCountHintExample.characterCount}} / 100</md-hint>
</md-input>
<md-input-container>
<input md-input
placeholder="Character count (100 max)"
maxlength="100"
value="Hello world. How are you?"
#characterCountHintExample>
<md-hint align="end">{{characterCountHintExample.value.length}} / 100</md-hint>
</md-input-container>
```

<img src="https://material.angularjs.org/material2_assets/input/character-count.png">

### Divider Color


## Divider Color

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`.

#### Example

^((please note that this example has been doctored to show the colors; they would normally show only on focus)^)

<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png">



## Labelling

You can label the `<md-input>` as you would a regular `<input>`.

## Focus

You can put the focus on an input component using the `focus()` method.

### Example
The divider (line under the `input` content) color can be changed by using the `dividerColor`
attribute of `md-input-container`. A value of `primary` is the default and will correspond to your
theme primary color. Alternatively, you can specify `accent` or `warn`.

```html
<md-input #nameInput placeholder="name"></md-input>
<md-input-container>
<input md-input placeholder="Default color" value="example">
</md-input-container>
<md-input-container dividerColor="accent">
<input md-input placeholder="Accent color" value="example">
</md-input-container>
<md-input-container dividerColor="warn">
<input md-input placeholder="Warn color" value="example">
</md-input-container>
```

```ts
export class MyComponent implements AfterViewInit {
@ViewChild('nameInput') nameInput: MdInput;
_please note that this image has been doctored to show each `input` as if it were focused:_
<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png">

ngAfterViewInit() {
this.nameInput.focus();
}
}
```
### Full Forms

## Textareas
You can make a full form using inputs, and they will support autofill natively.

```html
<md-textarea placeholder="Textarea with autosize"></md-textarea>
<form>
<md-input-container style="width: 100%">
<input md-input placeholder="Company (disabled)" disabled value="Google">
</md-input-container>

<table style="width: 100%" cellspacing="0"><tr>
<td><md-input-container style="width: 100%">
<input md-input placeholder="First name">
</md-input-container></td>
<td><md-input-container style="width: 100%">
<input md-input placeholder="Long Last Name That Will Be Truncated">
</md-input-container></td>
</tr></table>

<p>
<md-input-container width="100%">
<textarea md-input placeholder="Address" value="1600 Amphitheatre Pkway"></textarea>
</md-input-container>
<md-input-container width="100%">
<textarea md-input placeholder="Address 2"></textarea>
</md-input-container>
</p>

<table style="width: 100%" cellspacing="0"><tr>
<td><md-input-container width="100%">
<input md-input placeholder="City">
</md-input-container></td>
<td><md-input-container width="100%">
<input md-input placeholder="State">
</md-input-container></td>
<td><md-input-container width="100%">
<input md-input #postalCode maxlength="5" placeholder="Postal Code" value="94043">
<md-hint align="end">{{postalCode.value.length}} / 5</md-hint>
</md-input-container></td>
</tr></table>
</form>
```

### Example

## Full Forms

You can make a full form using inputs, and it will support autofill natively.

#### Example
<img src="https://material.angularjs.org/material2_assets/input/full-form.png">

```html
<md-card class="demo-card demo-basic">
<md-toolbar color="primary">Basic</md-toolbar>
<md-card-content>
<form>
<md-input class="demo-full-width" placeholder="Company (disabled)" disabled value="Google">
</md-input>

<table style="width: 100%" cellspacing="0"><tr>
<td><md-input placeholder="First name" style="width: 100%"></md-input></td>
<td><md-input placeholder="Long Last Name That Will Be Truncated" style="width: 100%"></md-input></td>
</tr></table>
<p>
<md-textarea class="demo-full-width" placeholder="Address" value="1600 Amphitheatre Pkway"></md-textarea>
<md-textarea class="demo-full-width" placeholder="Address 2"></md-textarea>
</p>
<table style="width: 100%" cellspacing="0"><tr>
<td><md-input class="demo-full-width" placeholder="City"></md-input></td>
<td><md-input class="demo-full-width" placeholder="State"></md-input></td>
<td><md-input #postalCode class="demo-full-width" maxlength="5"
placeholder="Postal Code"
value="94043">
<md-hint align="end">{{postalCode.characterCount}} / 5</md-hint>
</md-input></td>
</tr></table>
</form>
</md-card-content>
</md-card>
```
## API Summary

Will result in this:
### Inputs

<img src="https://material.angularjs.org/material2_assets/input/full-form.png">
| Name | Type | Description |
| --- | --- | --- |
| `align` | `"start" | "end"` | The alignment of the `input` or `textarea`. Default = `"start"`. |
| `dividerColor` | `"primary" | "accent" | "warn"` | The color of the placeholder and underline. Default = `"primary"`. |
| `floatingPlaceholder` | boolean | Whether the placeholder should float above the input after text is entered. Default = `true`. |
| `hintLabel` | string | The hint text to show on the start end of the `md-input-container`. |
4 changes: 4 additions & 0 deletions src/lib/sidenav/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
**NOTE: The <code>md-sidenav-layout</code> element is deprecated. <code>md-sidenav-container</code>
should be used instead.**


# MdSidenav

MdSidenav is the side navigation component for Material 2. It is composed of two components: `<md-sidenav-container>` and `<md-sidenav>`.
Expand Down
2 changes: 1 addition & 1 deletion src/lib/slider/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ right-to-left languages.
| `max` | number | Optional, the maximum number for the slider. Default = `100`. |
| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. |
| `value` | number | Optional, the value to start the slider at. |
| `tick-interval` | `"auto" | number` | Optional, how many steps between tick marks. |
| `tick-interval` | `"auto"` \| number | Optional, how many steps between tick marks. |
| `invert` | boolean | Optional, whether to invert the axis the thumb moves along. |
| `vertical` | boolean | Optional, whether the slider should be oriented vertically. |
| `disabled` | boolean | Optional, whether or not the slider is disabled. Default = `false`. |
Expand Down