## NumberInput Use NumberInput to provide a field for entering numbers in your app with ability to set min, max and step. Category: Inputs ### Introduction ### Value Type The `value` prop in `NumberInput` can be either a string or a number. Generally, if the `value` can be represented as a number (e.g., 55, 1.28, -100), it will be treated as a number. However, there are specific cases where the value cannot be represented as a number and is instead treated as a string: - Empty State: An empty state is represented as an empty string (`''`). **To clear the value in a callback, use `''` instead of `None`.** - Exceeding Safe Integer Limits: If the number is larger than [Number.MAX_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) or smaller than [Number.MIN_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER), it will be represented as a string (e.g., '90071992547409910'). - Multiple Zeros: Numbers that consist only of zeros or have trailing zeros are represented as strings (e.g., '0.', '0.0', '-0.00', etc.). ### min and max Set `min` and `max` props to limit the input value: ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Enter value between 10 and 20", min=10, max=20, w=250, ) ``` ### Clamp behavior By default, the `value` is clamped when the input is blurred. If you set `clampBehavior="strict"`, it will not be possible to enter value outside of min/max range. Note that this option may cause issues if you have tight `min` and `max`, for example `min=10` and `max=20`. If you need to disable value clamping entirely, set `clampBehavior="none"`. ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="You cannot enter number less than 0 or greater than 100", placeholder="You cannot enter number less than 0 or greater than 100", clampBehavior="strict", min=0, max=100, w=450, ) ``` ### Prefix and suffix Set `prefix` and `suffix` props to add given string to the start or end of the input value: ```python import dash_mantine_components as dmc component = dmc.Stack([ dmc.NumberInput( label="With prefix", placeholder="Dollars", prefix="$", value=100, w=250, mb="md" ), dmc.NumberInput( label="With suffix", placeholder="Percent", suffix="%", value=100, w=250, mt="md" ), ]) ``` ### Negative numbers By default, negative numbers are allowed. Set `allowNegative=False` to allow only positive numbers. ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Negative numbers are not allowed", placeholder="Do not enter negative numbers", allowNegative=False, w=300, ) ``` ### Decimal numbers By default, decimal numbers are allowed. Set `allowDecimal=False` to allow only integers. ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Decimal numbers are not allowed", placeholder="Do not enter decimal numbers", allowDecimal=False, w=250, ) ``` ### Decimal scale `decimalScale` controls how many decimal places are allowed: ```python import dash_mantine_components as dmc component = dmc.Stack([ dmc.NumberInput( label="You can enter only 2 digits after decimal point", placeholder="Do not enter more than 2 decimals", decimalScale=2, w=250, mb="md" ), dmc.NumberInput( label="Number input with decimal steps", value=0.05, decimalScale=2, min=-1, step=0.05, max=1, w=250, mt="md" ) ]) ``` ### Fixed decimal scale Set `fixedDecimalScale=True` to always display fixed number of decimal places: ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Always show 2 digits after decimal point", placeholder="Do not enter more than 2", decimalScale=2, fixedDecimalScale=True, value=2.2, w=250, ) ``` ### Decimal separator Set `decimalSeparator` to change decimal separator character: ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Custom decimal separator", decimalSeparator=",", value=20.234, w=250, ) ``` ### Thousand separator Set `thousandSeparator` prop to separate thousands with a character. You can control grouping logic with `thousandsGroupStyle`, it accepts: `thousand`, `lakh`, `wan`, `none` values. ```python import dash_mantine_components as dmc component = dmc.Stack([ dmc.NumberInput( label="Thousands are separated with a comma", placeholder="Thousands are separated with a comma", thousandSeparator=",", value=1_000_000, w=400 ), dmc.NumberInput( label="Thousands are separated with a space", placeholder="Thousands are separated with a space", thousandSeparator=" ", value=1_000_000, mt="md", w=400 ) ]) ``` ### Left and right sections You can use DashIconify to add icon to the NumberInput. `NumberInput` supports `leftSection` and `rightSection` props. These sections are rendered with absolute position inside the input wrapper. You can use them to display icons, input controls or any other elements. You can use the following props to control sections styles and content: - `rightSection/leftSection` – components to render on the corresponding side of input - `rightSectionWidth/leftSectionWidth` – controls width of the right section and padding on the corresponding side of the input. By default, it is controlled by component size prop. - `rightSectionPointerEvents/leftSectionPointerEvents` – controls pointer-events property of the section. If you want to render a non-interactive element, set it to none to pass clicks through to the input. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify component = dmc.Stack([ dmc.NumberInput( label="With left section", description="From 0 to infinity, in steps of 5", value=5, min=0, step=5, leftSection=DashIconify(icon="fa6-solid:weight-scale"), w=250, ), dmc.NumberInput( label="With right section", description="From 0 to infinity, in steps of 5", value=5, min=0, step=5, rightSection=DashIconify(icon="fa6-solid:weight-scale"), w=250, ) ]) ``` ### Increment/decrement on hold Set `stepHoldDelay` and `stepHoldInterval` props to define behavior when increment/decrement controls are clicked and held. ```python import dash_mantine_components as dmc component = dmc.NumberInput( label="Step on hold", description="Step the value when clicking and holding the arrows", stepHoldDelay=500, stepHoldInterval=100, value=0, w=250, ) ``` ### Remove controls Controls are not rendered in these cases: - `hideControls` prop is set to `True` - Input is disabled - `variant` prop is set to "unstyled" ```python import dash_mantine_components as dmc component = dmc.Stack( [ dmc.NumberInput(label="By default controls are visible", w=250), dmc.NumberInput( label="Hide controls", hideControls=True, w=250 ), dmc.NumberInput( label="Disabled and hide controls", disabled=True, hideControls=True, w=250, ), ] ) ``` ### Disabled state ```python import dash_mantine_components as dmc component = dmc.NumberInput(disabled=True, label="Disabled input", placeholder="Disabled input", p="lg"), ``` ### Styles API This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information. #### NumberInput Selectors | Selector | Static selector | Description | |-------------|--------------------------------|--------------------------------------------------| | wrapper | .mantine-NumberInput-wrapper | Root element of the Input | | input | .mantine-NumberInput-input | Input element | | section | .mantine-NumberInput-section | Left and right sections | | root | .mantine-NumberInput-root | Root element | | label | .mantine-NumberInput-label | Label element | | required | .mantine-NumberInput-required | Required asterisk element, rendered inside label | | description | .mantine-NumberInput-description | Description element | | error | .mantine-NumberInput-error | Error element | | controls | .mantine-NumberInput-controls | Increment and decrement buttons wrapper | | control | .mantine-NumberInput-control | Increment and decrement buttons | #### NumberInput CSS Variables | Selector | Variable | Description | |-----------|----------------------|---------------------------------------------| | controls | --ni-chevron-size | Controls width and height of the chevron icon | #### NumberInput Data Attributes | Selector | Attribute | Value | |----------|------------------|-------------------------------------| | control | data-direction | "up" or "down" depending on control | ### Keyword Arguments #### NumberInput - id (string; optional): Unique ID to identify this component in Dash callbacks. - allowDecimal (boolean; optional): Determines whether decimal values are allowed, `True` by default. - allowLeadingZeros (boolean; optional): Determines whether leading zeros are allowed. If not set, leading zeros are removed when the input is blurred. `False` by default. - allowNegative (boolean; optional): Determines whether negative values are allowed, `True` by default. - allowedDecimalSeparators (list of strings; optional): Characters which when pressed result in a decimal separator, `['.']` by default. - aria-* (string; optional): Wild card aria attributes. - attributes (boolean | number | string | dict | list; optional): Passes attributes to inner elements of a component. See Styles API docs. - autoComplete (string; default 'off'): (string; default "off") Enables the browser to attempt autocompletion based on user history. For more information, see: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete. - clampBehavior (a value equal to: 'none', 'strict', 'blur'; optional): Controls how value is clamped, `strict` – user is not allowed to enter values that are not in `[min, max]` range, `blur` – user is allowed to enter any values, but the value is clamped when the input loses focus (default behavior), `none` – lifts all restrictions, `[min, max]` range is applied only for controls and up/down keys. - className (string; optional): Class added to the root element, if applicable. - classNames (dict; optional): Adds custom CSS class names to inner elements of a component. See Styles API docs. - darkHidden (boolean; optional): Determines whether component should be hidden in dark color scheme with `display: none`. - data-* (string; optional): Wild card data attributes. - debounce (number | boolean; default False): (boolean | number; default False): If True, changes to input will be sent back to the Dash server only on enter or when losing focus. If it's False, it will send the value back on every change. If a number, it will not send anything back to the Dash server until the user has stopped typing for that number of milliseconds. - decimalScale (number; optional): Limits the number of digits that can be entered after the decimal point. - decimalSeparator (string; optional): Character used as a decimal separator, `'.'` by default. - description (a list of or a singular dash component, string or number; optional): Contents of `Input.Description` component. If not set, description is not rendered. - descriptionProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Description` component. - disabled (boolean; optional): Sets disabled attribute on the input element. - error (a list of or a singular dash component, string or number; optional): Contents of `Input.Error` component. If not set, error is not rendered. - errorProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Error` component. - fixedDecimalScale (boolean; optional): If set, 0s are added after `decimalSeparator` to match given `decimalScale`. `False` by default. - hiddenFrom (string; optional): Breakpoint above which the component is hidden with `display: none`. - hideControls (boolean; optional): Determines whether the up/down controls should be hidden, `False` by default. - inputProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input` component. - inputWrapperOrder (list of a value equal to: 'label', 'input', 'description', 'error's; optional): Controls order of the elements, `['label', 'description', 'input', 'error']` by default. - label (a list of or a singular dash component, string or number; optional): Contents of `Input.Label` component. If not set, label is not rendered. - labelProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the `Input.Label` component. - leftSection (a list of or a singular dash component, string or number; optional): Content section rendered on the left side of the input. - leftSectionPointerEvents (a value equal to: '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'none', 'auto', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional): Sets `pointer-events` styles on the `leftSection` element, `'none'` by default. - leftSectionProps (dict; optional): Props passed down to the `leftSection` element. - leftSectionWidth (string | number; optional): Left section width, used to set `width` of the section and input `padding-left`, by default equals to the input height. - lightHidden (boolean; optional): Determines whether component should be hidden in light color scheme with `display: none`. - loading_state (dict; optional): Object that holds the loading state object coming from dash-renderer. For use with dash<3. `loading_state` is a dict with keys: - max (number; optional): Maximum possible value. - min (number; optional): Minimum possible value. - mod (string | dict | list of string | dicts; optional): Element modifiers transformed into `data-` attributes. For example: "xl" or {"data-size": "xl"}. Can also be a list of strings or dicts for multiple modifiers. Falsy values are removed. - n_blur (number; default 0): An integer that represents the number of times that this element has lost focus. - n_submit (number; default 0): An integer that represents the number of times that this element has been submitted. - name (string; optional): Name prop. - persisted_props (list of strings; optional): Properties whose user interactions will persist after refreshing the component or the page. Since only `value` is allowed this prop can normally be ignored. - persistence (string | number | boolean; optional): Used to allow user interactions in this component to be persisted when the component - or the page - is refreshed. If `persisted` is truthy and hasn't changed from its previous value, a `value` that the user has changed while using the app will keep that change, as long as the new `value` also matches what was given originally. Used in conjunction with `persistence_type`. Note: The component must have an `id` for persistence to work. - persistence_type (a value equal to: 'local', 'session', 'memory'; optional): Where persisted user changes will be stored: memory: only kept in memory, reset on page refresh. local: window.localStorage, data is kept after the browser quit. session: window.sessionStorage, data is cleared once the browser quit. - placeholder (string; optional): Placeholder. - pointer (boolean; optional): Determines whether the input should have `cursor: pointer` style, `False` by default. - prefix (string; optional): Prefix added before the input value. - radius (number; optional): Key of `theme.radius` or any valid CSS value to set `border-radius`, numbers are converted to rem, `theme.defaultRadius` by default. - readOnly (boolean; optional): Readonly. - required (boolean; optional): Adds required attribute to the input and a red asterisk on the right side of label, `False` by default. - rightSection (a list of or a singular dash component, string or number; optional): Content section rendered on the right side of the input. - rightSectionPointerEvents (a value equal to: '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'none', 'auto', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional): Sets `pointer-events` styles on the `rightSection` element, `'none'` by default. - rightSectionProps (dict; optional): Props passed down to the `rightSection` element. - rightSectionWidth (string | number; optional): Right section width, used to set `width` of the section and input `padding-right`, by default equals to the input height. - size (optional): Controls input `height` and horizontal `padding`, `'sm'` by default. - startValue (number; optional): Value set to the input when increment/decrement buttons are clicked or up/down arrows pressed if the input is empty, `0` by default. - step (number; optional): Number by which value will be incremented/decremented with up/down controls and keyboard arrows, `1` by default. - stepHoldDelay (number; optional): Initial delay in milliseconds before stepping the value. - stepHoldInterval (number; optional): Delay before stepping the value. Can be a number of milliseconds or a function that receives the current step count and returns the delay in milliseconds. - styles (boolean | number | string | dict | list; optional): Adds inline styles directly to inner elements of a component. See Styles API docs. - suffix (string; optional): Suffix added after the input value. - tabIndex (number; optional): tab-index. - thousandSeparator (string | boolean; optional): A character used to separate thousands. - thousandsGroupStyle (a value equal to: 'none', 'thousand', 'lakh', 'wan'; optional): Defines the thousand grouping style. - type (a value equal to: 'text', 'tel', 'password'; optional): Controls input `type` attribute, `'text'` by default. - value (string | number; optional): Controlled component value. - valueIsNumericString (boolean; optional): If value is passed as string representation of numbers (unformatted) and number is used in any format props like in prefix or suffix in numeric format and format prop in pattern format then this should be passed as `True`. `False` by default. - variant (string; optional): variant. - visibleFrom (string; optional): Breakpoint below which the component is hidden with `display: none`. - withAsterisk (boolean; optional): Determines whether the required asterisk should be displayed. Overrides `required` prop. Does not add required attribute to the input. `False` by default. - withErrorStyles (boolean; optional): Determines whether the input should have red border and red text color when the `error` prop is set, `True` by default. - wrapperProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Props passed down to the root element.