Number Field

Allows users to enter a number in a text field or use buttons to increment or decrement the value.

Labelling

Label Text

The label attribute provides a short description of the purpose of the Number Field.

If a visible label can’t be used, provide one using the aria-label attribute. This ensures screen readers announce the purpose of the element, making it accessible to all users.

Placeholder Text

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.

Helper Text

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.

Contextual Help

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 { VContextualHelp, VNumberField } from '@vonage/vivid-api-vue';
</script>

<template>
  <VNumberField label="Wanted quantity">
    <template #contextual-help>
      <VContextualHelp>How many apples do you need</VContextualHelp>
    </template>
  </VNumberField>
</template>

Value

Set the value attribute to set the default value for the number field.
Setting the property on the element will not change the default value, but will change the value shown in the view as well as the submitted value in a form (imitating the native behavior).

Values always use the period (”.”) as the decimal separator, regardless of the user’s locale.

Only the value on the screen is localized.

Value as Number

Use the valueAsNumber property to get or set the value as a number. If no valid value is entered in the field, the valueAsNumber is NaN.

<script setup lang="ts">
import { ref, useTemplateRef, onMounted } from 'vue';
import { VNumberField } from '@vonage/vivid-api-vue';

const valueAsNumber = ref('NaN');
const numberField = useTemplateRef<InstanceType<typeof VNumberField>>('number-field');

const updateValue = () => {
if (numberField.value?.element) {
valueAsNumber.value = numberField.value.element.valueAsNumber;
}
};

</script>

<template>
  <div>
    <VNumberField ref="number-field" label="Quantity" @input="updateValue" />
    <p>valueAsNumber: <span :key="valueAsNumber" v-text="valueAsNumber"></span></p>
  </div>
</template>

<vwc-number-field label="Quantity"></vwc-number-field>
<p>valueAsNumber: <span id="value"></span></p>

<script>
  function update() {
    document.getElementById('value').textContent = document.querySelector('vwc-number-field').valueAsNumber;
  }

  customElements.whenDefined('vwc-number-field').then(update);
  document.querySelector('vwc-number-field').addEventListener('input', update);
</script>

Validation Feedback

Success Text

The success-text attribute provides a custom success message. Any current error state will be overridden by success-text.

Scale

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.

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 Number Field) to control the width of the input.

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

<template>
  <div class="container">
    <VNumberField label="Condensed" scale="condensed" />
    <VNumberField label="Normal" scale="normal" />
  </div>
</template>

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

<div class="container">
  <vwc-number-field label="Condensed" scale="condensed"></vwc-number-field>
  <vwc-number-field label="Normal" scale="normal"></vwc-number-field>
</div>

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

Shape

The shape attribute controls the border radius of the Number Field input element.

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

<template>
  <div class="container">
    <VNumberField label="Pill" shape="pill" />
    <VNumberField label="Rounded" shape="rounded" />
  </div>
</template>

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

<div class="container">
  <vwc-number-field label="Pill" shape="pill"></vwc-number-field>
  <vwc-number-field label="Rounded" shape="rounded"></vwc-number-field>
</div>

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

Appearance

The appearance attribute controls the style of the Number Field input element.
Use ghost in combination with a containing element which provides a border, for example Action Group.

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

<template>
  <div class="container">
    <VNumberField appearance="fieldset" placeholder="appearance" label="fieldset" />
    <VNumberField appearance="ghost" placeholder="appearance" label="ghost" />
  </div>
</template>

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

<div class="container">
  <vwc-number-field appearance="fieldset" placeholder="appearance" label="fieldset"></vwc-number-field>
  <vwc-number-field appearance="ghost" placeholder="appearance" label="ghost"></vwc-number-field>
</div>

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

Disabled

Add the disabled attribute to disable the Number field input element.

Readonly

The readonly attribute prevents the user from changing the Number Field input element value.