Number Field

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

Usage

Code

Accessibility

  <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 number 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. See Intl.NumberFormat options documentation for more details.
`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 number 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.
`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
`renderPrefix`		`TemplateResult \| typeof nothing`	Renders the prefix slot content with step down button when step buttons are at edges. Remember that if you override this method, the step down button will no longer be rendered automatically when `stepButtons` is set to 'edges'. You will need to implement your own button logic if needed.
`renderSuffix`		`TemplateResult \| typeof nothing`	Renders the suffix slot content with step buttons. Remember that if you override this method, the step buttons will no longer be rendered automatically. You will need to implement your own button logic if needed.
`stepDown`	`decrement: number`	`void`	Decreases the current value by the `step` amount.
`stepUp`	`increment: number`	`void`	Increases the current value by the `step` amount.
`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.
`renderInputSlot`		`TemplateResult`	Render the input slot; separate method so it is composable for child components.
`parseValue`	`value: string`	`void`	Method that parses the string input and converts it to a specific value. Override this method if you want to convert the value in a different way. Throw an error if the value is invalid.
`onBlur`		`void`	Handles the blur event when the input field loses focus. Emits a `sl-blur` event if the component had focus and updates the state.
`onChange`		`void`	This method is called when the input changes.
`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 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<string \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.

Slots

Name	Description
`prefix`	Used for step buttons when `stepButtons` is set to 'edges'. If overridden, the step down button will not be rendered automatically, and you will need to implement your own button logic.
`suffix`	Used for step buttons internally (when `stepButtons` is set). If overridden, the step buttons will not be rendered automatically, and you will need to implement your own button logic.
`input`	The slot for the input element

Interactive example