@base-ui/react/esm/number-field/root/NumberFieldRoot.d.ts

Base UI is a library of headless ('unstyled') React components and low-level hooks. You gain complete control over your app's CSS and accessibility features.

import * as React from 'react';
import type { FieldRoot } from "../../field/root/FieldRoot.js";
import type { BaseUIComponentProps } from "../../utils/types.js";
import type { ChangeEventCustomProperties } from "../utils/types.js";
import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
import { REASONS } from "../../utils/reasons.js";
/**
 * Groups all parts of the number field and manages its state.
 * Renders a `<div>` element.
 *
 * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
 */
export declare const NumberFieldRoot: React.ForwardRefExoticComponent<Omit<NumberFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
export interface NumberFieldRootProps extends Omit<BaseUIComponentProps<'div', NumberFieldRootState>, 'onChange'> {
  /**
   * The id of the input element.
   */
  id?: string | undefined;
  /**
   * The minimum value of the input element.
   */
  min?: number | undefined;
  /**
   * The maximum value of the input element.
   */
  max?: number | undefined;
  /**
   * When true, direct text entry may be outside the `min`/`max` range without clamping,
   * so native range underflow/overflow validation can occur.
   * Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp.
   * @default false
   */
  allowOutOfRange?: boolean | undefined;
  /**
   * The small step value of the input element when incrementing while the meta key is held. Snaps
   * to multiples of this value.
   * @default 0.1
   */
  smallStep?: number | undefined;
  /**
   * Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area.
   * To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop.
   * Specify `step="any"` to always disable step validation.
   * @default 1
   */
  step?: (number | 'any') | undefined;
  /**
   * The large step value of the input element when incrementing while the shift key is held. Snaps
   * to multiples of this value.
   * @default 10
   */
  largeStep?: number | undefined;
  /**
   * Whether the user must enter a value before submitting a form.
   * @default false
   */
  required?: boolean | undefined;
  /**
   * Whether the component should ignore user interaction.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Whether the user should be unable to change the field value.
   * @default false
   */
  readOnly?: boolean | undefined;
  /**
   * Identifies the field when a form is submitted.
   */
  name?: string | undefined;
  /**
   * The raw numeric value of the field.
   */
  value?: (number | null) | undefined;
  /**
   * The uncontrolled value of the field when it’s initially rendered.
   *
   * To render a controlled number field, use the `value` prop instead.
   */
  defaultValue?: number | undefined;
  /**
   * Whether to allow the user to scrub the input value with the mouse wheel while focused and
   * hovering over the input.
   * @default false
   */
  allowWheelScrub?: boolean | undefined;
  /**
   * Whether the value should snap to the nearest step when incrementing or decrementing.
   * @default false
   */
  snapOnStep?: boolean | undefined;
  /**
   * Options to format the input value.
   */
  format?: Intl.NumberFormatOptions | undefined;
  /**
   * Callback fired when the number value changes.
   *
   * The `eventDetails.reason` indicates what triggered the change:
   * - `'input-change'` for parseable typing or programmatic text updates
   * - `'input-clear'` when the field becomes empty
   * - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur
   * - `'input-paste'` for paste interactions
   * - `'keyboard'` for keyboard input
   * - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls
   * - `'wheel'` for wheel-based scrubbing
   * - `'scrub'` for scrub area drags
   */
  onValueChange?: ((value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void) | undefined;
  /**
   * Callback function that is fired when the value is committed.
   * It runs later than `onValueChange`, when:
   * - The input is blurred after typing a value.
   * - The pointer is released after scrubbing or pressing the increment/decrement buttons.
   *
   * It runs simultaneously with `onValueChange` when interacting with the keyboard.
   *
   * **Warning**: This is a generic event not a change event.
   */
  onValueCommitted?: ((value: number | null, eventDetails: NumberFieldRoot.CommitEventDetails) => void) | undefined;
  /**
   * The locale of the input element.
   * Defaults to the user's runtime locale.
   */
  locale?: Intl.LocalesArgument | undefined;
  /**
   * A ref to access the hidden input element.
   */
  inputRef?: React.Ref<HTMLInputElement> | undefined;
}
export interface NumberFieldRootState extends FieldRoot.State {
  /**
   * The raw numeric value of the field.
   */
  value: number | null;
  /**
   * The formatted string value presented in the input element.
   */
  inputValue: string;
  /**
   * Whether the user must enter a value before submitting a form.
   */
  required: boolean;
  /**
   * Whether the component should ignore user interaction.
   */
  disabled: boolean;
  /**
   * Whether the user should be unable to change the field value.
   */
  readOnly: boolean;
  /**
   * Whether the user is currently scrubbing the field.
   */
  scrubbing: boolean;
}
export type NumberFieldRootChangeEventReason = typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.inputBlur | typeof REASONS.inputPaste | typeof REASONS.keyboard | typeof REASONS.incrementPress | typeof REASONS.decrementPress | typeof REASONS.wheel | typeof REASONS.scrub | typeof REASONS.none;
export type NumberFieldRootChangeEventDetails = BaseUIChangeEventDetails<NumberFieldRootChangeEventReason, ChangeEventCustomProperties>;
export type NumberFieldRootCommitEventReason = typeof REASONS.inputBlur | typeof REASONS.inputClear | typeof REASONS.keyboard | typeof REASONS.incrementPress | typeof REASONS.decrementPress | typeof REASONS.wheel | typeof REASONS.scrub | typeof REASONS.none;
export type NumberFieldRootCommitEventDetails = BaseUIGenericEventDetails<NumberFieldRoot.CommitEventReason>;
export declare namespace NumberFieldRoot {
  type State = NumberFieldRootState;
  type Props = NumberFieldRootProps;
  type ChangeEventReason = NumberFieldRootChangeEventReason;
  type ChangeEventDetails = NumberFieldRootChangeEventDetails;
  type CommitEventReason = NumberFieldRootCommitEventReason;
  type CommitEventDetails = NumberFieldRootCommitEventDetails;
}