1 |
|
2 | title: "Select helper text"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "The helper text provides supplemental information and/or validation messages to users"
|
6 | iconId: menu
|
7 | path: /catalog/input-controls/select-menus/helper-text/
|
8 | -->
|
9 |
|
10 | # Select helper text
|
11 |
|
12 | 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.
|
13 |
|
14 | ## Basic usage
|
15 |
|
16 | ### HTML structure
|
17 |
|
18 | ```html
|
19 | <p class="mdc-select-helper-text" aria-hidden="true">
|
20 | ```
|
21 |
|
22 | > NOTE: Make sure there are no white-space characters before helper text content.
|
23 |
|
24 | ### JavaScript instantiation
|
25 |
|
26 | ```js
|
27 | import {MDCSelectHelperText} from '@material/select/helper-text';
|
28 | const helperText = new MDCSelectHelperText(document.querySelector('.mdc-select-helper-text'));
|
29 | ```
|
30 |
|
31 | #### Accessibility
|
32 |
|
33 | Note that in every example where the helper text is dependent on the state of the `select` element, we
|
34 | assign an id to the `mdc-select-helper-text` element and set that id to the value of the
|
35 | `aria-controls` and `aria-describedby` attributes on the element with the `mdc-select__selected-text` class.
|
36 | We recommend doing this as well as it will help indicate to assistive devices that
|
37 | the display of the helper text is dependent on the interaction with the MDCSelect component.
|
38 |
|
39 | ```html
|
40 | <div class="mdc-select mdc-select--filled">
|
41 | <div class="mdc-select__anchor"
|
42 | role="button"
|
43 | aria-haspopup="listbox"
|
44 | aria-labelledby="demo-label demo-selected-text"
|
45 | aria-controls="my-helper-text"
|
46 | aria-describedby="my-helper-text">
|
47 | <!-- rest of main component -->
|
48 | </div>
|
49 | <p id="my-helper-text" class="mdc-select-helper-text">Helper text</p>
|
50 | ```
|
51 |
|
52 | When using our JS component, if the browser sees that the input element has an `aria-controls`
|
53 | attribute, it will look for an element with the id specified and treat it as the Select's helper
|
54 | text element, taking care of adding/removing `aria-hidden` and other accessibility attributes. Adding
|
55 | and removing classes and attributes to the helper text element can also be done using the
|
56 | MDCSelectHelperText API, which is described below.
|
57 |
|
58 | ## API
|
59 |
|
60 | ### CSS classes
|
61 |
|
62 | CSS Class | Description
|
63 | --- | ---
|
64 | `mdc-select-helper-text` | Mandatory. By default non-validation helper text is always visible.
|
65 | `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.
|
66 | `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.
|
67 |
|
68 | ### Sass mixins
|
69 |
|
70 | Mixin | Description
|
71 | --- | ---
|
72 | `helper-text-color($color)` | Customizes the color of the helper text following a select.
|
73 | `disabled-helper-text-color($color)` | Customizes the color of the helper text following a select when disabled.
|
74 | `helper-text-validation-color($color)` | Customizes the color of the helper text validation message when the select is invalid.
|
75 | `hover-helper-text-validation-color($color)` | Customizes the color of the helper text validation message when the select is invalid and hovered.
|
76 |
|
77 | ## `MDCSelectHelperText` properties and methods
|
78 |
|
79 | Property | Value Type | Description
|
80 | --- | --- | ---
|
81 | `foundation` | `MDCSelectHelperTextFoundation` | Returns the helper text's foundation. This allows the parent `MDCSelect` component to access the public methods on the `MDCSelectHelperTextFoundation` class.
|
82 |
|
83 | ## Usage within frameworks
|
84 |
|
85 | 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](../../../docs/integrating-into-frameworks.md).
|
86 |
|
87 | ### `MDCSelectHelperTextAdapter`
|
88 |
|
89 | Method Signature | Description
|
90 | --- | ---
|
91 | `addClass(className: string) => void` | Adds a class to the helper text element.
|
92 | `removeClass(className: string) => void` | Removes a class from the helper text element.
|
93 | `hasClass(className: string) => boolean` | Returns true if classname exists for the helper text element.
|
94 | `setAttr(attr: string, value: string) => void` | Sets an attribute with a given value on the helper text element.
|
95 | `removeAttr(attr: string) => void` | Removes an attribute on the helper text element.
|
96 | `setContent(attr: string) => void` | Sets the text content for the helper text element.
|
97 |
|
98 | ### `MDCSelectHelperTextFoundation`
|
99 |
|
100 | Method Signature | Description
|
101 | --- | ---
|
102 | `getId() => string|null` | Gets the ID of the helper text.
|
103 | `isVisible() => boolean` | Returns whether the helper text is visible.
|
104 | `setContent(content: string) => void` | Sets the content of the helper text.
|
105 | `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.
|
106 | `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.
|
107 | `setValidity(inputIsValid: boolean) => void` | Sets the validity of the helper text based on the input validity.
|