Docs

Docs

Number Field

Source: TypeScript / Java
Number Field is an input field that accepts only numeric input.

Number Field is an input field that accepts only numeric input. The input can be a decimal or an integer. There is also a big decimal for Flow.

You can specify a unit as a prefix, or a suffix for the field.

Open in a
new tab
NumberField dollarField = new NumberField();
dollarField.setLabel("Balance");
dollarField.setValue(200.0);
Div dollarPrefix = new Div();
dollarPrefix.setText("$");
dollarField.setPrefixComponent(dollarPrefix);

NumberField euroField = new NumberField();
euroField.setLabel("Balance");
euroField.setValue(200.0);
Div euroSuffix = new Div();
euroSuffix.setText("€");
euroField.setSuffixComponent(euroSuffix);

add(dollarField, euroField);

Step Buttons

Step buttons allow the user to make small adjustments, quickly.

Open in a
new tab
IntegerField adultsField = new IntegerField();
adultsField.setValue(2);
adultsField.setStepButtonsVisible(true);
adultsField.setMin(0);
adultsField.setMax(9);

Validation

Number Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation occurs typically when the user initiates a value change, for example by entering input and pressing Enter. If the value is invalid, the field is highlighted in red, and an error message appears underneath the input.

Below is a list of supported constraints with more detailed information:

Bad Input

Bad input refers to any input that cannot be parsed into a value of the field type. When an unparsable value is entered, the field resets the value to empty and becomes invalid. This constraint is non-configurable and enabled by default.

Required

Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared.

An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the --lumo-required-field-indicator style property.

Min & Max Values

The valid input range of a Number Field can be restricted by defining min and max values. Helper text can be used to inform the user about the accepted range.

Step

Refer to the Step section for more details and an example.

Allowed Characters

A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don’t match the expression are rejected. However, values set programmatically are not subject to this restriction, even if they contain disallowed characters.

The following example demonstrates how to create a quantity field using a combination of these constraints:

Open in a
new tab
IntegerField integerField = new IntegerField();
integerField.setLabel("Quantity");
integerField.setHelperText("Max 10 items");
integerField.setRequiredIndicatorVisible(true);
integerField.setMin(1);
integerField.setMax(10);
integerField.setValue(2);
integerField.setStepButtonsVisible(true);

integerField.setI18n(new IntegerFieldI18n()
        .setRequiredErrorMessage("Field is required")
        .setBadInputErrorMessage("Invalid number format")
        .setMinErrorMessage("Quantity must be at least 1")
        .setMaxErrorMessage("Maximum 10 items available"));

add(integerField);

It’s important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback.

Note
Data Binding & Custom Validation
Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding Flow and Hilla articles.

Step

The step value of a Number Field defines the numeric intervals that are allowed.

It specifies the amount by which the value increases or decreases when using the Up or Down arrow keys, or the step buttons.

It also invalidates the field if the value entered doesn’t align with the specified step.

Open in a
new tab
NumberField numberField = new NumberField();
numberField.setLabel("Duration (hours)");
numberField.setStep(0.5);
numberField.setValue(12.5);
numberField.setStepButtonsVisible(true);
numberField.setI18n(new NumberFieldI18n()
        .setBadInputErrorMessage("Invalid number format")
        .setStepErrorMessage("Duration must be a multiple of 0.5"));
add(numberField);

Number Type Variants

Integer Field

To allow only integers to be entered, you can use the Integer Field like so:

Open in a
new tab
IntegerField xField = new IntegerField();
xField.setLabel("X");
xField.setValue(-1284);

IntegerField yField = new IntegerField();
yField.setLabel("Y");
yField.setValue(3910);

add(xField, yField);

BigDecimal Field (Flow)

Flow developers who need to support the BigDecimal type can use BigDecimal Field:

Open in a
new tab
BigDecimalField bigDecimalField = new BigDecimalField();
bigDecimalField.setLabel("Result");
bigDecimalField.setWidth("240px");
bigDecimalField.setValue(new BigDecimal("948205817.472950487"));
add(bigDecimalField);

Basic Features

The following features, common to most input field components, are supported:

Label

The label is used to identify the input field. It supports plain-text content, and its length is limited to the width of the field. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.

Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby attribute. Fields without any visible label should include an invisible label for assistive technologies with the aria-label attribute.

Helper

Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.

A style variant is available for rendering the helper above the field.

In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.

Placeholder

The placeholder is text that’s displayed when the field is empty. Its primary purpose is to provide a short input hint (e.g., the expected format) in situations where a Helper cannot be used.

Placeholders should not be used as a replacement for a visible label. They can be mistaken for a manually entered value. See Label for alternatives to the built-in field label.

Tooltip

Tooltips are small text pop-ups displayed on hover, and on keyboard-focus. They can be used to provide additional information about a field. This can be useful in situations where an always visible Helper is not appropriate. Helpers are generally recommended in favor of tooltips, though, as they provide much better discoverability and mobile support. See the Tooltip documentation for more information.

Clear Button

The clear button — which is displayed when the field is not empty — clears the field’s current value. Although the button itself is not keyboard focusable, the clear action can be taken with the Esc key, when the field has focus. The clear button can be especially useful in search and filter fields, where users often need to clear the value. They’re less useful, however, in regular forms.

Prefix & Suffix

Prefix and suffix elements — rendered at either end of the field — can be used to display units, icons, and similar visual cues to the field’s purpose or format.

Prefix and suffix elements typically don’t work well with assistive technologies like screen readers. Therefore, the information communicated by them should also be conveyed through other means, such as in a Label, a Helper, or through ARIA attributes on the field itself.

External & Invisible Labels (ARIA)

Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.

<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-number-field accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-number-field accessible-name="This is the label">...
Open in a
new tab
NumberField field = new NumberField();
field.setLabel("Label");
field.setHelperText("Helper text");
field.setPlaceholder("Placeholder");
field.setTooltipText("Tooltip text");
field.setClearButtonVisible(true);
field.setPrefixComponent(new Span("$"));
field.setSuffixComponent(VaadinIcon.DOLLAR.create());

Read-Only & Disabled

Fields used to display values should be set to read-only mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.

Fields that are currently unavailable should be disabled. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.

Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.

Open in a
new tab
NumberField readonlyField = new NumberField();
readonlyField.setReadOnly(true);
readonlyField.setLabel("Read-only");
readonlyField.setValue(200.0);

NumberField disabledField = new NumberField();
disabledField.setEnabled(false);
disabledField.setLabel("Disabled");

Style Variants

The following style variants can be applied:

Text Alignment

Three different text alignments are supported: left, which is the default; center; and right.

Right-alignment is recommended for numerical values when presented in vertical groups. This tends to aid interpretation and comparison of values.

Small Variant

The small variant can be used to make individual fields more compact. The default size of fields can be customized with style properties.

Helper Above Field

The helper can be rendered above the field, and below the label.

Borders

Borders can be applied to the field surface by providing a value (e.g., 1px) to the --vaadin-input-field-border-width CSS property. This can be applied globally to all input fields using the html selector, or to individual component instances. Borders are required to achieve WCAG 2.1 level AA conformant color contrast with the default Lumo styling of fields.

You can override the default border color with the --vaadin-input-field-border-color property.

Open in a
new tab
NumberField field = new NumberField();
field.addThemeVariants(TextFieldVariant.LUMO_SMALL,
        TextFieldVariant.LUMO_ALIGN_RIGHT,
        TextFieldVariant.LUMO_HELPER_ABOVE_FIELD);
field.getStyle().set("--vaadin-input-field-border-width", "1px");

Best Practices

Number Field should be used for actual number values, such as counts and measures — values that may be part of a calculation. Don’t use it for other digit-based values, such as telephone, credit card, and social security numbers. These values can have leading zeros and be greater than Number Field’s maximum supported value.

When applicable, set the most common choice as the default value. For example, airline, bus, train and other travel companies typically set the default number of passengers to 1.

69FAE707-4778-4093-8FB9-8BAE22E9D7F6