sp-number-field

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Overview

<sp-number-field> elements are used for numeric inputs.

Usage

See it on NPM! How big is this package in your project? Try it on Stackblitz

yarn add @spectrum-web-components/number-field

Import the side effectful registration of <sp-number-field> via:

import '@spectrum-web-components/number-field/sp-number-field.js';

When looking to leverage the NumberField base class as a type and/or for extension purposes, do so via:

import { NumberField } from '@spectrum-web-components/number-field';

Anatomy

A number field consists of an input field for numeric values and optional stepper buttons for incrementing and decrementing the value. The stepper UI can be hidden using the hide-stepper attribute.

<sp-field-label>
    What is the air-speed velocity of an unladen swallow?
</sp-field-label>
<sp-number-field
    id="anatomy"
    format-options='{
        "style": "unit",
        "unit": "MPH",
        "unitDisplay": "long"
    }'
></sp-number-field>

Options

Sizes

Small Medium 
<sp-number-field label="Size" value="1024" size="m"></sp-number-field>
 Large Extra Large

Formatting

An <sp-number-field> element will process its numeric value with new Intl.NumberFormat(this.resolvedLanguage, this.formatOptions).format(this.value) in order to prepare it for visual delivery in the input. In order to customize this processing supply your own Intl.NumberFormatOptions via the formatOptions property, or format-options attribute as seen below.

this.resolvedLanguage represents the language in which the <sp-number-field> element is currently being delivered. By default, this value will represent the language established by the lang attribute on the root <html> element while falling back to navigator.language when that is not present. This value can be customized via a language context provided by a parent element that listens for the sp-language-context event and supplies update language settings to the callback function contained therein. Applications leveraging the <sp-theme> element to manage the visual delivery or text direction of their content will be also be provided a reactive context for supplying language information to its descendants.

Decimals

The following example uses the signDisplay option to include the plus sign for positive numbers, for example to display an offset from some value. In addition, it always displays a minimum of 1 digit after the decimal point, and allows up to 2 fraction digits. If the user enters more than 2 fraction digits, the result will be rounded.

<sp-field-label for="decimals">Adjust exposure</sp-field-label>
<sp-number-field
    id="decimals"
    value="0"
    format-options='{
        "signDisplay": "exceptZero",
        "minimumFractionDigits": 1,
        "maximumFractionDigits": 2
    }'
></sp-number-field>
 Percentages Currency values Units Custom Units Minimum and maximum values Step values

States

Invalid

The invalid attribute indicates that the number field's value is invalid. When set, appropriate ARIA attributes will be automatically applied.

<sp-field-label for="invalid">
    It's one banana, Michael, how much could it cost?
</sp-field-label>
<sp-number-field
    id="invalid"
    invalid
    style="width: 130px"
    value="10"
    min="0"
    max="0.3"
    step="0.01"
    format-options='{
        "style": "currency",
        "currency": "USD",
        "currencyDisplay": "code",
        "currencySign": "accounting",
        "minimumFractionDigits": 2,
        "maximumFractionDigits": 2
    }'
></sp-number-field>
<sp-help-text variant="negative">
    Value should be between $0 and $0.3.
</sp-help-text>

Valid

The valid attribute indicates that the number field's value is valid.

<sp-field-label for="valid">
    It's one banana, Michael, how much could it cost?
</sp-field-label>
<sp-number-field
    id="valid"
    valid
    style="width: 130px"
    value="0.23"
    min="0"
    max="0.3"
    step="0.01"
    format-options='{
        "style": "currency",
        "currency": "USD",
        "currencyDisplay": "code",
        "currencySign": "accounting",
        "minimumFractionDigits": 2,
        "maximumFractionDigits": 2
    }'
></sp-number-field>

Required

Use the required attribute to indicate a number field value is required. Dictate the validity or invalidity state of the text entry with the valid or invalid attributes.

<sp-field-label for="number-1" required>Count</sp-field-label>
<sp-number-field id="number-1" valid value="123"></sp-number-field>
<sp-field-label for="number-2" required>Size</sp-field-label>
<sp-number-field id="number-2" invalid value="152"></sp-number-field>

Disabled

The disabled attribute prevents the number field from receiving focus or events. The number field will appear faded.

<sp-field-label for="disabled" disabled>Number of tickets</sp-field-label>
<sp-number-field id="disabled" disabled value="0"></sp-number-field>

Read-only

Number fields have a readonly attribute for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed.

<sp-field-label for="readonly">Number of tickets</sp-field-label>
<sp-number-field id="readonly" readonly value="0"></sp-number-field>

Behaviors

The number field works with the following interactions:

  • the input field,
  • ArrowUp or ArrowDown keys,
  • the scroll wheel, or
  • the stepper UI, when not hidden by the hide-stepper attribute.

The input value incrementally increases or decreases by the value of the step attribute. The shift key can be used to apply steps at 10 times (or the value of the step-modifier attribute times) their normal rate.

Default value

The <sp-number-field> component doesn't manage a default value by itself. This means that consumers can set the value of the number-field as an empty string by clearing the input. If we want the number-field to reset to a default-value when the user clears the input, we can listen for the change event on the number-field component and set its value to the desired default-value if the input is empty.

<sp-field-label for="default">
    Default value of this number field is 42
</sp-field-label>
<sp-number-field id="default" value="20"></sp-number-field>

<script type="module">
    const numberField = document.querySelector('#default');

    numberField.addEventListener('change', (event) => {
        alert('change');
        const target = event.target;
        if (isNaN(target.value)) {
            target.value = '42';
        }
    });
</script>

Accessibility

Labels

Every number field must have a label that clearly describes its purpose. The label can be provided either via the label attribute or with an associated <sp-field-label> element.

Keyboard Navigation

Number fields support the following keyboard interactions:

  • ArrowUp and ArrowDown keys increment and decrement the value
  • Shift + ArrowUp or ArrowDown applies steps at 10 times (or the value of step-modifier) the normal rate
  • The scroll wheel can be used to increment and decrement the value when focused

Help Text

Consider providing help text to explain:

  • The expected format of the input
  • Any minimum or maximum values
  • The meaning of units or special formatting (e.g., currency, percentages)
  • Step increments if they differ from the default