@carbon/react
Version:
React components for the Carbon Design System
202 lines (201 loc) • 6.83 kB
TypeScript
/**
* Copyright IBM Corp. 2016, 2025
*
* 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 { TranslateWithId } from '../../types/common';
import { type NumberFormatOptions } from '@carbon/utilities';
export declare const translationIds: {
readonly 'increment.number': "increment.number";
readonly 'decrement.number': "decrement.number";
};
/**
* Message ids that will be passed to translateWithId().
*/
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> {
/**
* `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 or stepper
* buttons are blurred.
*/
onBlur?: (event: React.FocusEvent<HTMLInputElement> | 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;
}
declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;
export interface Label {
disabled?: boolean;
hideLabel?: boolean;
id?: string;
label?: ReactNode;
}
export interface HelperTextProps {
id?: string;
description?: ReactNode;
disabled?: boolean;
}
export { NumberInput };