Number Field

A number field component allows users to enter and adjust numeric values.

Usage

Code

Accessibility

<sl-number-field aria-label="Number field" step-buttons="end" value="100"></sl-number-field>

The stepper control buttons allow users to increment or decrement the value is defined in steps, within a well-defined, preferably small, range. They are ideal for scenarios like adjusting product amounts, setting measurement values, or tuning numeric settings where direct typing might lead to errors.

Require Formatting Values

Number fields can display format-specific information, such as currency symbols or percentage signs, alongside the input value. This visual formatting helps users recognise the context of the data they enter, improving clarity and reducing mistakes, especially in financial or statistical inputs.

When not to use

For a Fixed Number of Options

When the selection involves a small, predefined set of numeric options, the Select component is more suitable than a number field. Select ensure quicker selection, avoid invalid entries, and streamline the user experience for limited choices.

Anatomy

Item	Name	Description	Optional
1	Input field	Area where users type the number.	No
2	Stepper controls	Field buttons to increment or decrement the value.	Yes
3	Label	Text describing the purpose of the field.	Yes
4	Helper text	Trxt that provides extra guidance.	Yes
5	Prefix	Text placed before the value.	Yes
6	Suffix	Text placed after the value.	Yes
7	Error message	Communicates validation issues.	Yes

Variants

Basic: Input field only.
Steppers: Input field plus increment/decrement controls.
Prefix or Suffix: Adds contextual information like currency or units.
Hint text: Provides additional instructions.
Validation: Shows error messages when input rules are not respected.

States

Default: Active field allowing free numerical input and adjustments.
Hover: Highlighted field indicating interactivity before clicking.
Active: Field focused and ready for user input.

Figma Options

With these options, you can tweak the appearance of the number field in Figma. They are available in the Design Panel so you can compose the tag to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Size	`md` `lg`	Size 'md' is the default size of the number field component
Variant	`Default` `Invalid` `disabled`	Indicates the state of the number field
State	`idle` `hover` `active` `disabled`	Indicates the state of the number field
Label	`value`	The text of the label
Placeholader	`value`	The text of the placeholder
Steppers	`End` `Edges`	Define the place of the stepper buttons
Imput Text	`value`	The text of the value
Focus	`On` `Off`	Shows the focus ring
Prefix	`On` `Off`	Shows the prefix of the field
Sufix	`On` `Off`	Shows the sufix of the field

Behaviours

Keyboard Input

The number field accepts direct keyboard input, allowing users to quickly enter numerical values without relying on other controls.

Stepper Controls

Users can adjust the value easily using the increment and decrement buttons, ensuring fine-grained control over numerical input.

Input Validation

The field validates user input based on minimum, maximum, and step settings to maintain consistent and valid data.

Visual Formatting

The number field can apply visual formatting, such as thousand separators, to improve readability and reduce entry errors.

Accessibility Support

Built with accessibility in mind, the number field uses ARIA roles and supports full keyboard navigation, ensuring an inclusive user experience.

Text Field: If you want a free-form text input.
Select: Selecting from predefined numeric options.

  <sl-number-field aria-label="Number field" placeholder="Type a number" value="20"></sl-number-field>

API

Number Field has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`autocomplete`	`autocomplete`	`string \| undefined`		Specifies which type of data the browser can use to pre-fill the input.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the text field is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`formatOptions`	`format-options`	`Intl.NumberFormatOptions \| undefined`		Number formatting options.
`formattedValue`	-	`string`		The formatted value, to be used as the input value.
`input`	-	`HTMLInputElement`		The input element in the light DOM.
`inputSize`	`input-size`	`number \| undefined`		The size attribute of the input element.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`locale`	`locale`	`string`		The component's locale.
`max`	`max`	`number \| undefined`	`Infinity`	The maximum value that is acceptable and valid. If the value is greater, the control will be invalid.
`maxLength`	`maxlength`	`number \| undefined`		Maximum length (number of characters).
`min`	`min`	`number \| undefined`	`-Infinity`	The minimum value that is acceptable and valid. If the value is less, the control will be invalid.
`minLength`	`minlength`	`number \| undefined`		Minimum length (number of characters).
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`pattern`	`pattern`	`string \| undefined`		This will validate the value of the input using the given pattern.
`placeholder`	`placeholder`	`string \| undefined`		Placeholder text in the input.
`rawValue`	-	`string`	`''`	The raw (string) value of the input.
`readonly`	`readonly`	`boolean \| undefined`		Whether you can interact with the input or if it is just a static, readonly display.
`required`	`required`	`boolean \| undefined`		Whether the text field is a required field.
`showValid`	`show-valid`	`boolean`	`false`	Optional property to indicate the valid state should be shown.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'md' \| 'lg' \| undefined`	`md`	The size of the input.
`step`	`step`	`number \| undefined`	`1`	The amount by which the value will be increased/decreased by a step up/down.
`stepButtons`	`step-buttons`	`'end' \| 'edges' \| undefined`		Step buttons placement for incrementing / decrementing. No step buttons by default.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`type`	`type`	`'email' \| 'number' \| 'tel' \| 'text' \| 'url' \| 'password'`	`'text'`	The input type. Only text types are valid here. For other types, see their respective components.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The text value.
`valueAsNumber`	`valueAsNumber`			The number value.

Methods

Name	Parameters	Return	Description
`stepDown`	`decrement: number`	`void`	Decreases the current value by the `step` amount.
`stepUp`	`increment: number`	`void`	Increases the current value by the `step` amount.
`onBlur`		`void`	Handles the blur event when the input field loses focus. Parses the raw value, validates the input, and updates the state.
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.
`renderPrefix`		`TemplateResult \| typeof nothing`	Renders the prefix slot; can be overridden to customize the prefix.
`renderInputSlot`		`TemplateResult`	Render the input slot; separate method so it is composable for child components.
`renderSuffix`		`TemplateResult \| typeof nothing`	Renders the suffix slot; can be overridden to customize the suffix. Remember that if you override this method, it will no longer automatically show the valid checkmark when the input is valid.
`parseValue`	`value: string`	`T \| undefined`	Method that converts the string value in the input to the specified type T. Override this method if you want to convert the value in a different way. Throw an error if the value is invalid.
`onFocus`		`void`	Handles the focus event when the input field gains focus. Emits a focus event and updates the focus ring state.
`onInput`	`{ target }: Event & { target: HTMLInputElement }`	`void`	Handles input events to update the raw and parsed values.
`onKeydown`	`event: KeyboardEvent`	`void`	Handles the `keydown` event for the text field. Simulates the native behavior of submitting a form when the Enter key is pressed.
`onPrefixSlotChange`	`event: Event & { target: HTMLSlotElement }`	`void`	Handles changes to the prefix slot. Detects and adds any `FieldButton` elements assigned to the prefix slot to the `fieldButtons` state for further processing.
`onSlotChange`	`event: Event & { target: HTMLSlotElement }`	`void`	Handles changes to the input slot. Updates the `input` element reference and synchronizes its attributes with the component's properties.
`onSuffixSlotChange`	`event: Event & { target: HTMLSlotElement }`	`void`	Handles changes to the suffix slot. Detects and adds any `FieldButton` elements assigned to the suffix slot to the `fieldButtons` state for further processing.

Events

Name	Event type	Description
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<T \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.

Slots

Name	Description
`prefix`	Content shown before the input
`input`	The slot for the input element
`suffix`	Content shown after the input

CSS Parts

Name	Description
`wrapper`	The input's wrapper

Keyboard interactions

Here's an overview of the common keyboard interactions associated with a number field:

Command	Description
Tab	When focus is outside the number field, moves focus to the input container.
Arrow up/down	Increases or decreases the value in the number field, respecting the `step` attribute if set.

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningfull value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Attribute	Value	Description
`aria-label`	string	Defines a string that tells the user what information they need to enter in this number field. Needs to be added when the number-field is not wrapped with `sl-form-field` and there is no `sl-label`.
`aria-labelledby`	string	Used to connect with single header/element that describes the number field, when there is no label component connected to.
`aria-required`	boolean	Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required. If there is already a `required` attribute added, it is recommended to avoid adding `aria-required`.
`aria-disabled`	boolean	Announces the number field component as disabled with a screen reader. See [Note 1] below.

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

disabled dims the number field visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.
aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the number field out of the navigation flow.

When disabled is added to a number field there is no need to also add aria-disabled. Everything aria-disabled does, disabled does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.

Interactive example