Components / Library version 3.28.0

Input

The Input component provides an accessible text input field. See properties for all functionality.

Properties Examples Events Accessibility Notes

* Required property

label *
string
A description for the input. Required even if the label-position is set to none (for accessibility reasons).
character-limit
number
The maximum number of characters the user can type. The character count and limit will be displayed on the right side of the field. Character limiting is disabled when this property is unset.
disabled
boolean
Disables the component.
error-message
string
Set this string to display an error message.
info
string
Set the info text displayed under the input field.
input-width
string: CSS width value
Set the width of the input independently of the width of the component so that label, info text or error message can be wider than the input. Defaults to 100%.
label-position
top | left | none
Defaults to top. Set to none if no label should be displayed.
min
number
For use with type="number", the minimum value that can be reached using the stepper.
max
number
For use with type="number", the maximum value that can be reached using the stepper.
placeholder
string
Set the placeholder text within the input field.
prevent-validation
string
Validation will not occur when clicking on an element with this id. Accepts multiple ids separated by spaces. See Notes tab for more information.
required-field
boolean
Set this property to indicate this input as required.
required-field-message
string
The message to display when an error is displayed due to the field being left empty. If not set, this message will be: "This field is required."
step
number
For use with type="number", the interval used when stepping between values.
symbol-before
string
Display the string before the value (e.g. "$").
symbol-after
string
Display the string after the value (e.g. "%").
text-after
string
Display the string after the input. This text should be no longer than 55 characters.
type
text | number
The input's type, defaults to text.
value
string
The value to initially set the input field, or the input field's current value.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Usage in Elm

Code generated from HTML.
wmInputValueChanged
Emitted on blur when Input's value changes.
input
Emitted when a user types in the input field.

Screen Reader

Error messages will be announced via live-region. If the info property is present, info text will be read upon focusing the input field.

The prevent validation prop is used with a specific use-case in mind. When components that feature required fields are initally focused within a modal, closing the modal will flash the required error. The prevent validation prop is useful in this case, where the close button's id can be passed through preventing the validation flash.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.