@carbon/react
Version:
React components for the Carbon Design System
222 lines (221 loc) • 8.12 kB
TypeScript
/**
* Copyright IBM Corp. 2016, 2026
*
* This source code is licensed under the Apache-2.0 license found in the
* LICENSE file in the root directory of this source tree.
*/
import React, { type ReactNode } from 'react';
import type { TranslateWithId } from '../../types/common';
import { type NumberFormatOptions } from '@carbon/utilities';
declare const translationIds: {
readonly 'increment.number': "increment.number";
readonly 'decrement.number': "decrement.number";
};
type TranslationKey = keyof typeof translationIds;
type ExcludedAttributes = 'defaultValue' | 'id' | 'min' | 'max' | 'onChange' | 'onClick' | 'size' | 'step' | 'value';
export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>, TranslateWithId<TranslationKey> {
/**
* Optional validation function that is called with the input value and locale.
* This is called before other validations, giving consumers the ability
* to short-circuit or extend validation without replacing built-in rules
* @example
* // Using the built-in separator validation
* <NumberInput validate={validateNumberSeparators} />
*
* // Combining with custom validation
* <NumberInput
* validate={(value, locale) => {
* return validateNumberSeparators(value, locale) && customValidation(value)
* }}
* />
* - Return `false` to immediately fail validation.
* - Return `true` to pass this validation, but still run other checks (min, max, required, etc.).
* - Return `undefined` to defer entirely to built-in validation logic.
*
*/
validate?: (value: string, locale: string) => boolean | undefined;
/**
* `true` to allow empty string.
*/
allowEmpty?: boolean;
/**
* Specify an optional className to be applied to the wrapper node
*/
className?: string;
/**
* **Experimental**: Provide a `decorator` component to be rendered inside the
* `TextInput` component
*/
decorator?: ReactNode;
/**
* Optional starting value for uncontrolled state
* Defaults to 0 when type="number"
* Defaults to NaN when type="text"
*/
defaultValue?: number | string;
/**
* Specify if the wheel functionality for the input should be disabled, or not
*/
disableWheel?: boolean;
/**
* Specify if the control should be disabled, or not
*/
disabled?: boolean;
/**
* **Experimental:** Specify Intl.NumberFormat options applied to internal
* number parsing and formatting. Use with `type="text"`, has no effect when
* `type="number"`.
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
*/
formatOptions?: NumberFormatOptions;
/**
* Provide the value stepping should begin at when the input is empty
*/
stepStartValue?: number;
/**
* Provide text that is used alongside the control label for additional help
*/
helperText?: ReactNode;
/**
* Specify whether you want the underlying label to be visually hidden
*/
hideLabel?: boolean;
/**
* Specify whether you want the steppers to be hidden
*/
hideSteppers?: boolean;
/**
* Provide a description for up/down icons that can be read by screen readers
*/
iconDescription?: string;
/**
* Specify a custom `id` for the input
*/
id: string;
/**
* Instruct the browser which keyboard to display on mobile devices. Defaults
* to `decimal`, but note that standard numeric keyboards vary across devices
* and operating systems.
* @see https://css-tricks.com/everything-you-ever-wanted-to-know-about-inputmode/
*/
inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
/**
* Specify if the currently value is invalid.
*/
invalid?: boolean;
/**
* Message which is displayed if the value is invalid.
*/
invalidText?: ReactNode;
/**
* Generic `label` that will be used as the textual representation of what
* this field is for
*/
label?: ReactNode;
/**
* `true` to use the light version.
*
* @deprecated The `light` prop for `NumberInput` is no longer needed and has
* been deprecated in v11 in favor of the new `Layer` component. It will be
* removed in the next major release.
*/
light?: boolean;
/**
* **Experimental:** Specify a [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt)
* language code for parsing and formatting. Use with `type="text"`, has no
* effect when `type="number"`.
*/
locale?: string;
/**
* The maximum value.
*/
max?: number;
/**
* The minimum value.
*/
min?: number;
/**
* Provide an optional handler that is called when the input is blurred.
*/
onBlur?: (event: React.FocusEvent<HTMLInputElement>, value?: string | number) => void;
/**
* Provide an optional handler that is called when the stepper
* buttons are blurred.
*/
onStepperBlur?: (event: React.FocusEvent<HTMLButtonElement>) => void;
/**
* Provide an optional handler that is called when the internal state of
* NumberInput changes. This handler is called with event and state info.
* When type="number", this is called on every change of the input.
* When type="text", this is only called on blur after the number has been
* parsed and formatted.
* `(event, { value, direction }) => void`
*/
onChange?: (event: React.MouseEvent<HTMLButtonElement> | React.FocusEvent<HTMLInputElement> | React.KeyboardEvent<HTMLInputElement>, state: {
value: number | string;
direction: string;
}) => void;
/**
* Provide an optional function to be called when the up/down button is clicked
*/
onClick?: (event: React.MouseEvent<HTMLElement>, state?: {
value: number | string;
direction: string;
}) => void;
/**
* Provide an optional function to be called when a key is pressed in the number input
*/
onKeyUp?: React.KeyboardEventHandler<HTMLInputElement>;
/**
* When type="text", provide an optional pattern to restrict user input. Has
* no effect when type="number".
*/
pattern?: string;
/**
* Specify if the component should be read-only
*/
readOnly?: boolean;
/**
* Specify the size of the Number Input.
*/
size?: 'sm' | 'md' | 'lg';
/**
* @deprecated please use `decorator` instead.
* **Experimental**: Provide a `Slug` component to be rendered inside the `TextInput` component
*/
slug?: ReactNode;
/**
* Specify how much the values should increase/decrease upon clicking on up/down button
*/
step?: number;
/**
* **Experimental**: Specify if the input should be of type text or number.
* Use type="text" with `locale`, `formatOptions`, and guide user input with
* `pattern` and `inputMode`.
*/
type?: 'number' | 'text';
/**
* Specify the value of the input
*/
value?: number | string;
/**
* Specify whether the control is currently in warning state
*/
warn?: boolean;
/**
* Provide the text that is displayed when the control is in warning state
*/
warnText?: ReactNode;
}
/**
* Converts a string with any Unicode numeral system to a JavaScript number.
* Handles all numeral systems supported by Intl.NumberFormat.
*
* @param {string} input - The input string with numerals in any Unicode system
* @param {string} locale - The locale for parsing separators
* @returns {number} The parsed number, or NaN if invalid
*/
export declare const parseNumberWithLocale: (input: string, locale: string) => number;
export declare const validateNumberSeparators: (input: string, locale: string) => boolean;
declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;
export { NumberInput };