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.
The label attribute provides a short description of the purpose of the Text Field.
If a visible label can’t be used, provide one using the
aria-labelattribute. This ensures screen readers announce the purpose of the element, making it accessible to all users.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField label="First name" /></template><vwc-text-field label="First name"></vwc-text-field>The helper-text attribute provides additional information to help the user enter the correct information.
To add HTML to the helper text, use the helper-text slot.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField helper-text="Must be at least six chars and contain both letters and numbers" label="Password" type="password" /></template><vwc-text-field helper-text="Must be at least six chars and contain both letters and numbers" label="Password" type="password"></vwc-text-field>The placeholder attribute provides an example of the type of input the user needs to enter.
Avoid using placeholder text as a substitute for a label. Placeholder text is not a reliable label—it disappears when users type and is not always announced by screen readers. Use a label element to ensure the Combobox is both visually and programmatically associated with a descriptive label.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField placeholder="name@domain.com" label="Email address" type="email" /></template><vwc-text-field placeholder="name@domain.com" label="Email address" type="email"></vwc-text-field>The char-count attribute can be use in combination with the maxlength attribute to provide a visual character count.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField char-count :maxlength="15" label="Username" helper-text="Maximum of 15 characters" /></template><vwc-text-field char-count maxlength="15" label="Username" helper-text="Maximum of 15 characters"></vwc-text-field>You can add the Contextual Help component using the contextual-help slot. It will be displayed next to the label, providing users additional information.
<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><vwc-text-field label="First name"> <vwc-contextual-help slot="contextual-help">This is the contextual help</vwc-contextual-help></vwc-text-field>The value attribute can be used the set the default value for the Text Field input element.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField value="Joe" label="Username" /></template><vwc-text-field value="Joe" label="Username"></vwc-text-field>The error-text attribute provides a custom error message. Any current error state will be overridden by error-text.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField error-text="Username is already taken" value="Joe" label="Username" /></template><vwc-text-field error-text="Username is already taken" value="Joe" label="Username"></vwc-text-field>The success-text attribute provides a custom success message. Any current error state will be overridden by success-text.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField success-text="Username is available" value="JoeB_89" label="Username" /></template><vwc-text-field success-text="Username is available" value="JoeB_89" label="Username"></vwc-text-field>Use the icon slot to add an icon from the icon library to the component.
<script setup lang="ts">import { VTextField, VIcon } from '@vonage/vivid-api-vue';</script>
<template> <VTextField label="Search" type="search" ><template #icon><VIcon name="search-line" /></template ></VTextField></template><vwc-text-field label="Search" type="search"> <vwc-icon slot="icon" name="search-line"></vwc-icon></vwc-text-field>The scale attribute controls the Text Field input element display size.
Use condensed in situations when space is limited, for example, inside a Data Grid cell.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <div class="container"> <VTextField scale="normal" label="Normal" /> <VTextField scale="condensed" label="Condensed" /> </div></template>
<style scoped>.container { display: flex; gap: 16px;}</style><div class="container"> <vwc-text-field scale="normal" label="Normal"></vwc-text-field> <vwc-text-field scale="condensed" label="Condensed"></vwc-text-field></div>
<style> .container { display: flex; gap: 16px; }</style>The reason for using scale for form elements and not size (as used in other components such as Button), is that size is a HTML attribute that can be used on input elements (and also Text Field) to control the width of the input.
The shape attribute controls the border radius of the Text Field input element.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <div class="container"> <VTextField shape="rounded" label="Rounded" /> <VTextField shape="pill" label="Pill" /> </div></template>
<style scoped>.container { display: flex; gap: 16px;}</style><div class="container"> <vwc-text-field shape="rounded" label="Rounded"></vwc-text-field> <vwc-text-field shape="pill" label="Pill"></vwc-text-field></div>
<style> .container { display: flex; gap: 16px; }</style>The appearance attribute controls the style of the Text Field input element.
Use ghost in combination with a containing element which provides a border, for example Action Group.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <div class="container"> <VTextField appearance="fieldset" label="Fieldset" placeholder="Appearance" /> <VTextField appearance="ghost" label="Ghost" placeholder="Appearance" /> </div></template>
<style scoped>.container { display: flex; gap: 16px;}</style><div class="container"> <vwc-text-field appearance="fieldset" label="Fieldset" placeholder="Appearance"></vwc-text-field> <vwc-text-field appearance="ghost" label="Ghost" placeholder="Appearance"></vwc-text-field></div>
<style> .container { display: flex; gap: 16px; }</style>The disabled attribute disables the Text Field input element.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField disabled label="Username" /></template><vwc-text-field disabled label="Username"></vwc-text-field>The readonly attribute prevents the user from changing the Text Field input element value.
<script setup lang="ts">import { VTextField } from '@vonage/vivid-api-vue';</script>
<template> <VTextField readonly label="Username" value="JoeB_89" /></template><vwc-text-field readonly label="Username" value="JoeB_89"></vwc-text-field>