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:

button: Button
checkbox: Checkbox
date: Date Picker | Date Range Picker
file: File Picker
number: Number Field
range: Slider | Range Slider
time: Time Picker

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.

<script setup lang="ts">
import { VTextField } from '@vonage/vivid-api-vue';
</script>

<template>
  <div class="fields">
    <VTextField type="tel" inputmode="tel" label="Telephone number" />
    <VTextField type="email" inputmode="email" label="Email address" />
  </div>
</template>

<style scoped>
.fields {
  display: flex;
  gap: 16px;
}
</style>

<div>
  <vwc-text-field type="tel" inputmode="tel" label="Telephone number"></vwc-text-field>
  <vwc-text-field type="email" inputmode="email" label="Email address"></vwc-text-field>
</div>

<style>
  div {
    display: flex;
    gap: 16px;
  }
</style>

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.

<script setup lang="ts">
import { VTextField, VButton, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VTextField type="search" inputmode="search" label="Search"
    ><template #icon><VIcon name="search" /></template>
    <template #action-items>
      <div class="action-items">
        <VButton size="condensed" aria-label="Record search query">
          <template #icon><VIcon name="microphone-2-line" /></template>
        </VButton>
        <VButton size="condensed" aria-label="Clear field">
          <template #icon><VIcon name="close-line" /></template>
        </VButton>
      </div>
    </template>
  </VTextField>
</template>

<style scoped>
.action-items {
  display: flex;
}
</style>

<vwc-text-field type="search" inputmode="search" label="Search"
  ><vwc-icon slot="icon" name="search"></vwc-icon>
  <div slot="action-items" class="action-items">
    <vwc-button size="condensed" aria-label="Record search query">
      <vwc-icon slot="icon" name="microphone-2-line"></vwc-icon>
    </vwc-button>
    <vwc-button size="condensed" aria-label="Clear field">
      <vwc-icon slot="icon" name="close-line"></vwc-icon>
    </vwc-button>
  </div>
</vwc-text-field>

<style>
  .action-items {
    display: flex;
  }
</style>

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.

<script setup lang="ts">
import { VTextField, VSelect, VOption, VDivider } from '@vonage/vivid-api-vue';
</script>

<template>
  <VTextField label="Search groceries" type="search" inputmode="search">
    <template #leading-action-items>
      <div class="leading-action-items">
        <VSelect aria-label="Options Selector" appearance="ghost" style="--focus-inset: 2px">
          <VOption value="all" text="All" selected />
          <VOption value="fruit" text="Fruit" />
          <VOption value="veg" text="Vegetables" />
        </VSelect>
        <VDivider orientation="vertical" style="height: 20px" />
      </div>
    </template>
  </VTextField>
</template>

<style scoped>
.leading-action-items {
  display: flex;
  align-items: center;
  column-gap: 2px;
}
</style>

<vwc-text-field label="Search groceries" type="search" inputmode="search">
  <div slot="leading-action-items" class="leading-action-items">
    <vwc-select aria-label="Options Selector" appearance="ghost">
      <vwc-option value="all" text="All" selected></vwc-option>
      <vwc-option value="fruit" text="Fruit"></vwc-option>
      <vwc-option value="veg" text="Vegetables"></vwc-option>
    </vwc-select>
    <vwc-divider orientation="vertical"></vwc-divider>
  </div>
</vwc-text-field>

<style>
  .leading-action-items {
    display: flex;
    align-items: center;
    column-gap: 2px;
  }
  vwc-select {
    --focus-inset: 2px;
  }
  vwc-divider {
    height: 20px;
  }
</style>

Helper Text Slot

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

<script setup lang="ts">
import { VTextField } from '@vonage/vivid-api-vue';
</script>

<template>
  <div class="helper-text-slot-demo">
    <VTextField label="EIN" :maxlength="12" char-count pattern="[0-9]*" inputmode="numeric" style="width: 100%">
      <template #helper-text>
        <span><a href="#">Employer Identification Number</a> should be 12 characters</span>
      </template>
    </VTextField>
  </div>
</template>

<style scoped>
.helper-text-slot-demo {
  width: 400px;
}
</style>

<vwc-text-field label="EIN" maxlength="12" char-count pattern="[0-9]*" inputmode="numeric">
  <span slot="helper-text"> <a href="#">Employer Identification Number</a> should be 12 characters </span>
</vwc-text-field>

<style>
  vwc-text-field {
    width: 400px;
  }
</style>

Contextual-Help

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

<script setup lang="ts">
import { VTextField, VContextualHelp } from '@vonage/vivid-api-vue';
</script>

<template>
  <VTextField label="First name">
    <template #contextual-help>
      <VContextualHelp>This is the contextual help</VContextualHelp>
    </template>
  </VTextField>
</template>

API Reference

Properties

Property	Type	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.
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	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.
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.
icon	The preferred way to add an icon to the component.
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.
icon	The preferred way to add an icon to the component.
leading-action-items	Used to add action items to the start of the text-field.

Events

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

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	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}