1 2<!--- 3 4This README is automatically generated from the comments in these files: 5paper-input-addon-behavior.html paper-input-behavior.html paper-input-char-counter.html paper-input-container.html paper-input-error.html paper-input.html paper-textarea.html 6 7Edit those files, and our readme bot will duplicate them over here! 8Edit this file, and the bot will squash your changes :) 9 10The bot does some handling of markdown. Please file a bug if it does the wrong 11thing! https://github.com/PolymerLabs/tedium/issues 12 13--> 14 15[](https://travis-ci.org/PolymerElements/paper-input) 16 17_[Demo and API docs](https://elements.polymer-project.org/elements/paper-input)_ 18 19 20##<paper-input> 21 22Material design: [Text fields](https://www.google.com/design/spec/components/text-fields.html) 23 24`<paper-input>` is a single-line text field with Material Design styling. 25 26```html 27<paper-input label="Input label"></paper-input> 28``` 29 30It may include an optional error message or character counter. 31 32```html 33<paper-input error-message="Invalid input!" label="Input label"></paper-input> 34<paper-input char-counter label="Input label"></paper-input> 35``` 36 37It can also include custom prefix or suffix elements, which are displayed 38before or after the text input itself. In order for an element to be 39considered as a prefix, it must have the `prefix` attribute (and similarly 40for `suffix`). 41 42```html 43<paper-input label="total"> 44 <div prefix>$</div> 45 <paper-icon-button suffix icon="clear"></paper-icon-button> 46</paper-input> 47``` 48 49A `paper-input` can use the native `type=search` or `type=file` features. 50However, since we can't control the native styling of the input (search icon, 51file button, date placeholder, etc.), in these cases the label will be 52automatically floated. The `placeholder` attribute can still be used for 53additional informational text. 54 55```html 56<paper-input label="search!" type="search" 57 placeholder="search for cats" autosave="test" results="5"> 58</paper-input> 59``` 60 61See `Polymer.PaperInputBehavior` for more API docs. 62 63### Focus 64 65To focus a paper-input, you can call the native `focus()` method as long as the 66paper input has a tab index. 67 68### Styling 69 70See `Polymer.PaperInputContainer` for a list of custom properties used to 71style this element. 72 73 74 75##<paper-input-char-counter> 76 77`<paper-input-char-counter>` is a character counter for use with `<paper-input-container>`. It 78shows the number of characters entered in the input and the max length if it is specified. 79 80```html 81<paper-input-container> 82 <input is="iron-input" maxlength="20"> 83 <paper-input-char-counter></paper-input-char-counter> 84</paper-input-container> 85``` 86 87### Styling 88 89The following mixin is available for styling: 90 91| Custom property | Description | Default | 92| --- | --- | --- | 93| `--paper-input-char-counter` | Mixin applied to the element | `{}` | 94 95 96 97##<paper-input-container> 98 99`<paper-input-container>` is a container for a `<label>`, an `<input is="iron-input">` or 100`<iron-autogrow-textarea>` and optional add-on elements such as an error message or character 101counter, used to implement Material Design text fields. 102 103For example: 104 105```html 106<paper-input-container> 107 <label>Your name</label> 108 <input is="iron-input"> 109</paper-input-container> 110``` 111 112Do not wrap `<paper-input-container>` around elements that already include it, such as `<paper-input>`. 113Doing so may cause events to bounce infintely between the container and its contained element. 114 115### Listening for input changes 116 117By default, it listens for changes on the `bind-value` attribute on its children nodes and perform 118tasks such as auto-validating and label styling when the `bind-value` changes. You can configure 119the attribute it listens to with the `attr-for-value` attribute. 120 121### Using a custom input element 122 123You can use a custom input element in a `<paper-input-container>`, for example to implement a 124compound input field like a social security number input. The custom input element should have the 125`paper-input-input` class, have a `notify:true` value property and optionally implements 126`Polymer.IronValidatableBehavior` if it is validatable. 127 128```html 129<paper-input-container attr-for-value="ssn-value"> 130 <label>Social security number</label> 131 <ssn-input class="paper-input-input"></ssn-input> 132</paper-input-container> 133``` 134 135If you're using a `<paper-input-container>` imperatively, it's important to make sure 136that you attach its children (the `iron-input` and the optional `label`) before you 137attach the `<paper-input-container>` itself, so that it can be set up correctly. 138 139### Validation 140 141If the `auto-validate` attribute is set, the input container will validate the input and update 142the container styling when the input value changes. 143 144### Add-ons 145 146Add-ons are child elements of a `<paper-input-container>` with the `add-on` attribute and 147implements the `Polymer.PaperInputAddonBehavior` behavior. They are notified when the input value 148or validity changes, and may implement functionality such as error messages or character counters. 149They appear at the bottom of the input. 150 151### Prefixes and suffixes 152 153These are child elements of a `<paper-input-container>` with the `prefix` 154or `suffix` attribute, and are displayed inline with the input, before or after. 155 156```html 157<paper-input-container> 158 <div prefix>$</div> 159 <label>Total</label> 160 <input is="iron-input"> 161 <paper-icon-button suffix icon="clear"></paper-icon-button> 162</paper-input-container> 163``` 164 165### Styling 166 167The following custom properties and mixins are available for styling: 168 169| Custom property | Description | Default | 170| --- | --- | --- | 171| `--paper-input-container-color` | Label and underline color when the input is not focused | `--secondary-text-color` | 172| `--paper-input-container-focus-color` | Label and underline color when the input is focused | `--primary-color` | 173| `--paper-input-container-invalid-color` | Label and underline color when the input is is invalid | `--error-color` | 174| `--paper-input-container-input-color` | Input foreground color | `--primary-text-color` | 175| `--paper-input-container` | Mixin applied to the container | `{}` | 176| `--paper-input-container-disabled` | Mixin applied to the container when it's disabled | `{}` | 177| `--paper-input-container-label` | Mixin applied to the label | `{}` | 178| `--paper-input-container-label-focus` | Mixin applied to the label when the input is focused | `{}` | 179| `--paper-input-container-label-floating` | Mixin applied to the label when floating | `{}` | 180| `--paper-input-container-input` | Mixin applied to the input | `{}` | 181| `--paper-input-container-underline` | Mixin applied to the underline | `{}` | 182| `--paper-input-container-underline-focus` | Mixin applied to the underline when the input is focused | `{}` | 183| `--paper-input-container-underline-disabled` | Mixin applied to the underline when the input is disabled | `{}` | 184| `--paper-input-prefix` | Mixin applied to the input prefix | `{}` | 185| `--paper-input-suffix` | Mixin applied to the input suffix | `{}` | 186 187This element is `display:block` by default, but you can set the `inline` attribute to make it 188`display:inline-block`. 189 190 191 192##<paper-input-error> 193 194`<paper-input-error>` is an error message for use with `<paper-input-container>`. The error is 195displayed when the `<paper-input-container>` is `invalid`. 196 197```html 198<paper-input-container> 199 <input is="iron-input" pattern="[0-9]*"> 200 <paper-input-error>Only numbers are allowed!</paper-input-error> 201</paper-input-container> 202``` 203 204### Styling 205 206The following custom properties and mixins are available for styling: 207 208| Custom property | Description | Default | 209| --- | --- | --- | 210| `--paper-input-container-invalid-color` | The foreground color of the error | `--error-color` | 211| `--paper-input-error` | Mixin applied to the error | `{}` | 212 213 214 215##<paper-textarea> 216 217`<paper-textarea>` is a multi-line text field with Material Design styling. 218 219```html 220<paper-textarea label="Textarea label"></paper-textarea> 221``` 222 223See `Polymer.PaperInputBehavior` for more API docs. 224 225### Validation 226 227Currently only `required` and `maxlength` validation is supported. 228 229### Styling 230 231See `Polymer.PaperInputContainer` for a list of custom properties used to 232style this element. 233 234 235 236##Polymer.PaperInputAddonBehavior 237 238Use `Polymer.PaperInputAddonBehavior` to implement an add-on for `<paper-input-container>`. A 239add-on appears below the input, and may display information based on the input value and 240validity such as a character counter or an error message. 241 242 243 244##Polymer.PaperInputBehavior 245 246Use `Polymer.PaperInputBehavior` to implement inputs with `<paper-input-container>`. This 247behavior is implemented by `<paper-input>`. It exposes a number of properties from 248`<paper-input-container>` and `<input is="iron-input">` and they should be bound in your 249template. 250 251The input element can be accessed by the `inputElement` property if you need to access 252properties or methods that are not exposed. 253 254 255
){kind=link}