Number Stepper

Import

import { NumberStepper } from 'heroui-native';

Anatomy

<NumberStepper>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>

• NumberStepper: Root container that manages numeric value state, and provides context to sub-components. Supports both controlled and uncontrolled modes.
• NumberStepper.DecrementButton: Pressable button that decreases the value by one step. Auto-disables at the minimum boundary. Renders a minus icon by default.
• NumberStepper.Value: Displays the current numeric value with direction-aware flip animations on change.
• NumberStepper.IncrementButton: Pressable button that increases the value by one step. Auto-disables at the maximum boundary. Renders a plus icon by default.

Usage

Basic Usage

The NumberStepper component uses compound parts to create a numeric stepper control.

<NumberStepper>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>

Custom Step

Configure the increment/decrement amount per press.

<NumberStepper defaultValue={0} step={5} minValue={0} maxValue={100}>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>

<NumberStepper defaultValue={0} step={0.5} minValue={0} maxValue={5}>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>

Disabled

Disable the entire number stepper or let boundaries auto-disable individual buttons.

<NumberStepper defaultValue={3} isDisabled>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>

Controlled

Control the value externally with value and onValueChange.

const [value, setValue] = useState(5);

<NumberStepper value={value} onValueChange={setValue} minValue={0} maxValue={20}>
  <NumberStepper.DecrementButton />
  <NumberStepper.Value />
  <NumberStepper.IncrementButton />
</NumberStepper>;

Render Function Children

Use a render function to access number stepper state for conditional rendering.

<NumberStepper
  value={quantity}
  onValueChange={setQuantity}
  minValue={1}
  maxValue={99}
>
  {({ isAtMin }) => (
    <>
      <NumberStepper.DecrementButton
        keepActiveAtBoundary
        onPress={() => {
          if (isAtMin) {
            Alert.alert('Removed', 'Item removed from cart');
          }
        }}
      >
        {isAtMin ? <TrashIcon size={16} /> : undefined}
      </NumberStepper.DecrementButton>
      <NumberStepper.Value />
      <NumberStepper.IncrementButton />
    </>
  )}
</NumberStepper>

Example

import { NumberStepper } from 'heroui-native';
import { useState } from 'react';
import { Alert, View } from 'react-native';

export default function NumberStepperExample() {
  const [quantity, setQuantity] = useState(1);

  return (
    <View className="flex-1 px-5 items-center justify-center">
      <NumberStepper
        value={quantity}
        onValueChange={setQuantity}
        minValue={1}
        maxValue={99}
      >
        {({ isAtMin }) => (
          <>
            <NumberStepper.DecrementButton
              keepActiveAtBoundary
              onPress={() => {
                if (isAtMin) {
                  Alert.alert('Removed', 'Item removed from cart');
                }
              }}
            >
              {isAtMin ? <TrashIcon size={16} /> : undefined}
            </NumberStepper.DecrementButton>
            <NumberStepper.Value />
            <NumberStepper.IncrementButton />
          </>
        )}
      </NumberStepper>
    </View>
  );
}

API Reference

NumberStepper

NumberStepperRootRenderProps

AnimationRootDisableAll

Animation configuration for the number stepper root component. Can be:

• false or "disabled": Disable only root animations
• "disable-all": Disable all animations including children
• true or undefined: Use default animations

NumberStepper.DecrementButton

NumberStepper.Value

NumberStepperValueAnimation

Animation configuration for the value component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

NumberStepperDirectionalAnimation

A single animation or a per-direction pair. Pass a plain value to use the same animation for both directions, or an object with increase/decrease keys for direction-aware control.

NumberStepper.IncrementButton

NumberStepperButtonIconProps

NumberStepperButtonAnimation

Animation configuration for button press scale effect. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

Hooks

useNumberStepper

Hook to access the number stepper root context. Must be used within a NumberStepper component.

import { useNumberStepper } from 'heroui-native';

const {
  value,
  isAtMin,
  isAtMax,
  isDisabled,
  step,
  minValue,
  maxValue,
  direction,
  decrement,
  increment,
} = useNumberStepper();

Returns