@base-ui-components/react
Version:
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.
161 lines • 5.99 kB
TypeScript
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<NumberFieldRootProps & React.RefAttributes<HTMLDivElement>>;
export interface NumberFieldRootProps extends Omit<BaseUIComponentProps<'div', NumberFieldRootState>, 'onChange'> {
/**
* The id of the input element.
*/
id?: string;
/**
* The minimum value of the input element.
*/
min?: number;
/**
* The maximum value of the input element.
*/
max?: number;
/**
* 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;
/**
* Amount to increment and decrement with the buttons and arrow keys,
* or to scrub with pointer movement in the scrub area.
* @default 1
*/
step?: number;
/**
* 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;
/**
* Whether the user must enter a value before submitting a form.
* @default false
*/
required?: boolean;
/**
* Whether the component should ignore user interaction.
* @default false
*/
disabled?: boolean;
/**
* Whether the user should be unable to change the field value.
* @default false
*/
readOnly?: boolean;
/**
* Identifies the field when a form is submitted.
*/
name?: string;
/**
* The raw numeric value of the field.
*/
value?: number | null;
/**
* The uncontrolled value of the field when it’s initially rendered.
*
* To render a controlled number field, use the `value` prop instead.
*/
defaultValue?: number;
/**
* 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;
/**
* Whether the value should snap to the nearest step when incrementing or decrementing.
* @default false
*/
snapOnStep?: boolean;
/**
* Options to format the input value.
*/
format?: Intl.NumberFormatOptions;
/**
* 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 or clamping 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;
/**
* 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;
/**
* The locale of the input element.
* Defaults to the user's runtime locale.
*/
locale?: Intl.LocalesArgument;
/**
* A ref to access the hidden input element.
*/
inputRef?: React.Ref<HTMLInputElement>;
}
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;
}