Input

<gr-input> | GrInput

Inputs can be used in forms, or anywhere where the user needs to provide information.

<gr-input label="Name"></gr-input>

Options

Placeholders

Use the placeholder attribute to add a placeholder.

The placeholder text, also commonly known as “ghost text,” is temporary and disappears once a user enters text.

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, this text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. Help text is the preferred way to communicate this information.

<gr-input placeholder="Type something"></gr-input>

Clearable

Add the clearable attribute to add a clear button when the input has content.

<gr-input placeholder="Clearable" clearable></gr-input>

Toggle password

Add the toggle-password attribute to add a toggle button that will show the password when activated.

<gr-input type="password" placeholder="Password Toggle" size="small" toggle-password></gr-input>
<br />
<gr-input type="password" placeholder="Password Toggle" size="medium" toggle-password></gr-input>
<br />
<gr-input type="password" placeholder="Password Toggle" size="large" toggle-password></gr-input>

Pill

Use the pill attribute to give inputs rounded edges.

<gr-input placeholder="Small" size="small" pill></gr-input>
<br />
<gr-input placeholder="Medium" size="medium" pill></gr-input>
<br />
<gr-input placeholder="Large" size="large" pill></gr-input>

Disabled

Use the disabled attribute to disable an input.

<gr-input placeholder="Disabled" size="small" disabled></gr-input>
<br />
<gr-input placeholder="Disabled" size="medium" disabled></gr-input>
<br />
<gr-input placeholder="Disabled" size="large" disabled></gr-input>

Sizes

Use the size attribute to change an input's size.

<gr-input placeholder="Small" size="small"></gr-input>
<br />
<gr-input placeholder="Medium" size="medium"></gr-input>
<br />
<gr-input placeholder="Large" size="large"></gr-input>

Icons

Use the start and end slots to add icons.

<gr-input placeholder="Medium" size="small">
  <ion-icon name="search-outline" slot="start"></ion-icon>
  <ion-icon name="chatbubble-outline" slot="end"></ion-icon>
</gr-input>
<br />
<gr-input placeholder="Medium" size="medium">
  <ion-icon name="search-outline" slot="start"></ion-icon>
  <ion-icon name="chatbubble-outline" slot="end"></ion-icon>
</gr-input>
<br />
<gr-input placeholder="Medium" size="large">
  <ion-icon name="search-outline" slot="start"></ion-icon>
  <ion-icon name="chatbubble-outline" slot="end"></ion-icon>
</gr-input>

Invalid

The input can be marked invalid using the invalid attribute.

<gr-input placeholder="Invalid" invalid></gr-input>

Labels

Use the label attribute to give the input an accessible label. For labels that contain HTML, use the label slot instead.

<gr-input label="Name"></gr-input>

Required or optional

Inputs can be marked as optional or required, depending on the situation. For required inputs, there are two styling options: a “(required)” label or an asterisk with the required-indicator attribute. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional inputs are either denoted with text added to the end of the label — “(optional)” — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

<gr-input label="Email address (required)" value="soof@paqt.com"></gr-input>
<br />
<gr-input label="Email address (optional)" value="soof@paqt.com"></gr-input>
<br />
<gr-input label="Email address" value="soof@paqt.com" required-indicator></gr-input>

Help Text

Add descriptive help text to an input with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

<gr-input label="Nickname" help-text="What would you like people to call you?"></gr-input>

Invalid Text

Add descriptive invalid text to an input with the invalid-text attribute. For invalid texts that contain HTML, use the invalid-text slot instead.

When you add the invalid attribute, the invalid text will be shown. When an input already includes help text, the help text is replaced with invalid text.

<gr-input
  label="Nickname"
  help-text="What would you like people to call you?"
  invalid-text="Enter what you would like people to call you."
  invalid
></gr-input>

Pattern

Add a pattern to specify a regular expression that the input value should match.

<gr-input
  label="Country code"
  help-text="Fill in a valid three letter country code"
  pattern="[A-Za-z]{3}"
></gr-input>

Usage guidelines

Include a label

Every input should have a label. A field without a label is ambiguous and not accessible.

Review label-less designs

In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML.

Follow capitalization rules

Field labels and placeholder text should be in sentence case.

Mark the minority of fields in a form as optional or required

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the fields are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the fields are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a field is optional. If you use an asterisk, be sure to include hint text to explain what the asterisk means.

Try to only ask for information that’s required.

For large forms involving sensitive data like checkout processes and long account creation forms, it's better to mark both required fields & optional fields explicitly (required fields with an asterisk, and label appended with “(optional)” for optional fields).

Use help text to show hints, formatting, and requirements

The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:

• An overall description of the input field
• Hints for what kind of information needs to be input
• Specific formatting examples or requirements

The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text.

Use help text instead of placeholder text

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible, and should be avoided if possible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text.

Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, and especially if they're communicating the same thing.

Validation

We recommend validating the users data before form submission. Use visual cues to guide the user as to where the problem lies within the form. This will help to easily identify the elements that need to be corrected.

The validation should appear when the user has clicked away from the input (not before), or otherwise when the user submits the form. Once the user corrects the errors within the text field, the validation should disappear once the data is rendered as valid.

For Vue, we recommend Vuelidate to implement this behavior. See a working example (CodeSandbox).

Of course, you should still validate server-side (if applicable).

Always write invalid text when invalid

Don't just mark an input invalid and expect the user to understand why it's invalid. Furthermore, the invalid text displays an icon which is needed for accessibility, and gives more attention to the invalid field.

Switch help text with invalid text

The help text area also displays an error message. When a text field already includes help text and it's marked invalid, the help text is replaced with invalid text. Once it's no longer invalid, the help text description reappears below the field.

Since one gets replaced by the other, the language of the help text and invalid text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Invalid text tells a user how to make it valid by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the invalid text include the same essential information so that it isn’t lost if one replaces the other (e.g., password requirements).

Write invalid text that shows a solution

Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user.

Invalid text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For text fields, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the invalid text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”

Properties

Events

Methods

removeFocus() => Promise<void>

Removes focus from the input.

Returns

Type: Promise<void>

select() => Promise<void>

Selects all the text in the input.

Returns

Type: Promise<void>

setFocus(options?: FocusOptions) => Promise<void>

Sets focus on the input.

Returns

Type: Promise<void>

setRangeText(replacement: string, start: number, end: number, selectMode?: 'select' | 'start' | 'end' | 'preserve') => Promise<void>

Replaces a range of text with a new string.

Returns

Type: Promise<void>

setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: 'forward' | 'backward' | 'none') => Promise<void>

Sets the start and end positions of the text selection (0-based).

Returns

Type: Promise<void>

Slots

CSS custom properties