Inputs
updated

  • HTML/CSS Available
  • Web Component Available
  • Last Updated

    2.30.0

Inputs allow a user to input and interact with data.

See Forms for guidance on composing full forms.

Variations

Default

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

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

Implementation Tips

Sticky Hover State on Touch Screens

On touch screens, :hover states “stick” after tapping an interactive element. To counter this behavior, MDS provides a mixin that resets component hover states to their default styles:

@include mds-sticky-hover-reset();

The mixin uses a media query based on hover: none to target touch screen devices and includes resets for Buttons, Checkboxes, Inputs, List Groups, Radio Buttons, Search Fields, Selects, Switches, and Textareas. You can apply this mixin within your product’s media queries along with other MDS touch styles, for example:

// Your product SCSS
@media screen and (max-width: 500px) {
    @include mds-sticky-hover-reset();
    @include mds-componentName-touch-properties();

    // The rest of your product’s responsive/touch styles...
}

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.