packages/mdc-select/helper-text/README.md
Helper text gives context about a select, such as how the selection will be used. It should be visible either persistently or only on invalid state.
<p class="mdc-select-helper-text" aria-hidden="true">
NOTE: Make sure there are no white-space characters before helper text content.
import {MDCSelectHelperText} from '@material/select/helper-text';
const helperText = new MDCSelectHelperText(document.querySelector('.mdc-select-helper-text'));
Note that in every example where the helper text is dependent on the state of the select element, we
assign an id to the mdc-select-helper-text element and set that id to the value of the
aria-controls and aria-describedby attributes on the element with the mdc-select__selected-text class.
We recommend doing this as well as it will help indicate to assistive devices that
the display of the helper text is dependent on the interaction with the MDCSelect component.
<div class="mdc-select mdc-select--filled">
<div class="mdc-select__anchor"
role="button"
aria-haspopup="listbox"
aria-labelledby="demo-label demo-selected-text"
aria-controls="my-helper-text"
aria-describedby="my-helper-text">
<!-- rest of main component -->
</div>
<p id="my-helper-text" class="mdc-select-helper-text">Helper text</p>
When using our JS component, if the browser sees that the input element has an aria-controls
attribute, it will look for an element with the id specified and treat it as the Select's helper
text element, taking care of adding/removing aria-hidden and other accessibility attributes. Adding
and removing classes and attributes to the helper text element can also be done using the
MDCSelectHelperText API, which is described below.
| CSS Class | Description |
|---|---|
mdc-select-helper-text | Mandatory. By default non-validation helper text is always visible. |
mdc-select-helper-text--validation-msg | Indicates the helper text is a validation message. By default validation message is hidden unless the select is invalid. |
mdc-select-helper-text--validation-msg-persistent | When the helper text is serving as a validation message, make it permanently visible regardless of the select's validity. |
| Mixin | Description |
|---|---|
helper-text-color($color) | Customizes the color of the helper text following a select. |
disabled-helper-text-color($color) | Customizes the color of the helper text following a select when disabled. |
helper-text-validation-color($color) | Customizes the color of the helper text validation message when the select is invalid. |
hover-helper-text-validation-color($color) | Customizes the color of the helper text validation message when the select is invalid and hovered. |
MDCSelectHelperText properties and methods| Property | Value Type | Description |
|---|---|---|
foundation | MDCSelectHelperTextFoundation | Returns the helper text's foundation. This allows the parent MDCSelect component to access the public methods on the MDCSelectHelperTextFoundation class. |
If you are using a JavaScript framework, such as React or Angular, you can create a Helper Text for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.
MDCSelectHelperTextAdapter| Method Signature | Description |
|---|---|
addClass(className: string) => void | Adds a class to the helper text element. |
removeClass(className: string) => void | Removes a class from the helper text element. |
hasClass(className: string) => boolean | Returns true if classname exists for the helper text element. |
setAttr(attr: string, value: string) => void | Sets an attribute with a given value on the helper text element. |
removeAttr(attr: string) => void | Removes an attribute on the helper text element. |
setContent(attr: string) => void | Sets the text content for the helper text element. |
MDCSelectHelperTextFoundation| Method Signature | Description |
|---|---|
| `getId() => string | null` |
isVisible() => boolean | Returns whether the helper text is visible. |
setContent(content: string) => void | Sets the content of the helper text. |
setValidation(isValidation: boolean) => void | Sets the helper text as a validation message. By default, validation messages are hidden when the select is valid and visible when the select is invalid. |
setValidationMsgPersistent(isPersistent: boolean) => void | This keeps the validation message visible even if the select is valid, though it will be displayed in the normal (grey) color. |
setValidity(inputIsValid: boolean) => void | Sets the validity of the helper text based on the input validity. |