Vivid Logo Vivid

Text Field

The Text Field component is used to allow users to provide text input when the expected input is short. As well as plain text, Text Field supports various types of text, including passwords, email addresses and telephone numbers.

Usage

Types

While Text Field follows the W3C specifictation, it only supports the following types:

text (default), email, password, search, tel, url

We support the following other types with the following components:

Input modes

Along with picking the correct type for the Text Field's purpose, it's also good for user experience to pick the correct inputmode.

The inputmode attribute hints at the type of data that might be entered by the user. This allows a browser to display an appropriate virtual keyboard.

Slots

Action Items Slot

Use the action-items slot to postfix elements to the Text Field input element.
In the example below Buttons are added to implement a custom funcationality for a search field.

Leading Action Items Slot

Use the leading-action-items slot to prefix elements to the Text Field input element.
In the example below a Select is added to implement a category filtered search field.

Helper Text Slot

The helper-text slot allows you to use rich content as the text-field's helper text.

Contextual-Help

The contextual-help slot allows you to add the Contextual Help component next to the label.

API Reference

Properties

Property Type Default Description
appearance 'fieldset' | 'ghost'
autoComplete string
autofocus boolean Indicates that an element should be focused on page load, or when the Dialog that it is part of is displayed
charCount boolean Use in combination with `maxlength` to display a character count.
disabled boolean Sets the element's disabled state. A disabled element will not be included during form submission.
errorText string Provides a custom error message. Any current error state will be overridden.
helperText string Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead.
icon IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
initialValue string The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
inputMode string Hints at the type of data that might be entered by the user while editing the element or its contents. This allows a browser to display an appropriate virtual keyboard.
label string The label for the form element.
list string Value of the id attribute of the `` of autocomplete options
maxlength number Maximum length (number of characters) of `value`
minlength number Minimum length (number of characters) of `value`
name string The name of the element. This element's value will be surfaced during form submission under the provided name.
pattern string Pattern the `value` must match to be valid
placeholder string Text that appears in the input element when it has no value set
readOnly boolean When true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute for more information.
required boolean Require the field to be completed prior to form submission.
scale 'condensed' | 'normal' Sets the display size of the input element
shape 'rounded' | 'pill'
size number Size (in chars) of the input element
spellcheck boolean Controls whether or not to enable spell checking for the input field, or if the default spell checking configuration should be used.
successText string Provides a custom success message. Any current error state will be overridden.
type 'text' | 'email' | 'password' | 'tel' | 'url' Allows setting a type or mode of text.
value
(modelValue)		 string The current value of the element.
Property Type Default Description
appearance 'fieldset' | 'ghost'
autocomplete string
autofocus boolean Indicates that an element should be focused on page load, or when the Dialog that it is part of is displayed
char-count boolean Use in combination with `maxlength` to display a character count.
disabled boolean Sets the element's disabled state. A disabled element will not be included during form submission.
error-text string Provides a custom error message. Any current error state will be overridden.
helper-text string Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead.
icon IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
value string The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
inputmode string Hints at the type of data that might be entered by the user while editing the element or its contents. This allows a browser to display an appropriate virtual keyboard.
label string The label for the form element.
list string Value of the id attribute of the `` of autocomplete options
maxlength number Maximum length (number of characters) of `value`
minlength number Minimum length (number of characters) of `value`
name string The name of the element. This element's value will be surfaced during form submission under the provided name.
pattern string Pattern the `value` must match to be valid
placeholder string Text that appears in the input element when it has no value set
readonly boolean When true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute for more information.
required boolean Require the field to be completed prior to form submission.
scale 'condensed' | 'normal' Sets the display size of the input element
shape 'rounded' | 'pill'
size number Size (in chars) of the input element
spellcheck boolean Controls whether or not to enable spell checking for the input field, or if the default spell checking configuration should be used.
success-text string Provides a custom success message. Any current error state will be overridden.
type 'text' | 'email' | 'password' | 'tel' | 'url' Allows setting a type or mode of text.
current-value string The current value of the element.

Slots

Name Description
action-items Used to add action items to the end of the text-field.
contextual-help Slot for the contextual-help component, displayed next to the label.
helper-text Describes how to use the text-field. Alternative to the `helper-text` attribute.
leading-action-items Used to add action items to the start of the text-field.
Name Description
action-items Used to add action items to the end of the text-field.
contextual-help Slot for the contextual-help component, displayed next to the label.
helper-text Describes how to use the text-field. Alternative to the `helper-text` attribute.
leading-action-items Used to add action items to the start of the text-field.

Events

Event Type Description
change CustomEvent<undefined> Fires a custom 'change' event when the value has changed
input CustomEvent<undefined> Fires a custom 'input' event when the value has changed
update:modelValue string Fires when the modelValue value changes
Name Type Description
change CustomEvent<undefined> Fires a custom 'change' event when the value has changed
input CustomEvent<undefined> Fires a custom 'input' event when the value has changed

Methods

Name Params Returns Description
checkValidity boolean Return the current validity of the element.
focus void
reportValidity boolean Return the current validity of the element. If false, fires an invalid event at the element.
select void Selects all the text in the text field
validate void {@inheritDoc (FormAssociated:interface).validate}