Skip to content
React NativeBeta

NumberInput

Locale-aware numbers, currency and percent with − and + steppers that repeat when held.

Beta. React Native support is in beta. APIs may change or break between prereleases (npm tag native).

On this page
Web preview — real device may differ
tsx
import { useState } from "react";
import { Text } from "react-native";
import { NumberInput } from "@/component-lib/number-input";
import { useKitTheme } from "@/component-lib/shared/native";
import { Section } from "./layout"; // Section and Row: page layout for the demo
 
export function NumberInputDemo() {
  const { tokens } = useKitTheme();
  const [amount, setAmount] = useState<number | null>(1234567.5);
  return (
    <>
      <Section title="NumberInput · locales">
        <NumberInput
          label="Amount (en-IN, INR)"
          locale="en-IN"
          format="currency"
          currency="INR"
          decimals={2}
          value={amount}
          onValueChange={setAmount}
          step={100}
          clearable
        />
        <Text style={{ color: tokens.muted, fontSize: tokens.fontSize - 2 }}>Value: {String(amount)}</Text>
        <NumberInput label="Betrag (de-DE)" locale="de-DE" decimals={2} defaultValue={9876.5} />
        <NumberInput label="Discount" format="percent" step={0.05} min={0} max={1} defaultValue={0.15} />
      </Section>
 
      <Section title="NumberInput · limits and states">
        <NumberInput
          label="Quantity"
          description="1 to 10. Hold + or − to repeat."
          min={1}
          max={10}
          decimals={0}
          defaultValue={1}
          required
        />
        <NumberInput label="Weight" trailing="kg" step={0.1} defaultValue={72.5} snapToStep />
        <NumberInput label="Seats" defaultValue={4} error="Only 3 seats left." />
        <NumberInput label="Locked" defaultValue={42} readOnly />
        <NumberInput label="Disabled" defaultValue={7} disabled size="sm" />
      </Section>
    </>
  );
}

Install

npx @grampro/kit@native add NumberInput

Usage

tsx
import { NumberInput } from "@/component-lib/number-input";
 
<NumberInput label="Amount" format="currency" currency="INR" locale="en-IN" min={0} step={100} />

Props

NumberInputProps

PropTypeDescription
valuenumber | nullThe number, or null for an empty field (controlled).
defaultValuenumber | null
onValueChange(value: number | null) => voidFires with the parsed number, or null when the field is emptied.
minnumberSmallest accepted value, applied on blur by default (see clampBehavior).
maxnumberLargest accepted value, applied the same way as min.
stepnumberHow much one stepper press moves. Default 1.
largeStepnumberKept for API parity; touch has no Page Up / Page Down. Default ten steps.
snapToStepbooleanRound every committed value onto the step grid, counting from min.
decimalsnumberFraction digits to show, and to round to.
localestringBCP 47 tag deciding the separators and digits, for reading and showing.
formatNumberStyleDefault decimal. percent shows 0.45 as 45%, as Intl does.
currencystringISO 4217 code, for format="currency".
useGroupingbooleanThousands separators while the field is not being edited. Default true.
clampBehaviorClampBehaviorWhen a value outside the limits is pulled back. Default blur.
stepperbooleanThe − and + buttons. Default true.
clearablebooleanA button that empties the field.
labelReactNode
descriptionReactNode
errorReactNodeThe validation message; also marks the field invalid.
sizeNumberSizeDefault md.
leadingReactNodeBefore the number: a currency symbol, a unit.
trailingReactNodeAfter the number: a unit, a suffix.
disabledboolean
readOnlyboolean
requiredbooleanMarks the label with an asterisk.
styleStyleable<ViewStyle>
stylesPartial<{ root: Styleable<ViewStyle>; label: Styleable<TextStyle>; control: Styleable<V…
localeTextPartial<NumberInputLocaleText>

Also accepts the props of Omit< TextInputProps, "value" | "defaultValue" | "style" | "editable" | "onChangeText" | "keyboardType" | "inputMode" >.

Native and web

  • Screen readers adjust it with increment and decrement actions (role="spinbutton").
  • Uses the same Intl parsing and formatting as the web, which Hermes supports.
  • Web version: NumberInput on the web.