Inputs

Variations Design Guidelines Code Reference Accessibility

Inputs
updated

HTML/CSS Available
Web Component Available
Last Updated
2.24.0

Inputs allow a user to input and interact with data.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to solicit a short, single line of text or a number.

Default

HTML

Web Component

<!-- Default -->
<input class="mds-form__input" type="text" id="input-id">
<!-- With Placeholder Text -->
<input class="mds-form__input" type="text" id="input-id" placeholder="First Name">
<!-- Disabled -->
<input class="mds-form__input" type="text" id="input-id" disabled>

<!-- Default -->
<mds-input id="input-id"></mds-input>
<!-- With Placeholder Text -->
<mds-input placeholder="First Name" id="input-id"></mds-input>
<!-- Disabled -->
<mds-input id="input-id" disabled></mds-input>

Always use a Label to describe an input. If you need additional instructional content, consider using Microcopy.
Never use placeholder text instead of a Label. Placeholder text should only provide additional context to a user and should never be the primary means of describing the input.
Always wrap grouped form elements in a mds-form__field-group container. See the Forms composition section for more guidelines on constructing forms.

<!-- HTML -->
<div class="mds-form__field-group">
    <label class="mds-form__label" for="first-name"> First Name </label>
    <input class="mds-form__input" type="text" id="first-name" placeholder="First Name" />
</div>
<!-- Web Component -->
<mds-field-group>
    <mds-label for="first-name"> First Name </mds-label>
    <mds-input id="first-name" placeholder="First Name"></mds-input>
</mds-field-group>

Right Aligned

Use to right align numeric input.

Right Aligned

HTML

Web Component

<input class="mds-form__input mds-form__input--right-aligned" type="text" id="input-id" value="12,345.67">

<mds-input right-aligned value="12,345.67" id="input-id"></mds-input>

Sizing

Sizing affects input size, text size and internal spacing. The default size is medium, and you can use modifier classes or props to make the input smaller or larger.

Small

Medium (Default)

Large

Touch

Small

Medium (Default)

Large

Touch

HTML

Web Component

<input class="mds-form__input mds-form__input--small" type="text" id="input-id" placeholder="First Name">

<mds-input size="small" placeholder="First Name" id="input-id"></mds-input>

See mixin documentation for additional details on how to create media queries to switch to the touch size.

Use When

A user must enter a name, email address, phone number, street address, age, salary, etc.

Don’t Use When

Gathering multiple lines of text. Instead, use a Text Area.
Performing a search. Instead, use a Search Field.

Behaviors

Placeholder text disappears when a user types in the input. If a user doesn’t enter a value and moves to another part of a form, the placeholder text reappears in the former text box.
In IE11, placeholder text is cleared on focus. This is default behavior and a known issue, teams are still encouraged to use text boxes in production.

Editorial

Placeholder text should be active. Start the text with a verb.
Don’t end placeholder text with a period.
Use title case for placeholder text.

CSS

Class References

Class	Applies to	Outcome
`mds-form__input--small`	`mds-form__input`	Applies small styles to the input.
`mds-form__input--large`	`mds-form__input`	Applies large styles to the input.
`mds-form__input--touch`	`mds-form__input`	Applies touch styles to the input.
`mds-form__input--right-aligned`	`mds-form__input`	Right aligns the input’s content.

Mixins

Touch Properties

Use this mixin to create media queries in your product styles to switch inputs to their touch variation.

@include mds-input-touch-properties();

For example, switching to the touch variation on screens with a max-width of 500px:

// Your product SCSS
@media screen and (max-width: 500px) {
    @include mds-input-touch-properties();
}

The mixin includes all CSS properties required to convert any size into the touch variation.
Use a media query that makes the most sense for your product, in addition to max-width, pointer: coarse is another helpful method for targeting touch screen devices.
If you don’t want every instance to change, consider using a wrapping class around the media query to target specific elements in your product.
When composing complex forms, consider using the @include mds-form-all-touch-properties(); mixin for efficiency.

Web Component

Props

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop	Type	Validation	Default	Description
`additionalClass`	String	—	—	A space-separated list of class names that will be appended to the default `mds-form__input` element.
`ariaDescribedby`	String	—	—	A space-separated list of element id, like microcopy or a field errors, whose content contains information about the input.
`ariaInvalid`	String	One of: `false`, `true`, `grammar`, `spelling`	`false`	Sets `aria-invalid` attribute.
`autocomplete`	String	—	—	Adds `autocomplete` attribute. See available values.
`disabled`	Boolean	—	`false`	If `true`, sets the `disabled` attribute on the input, rendering it non-interactive, and applies disabled styling.
`id`	String	Required	—	The `id` attribute for the HTML element.
`max`	Number	—	—	Maximum for type `number`.
`maxlength`	Number	—	—	If provided, sets the maximum number of characters allowed.
`min`	Number	—	—	Minimum for type `number`.
`minlength`	Number	—	—	If provided, sets the minimum number of characters allowed.
`name`	String	—	—	Adds the `name` attribute to the input element.
`pattern`	String	—	—	RegExp pattern for value to be validated against.
`placeholder`	String	—	—	Adds placeholder text.
`readonly`	Boolean	—	`false`	Adds the `readonly` attribute.
`required`	Boolean	—	`false`	If true, adds the `required` attribute.
`rightAligned`	Boolean	—	`false`	If `true`, right aligns the input’s content.
`size`	String	One of: `small`, `medium`, `large`, `touch`	`medium`	Alters the size of the input.
`spellcheck`	Boolean	—	—	Sets the `spellcheck` attribute on the input.
`step`	Number	Conditional based on `type="number"`	—	Sets the increment for the input. Only valid for `type="number"`.
`type`	String	One of: `email`, `number`, `password`, `tel`, `text`, `url`	`text`	Sets the `type` attribute for the `<input>`.
`value`	String	—	—	Text value for the input.

Usage Examples

Setting size, required, id, and placeholder via props:

<mds-input size="small" placeholder="First Name" id="input-id" required></mds-input>

Setting value, ariaDescribedby, id, and readonly via props:

<mds-input value="Jane" aria-describedy="first-name-microcopy" id="input-id" readonly></mds-input>

Setting type, minlength, id, and required via props:

<mds-input type="password" minlength="8" id="input-id" required></mds-input>

Browser Support

This component uses a box-shadow property to create an outline. Internet Explorer and Safari have known issues rendering these outlines when using the browser's zoom functionality. This visual defect doesn't affect the functionality of the component.
When using the minlength property in Edge v17+, if required isn’t set, and the user didn’t specify a value, minlength has no affect.

Implementation

Use placeholder text to provide an example of the type of input you need from the user. For example, if you need a phone number in a certain format, include (123) 456-7890 as placeholder text.
Include an aria-describedby attribute on each input that has an .mds-form__microcopy or an .mds-form__field-error component providing additional information. The value of the aria-describedby attribute must match the id attribute on the .mds-form__microcopy or .mds-form__field-error component.
Always pair a Label with an input. Include a for attribute on each label with a value matching the id attribute on the corresponding input.

Best Practices

Never use placeholder text in place of a label. See Labels for more information.

Variations

Default

Right Aligned

Sizing

Use When

Don’t Use When

Behaviors

Editorial

Related UI Components

Related UX Patterns

CSS

Class References

Mixins

Touch Properties

Web Component

Props

Usage Examples

Browser Support

Implementation

Best Practices