numberfield.md

NumberField

NumberField component is a form element used to select a number while following the keyboard interactions & accessibility properties like the Native Number Input. It follows WAI-ARIA Spin Button Pattern for the keyboard interactions and accessibility features. Supports all the features as React Aria's useNumberField.

Table of Contents

• Usage
• Composition
• Props
  • NumberFieldBaseStateProps
  • NumberFieldDecrementButtonOptions
  • NumberFieldGroupOptions
  • NumberFieldIncrementButtonOptions
  • NumberFieldInputOptions
  • NumberFieldLabelOptions
  • NumberFieldStateProps

Usage

import * as React from "react";
import { useLocale } from "@react-aria/i18n";

import {
  NumberFieldDecrementButton,
  NumberFieldGroup,
  NumberFieldIncrementButton,
  NumberFieldInput,
  NumberFieldLabel,
  useNumberFieldBaseState,
  useNumberFieldState,
} from "@adaptui/react";

export const NumberFieldBasic = props => {
  let { locale } = useLocale();
  const baseState = useNumberFieldBaseState({ ...props, locale });
  const state = useNumberFieldState({ ...props, state: baseState });

  return (
    <div>
      <NumberFieldLabel state={state}>NumberField</NumberFieldLabel>
      <NumberFieldGroup state={state}>
        <NumberFieldDecrementButton state={state}>-</NumberFieldDecrementButton>
        <NumberFieldInput state={state} />
        <NumberFieldIncrementButton state={state}>+</NumberFieldIncrementButton>
      </NumberFieldGroup>
    </div>
  );
};

export default NumberFieldBasic;

Composition

• useNumberFieldBaseState uses useNumberFieldState
• NumberFieldDecrementButton uses Role
• NumberFieldGroup uses Role
• NumberFieldIncrementButton uses Role
• NumberFieldInput uses Role
• NumberFieldLabel uses Role
• useNumberFieldState uses its own state

Props

NumberFieldBaseStateProps

Name	Type	Description
locale	string	The locale that should be used for parsing.

NumberFieldStateProps props

> These props are returned by the other props You can also provide these props.

Name	Type	Description
formatOptions	NumberFormatOptions | undefined	Formatting options for the value displayed in the number field.This also affects what characters are allowed to be typed by the user.
isDisabled	boolean | undefined	Whether the input is disabled.
isReadOnly	boolean | undefined	Whether the input can be selected but not changed by the user.
validationState	ValidationState | undefined	Whether the input should display its "valid" or "invalid" visual styling.
isRequired	boolean | undefined	Whether user input is required on the input before form submission.Often paired with the necessityIndicator prop to add a visual indicator to the input.
autoFocus	boolean | undefined	Whether the element should receive focus on render.
onFocus	((e: FocusEvent<Element, Element>) => void) | u...	Handler that is called when the element receives focus.
onBlur	((e: FocusEvent<Element, Element>) => void) | u...	Handler that is called when the element loses focus.
onFocusChange	((isFocused: boolean) => void) | undefined	Handler that is called when the element's focus status changes.
onKeyDown	((e: KeyboardEvent) => void) | undefined	Handler that is called when a key is pressed.
onKeyUp	((e: KeyboardEvent) => void) | undefined	Handler that is called when a key is released.
placeholder	string | undefined	Temporary text that occupies the text input when it is empty.
value	T | undefined	The current value (controlled).
defaultValue	T | undefined	The default value (uncontrolled).
onChange	((value: C) => void) | undefined	Handler that is called when the value changes.
minValue	T | undefined	The smallest value allowed for the input.
maxValue	T | undefined	The largest value allowed for the input.
step	T | undefined	The amount that the input value changes with each increment or decrement "tick".
label	ReactNode	The content to display as the label.
description	ReactNode	A description for the field. Provides a hint such as specific requirements for what to choose.
errorMessage	ReactNode	An error message for the field.

NumberFieldDecrementButtonOptions

Name	Type	Description
state	NumberFieldState	Object returned by the useNumberFieldState hook.

NumberFieldGroupOptions

Name	Type	Description
state	NumberFieldState	Object returned by the useNumberFieldState hook.

NumberFieldIncrementButtonOptions

Name	Type	Description
state	NumberFieldState	Object returned by the useNumberFieldState hook.

NumberFieldInputOptions

Name	Type	Description
state	NumberFieldState	Object returned by the useNumberFieldState hook.

NumberFieldLabelOptions

Name	Type	Description
state	NumberFieldState	Object returned by the useNumberFieldState hook.

NumberFieldStateProps

Name	Type	Description
decrementAriaLabel	string | undefined	A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.
incrementAriaLabel	string | undefined	A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.
id	string | undefined	The element's unique identifier. See MDN.
aria-label	string | undefined	Defines a string value that labels the current element.
aria-labelledby	string | undefined	Identifies the element (or elements) that labels the current element.
aria-describedby	string | undefined	Identifies the element (or elements) that describes the object.
aria-details	string | undefined	Identifies the element (or elements) that provide a detailed, extended description for the object.
onCopy	ClipboardEventHandler<HTMLInputElement> | undef...	Handler that is called when the user copies text. See MDN.
onCut	ClipboardEventHandler<HTMLInputElement> | undef...	Handler that is called when the user cuts text. See MDN.
onPaste	ClipboardEventHandler<HTMLInputElement> | undef...	Handler that is called when the user pastes text. See MDN.
onCompositionStart	CompositionEventHandler<HTMLInputElement> | und...	Handler that is called when a text composition system starts a new text composition session. See MDN.
onCompositionEnd	CompositionEventHandler<HTMLInputElement> | und...	Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.
onCompositionUpdate	CompositionEventHandler<HTMLInputElement> | und...	Handler that is called when a new character is received in the current text composition session. See MDN.
onSelect	ReactEventHandler<HTMLInputElement> | undefined	Handler that is called when text in the input is selected. See MDN.
onBeforeInput	FormEventHandler<HTMLInputElement> | undefined	Handler that is called when the input value is about to be modified. See MDN.
onInput	FormEventHandler<HTMLInputElement> | undefined	Handler that is called when the input value is modified. See MDN.
state	NumberFieldState	Object returned by the useNumberFieldBaseState hook.