Textareas

Variations Design Guidelines Code Reference Accessibility

You are viewing legacy documentation. View the most recent documentation.

Textareas

HTML/CSS Available
Web Component Deprecated
Last Updated
2.34.0

Textareas allow a user to input multiple lines of text.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use when soliciting multiple lines of text.

Default

HTML

Web Component

<!-- Default -->
<textarea class="mds-form__textarea" id="textarea-id"></textarea>
<!-- With Placeholder Text -->
<textarea class="mds-form__textarea" id="textarea-id" placeholder="Tell us more here..."></textarea>
<!-- Disabled -->
<textarea class="mds-form__textarea" id="textarea-id" disabled></textarea>

<!-- Default -->
<mds-textarea id="textarea-id"></mds-textarea>
<!-- With Placeholder Text -->
<mds-textarea id="textarea-id" placeholder="Tell us more here..."></mds-textarea>
<!-- Disabled -->
<mds-textarea id="textarea-id" disabled></mds-textarea>

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="comments">Comments</label>
    <textarea class="mds-form__textarea" id="comments"></textarea>
</div>
<!-- Web Component -->
<mds-field-group>
    <mds-label for="comments">Comments</mds-label>
    <mds-textarea id="comments"></mds-textarea>
</mds-field-group>

Sizing

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

Small

Medium (Default)

Large

Touch

Small

Medium (Default)

Large

Touch

HTML

Web Component

<textarea class="mds-form__textarea mds-form__textarea--small" id="small-textarea" placeholder="Textarea"></textarea>

<mds-textarea placeholder="Textarea" size="small" id="small-textarea"></mds-textarea>

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

Don’t Use When

Gathering short, single lines of text. Instead, use an Input.

Behaviors

Include placeholder text to indicate what information belongs in the textarea. Placeholder text disappears when the user types in the textarea. If the 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 textareas in production.

Editorial

Placeholder text in textareas should be full sentences with punctuation.
Don’t use title case here.

CSS

Class References

Class	Applies to	Outcome
`mds-form__textarea--small`	`mds-form__textarea`	Adjusts styling to render a small textarea.
`mds-form__textarea--large`	`mds-form__textarea`	Adjusts styling to render a large textarea.
`mds-form__textarea--touch`	`mds-form__textarea`	Adjusts styling to render a touch textarea.

Mixins

Touch Properties

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

@include mds-textarea-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-textarea-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__textarea` element.
`ariaDescribedby`	String	—	—	A space-separated list of element `id`, often Microcopy or a Field Error, whose content contains additional information about the textarea.
`ariaInvalid`	Boolean	—	—	Adds the `aria-invalid` attribute if the value is either `false` or `true`.
`disabled`	Boolean	—	`false`	If `true`, sets the `disabled` attribute on the textarea, rendering it non-interactive, and applies disabled styling.
`id`	String	Required	—	The `id` attribute for the HTML element.
`maxlength`	Number	—	—	If provided, sets the maximum number of characters allowed.
`minlength`	Number	—	—	If provided, sets the minimum number of characters allowed.
`name`	String	—	—	Adds the `name` attribute to the textarea element.
`placeholder`	String	—	—	Adds placeholder text.
`readonly`	Boolean	—	`false`	Adds the `readonly` attribute.
`required`	Boolean	—	`false`	If `true`, adds the `required` attribute.
`rows`	Number	—	—	Sets the number of visible text lines.
`size`	String	One of: `small`, `medium`, `large`, `touch`	`medium`	Alters the size of the textarea.
`text`	String	—	—	The content for the textarea.

Usage Examples

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

<mds-textarea id="textarea-id" size="small" placeholder="Comments" required></mds-textarea>

Setting id, ariaInvalid, and minlength via props:

<mds-textarea id="textarea-id" aria-invalid minlength="40"></mds-textarea>

Setting id and text via props:

<mds-textarea id="textarea-id" text="Text area content."></mds-textarea>

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

Include an aria-describedby attribute on each textarea 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 a textarea. Include a for attribute on each label with a value matching the id attribute on the corresponding textarea.

Variations

Default

Sizing

Don’t Use When

Behaviors

Editorial

Related UI Components

Related UX Patterns

CSS

Class References

Mixins

Touch Properties

Web Component

Props

Usage Examples

Implementation Tips

Sticky Hover State on Touch Screens

Browser Support

Implementation