Number Stepper

View in Storybook

Explore interactive examples and all component variations in our Storybook.

The NumberStepper component provides an intuitive numeric input with increment and decrement buttons. Built with accessibility and precision in mind, it supports various sizes, step values, and symbol customization. Perfect for quantity selectors, price inputs, configuration settings, and any interface requiring precise numeric control.

Basic Usage

View in Storybook

Quantity

Current value: 5

Size Variants

Small (sm)

Medium (md) - Default

Large (lg)

Extra Large (xl)

Symbol Variants

Currency ($)

$

Percentage (%)

%

Weight (kg)

kg

Temperature (°C)

°C

Step Variations

Step by 1 (integers)

Step by 0.1 (decimals)

Step by 0.25 (quarters)

$

Step by 5 (multiples)

%

E-commerce Example

Product Details

Premium T-Shirt$29.99

Quantity

Total:$29.99

Disabled State

Disabled Number Stepper

%

Disabled with Currency

$

Properties

NumberStepper

Property	Type	Default	Description
value	number	-	Current value (controlled).
defaultValue	number	0	Initial value (uncontrolled).
onChange	(value: number) => void	-	Callback fired when value changes.
min	number	-Infinity	Minimum allowed value.
max	number	Infinity	Maximum allowed value.
step	number	1	Increment/decrement step size.
size	'sm' | 'md' | 'lg' | 'xl'	'md'	Size variant of the component.
disabled	boolean	false	Whether the component is disabled.
leftSymbol	string	-	Symbol displayed on the left side of input.
rightSymbol	string	-	Symbol displayed on the right side of input.
className	string	-	Additional CSS classes.

Size Specifications

Size	Button	Input Height	Icon Size
sm	32px × 32px	32px	12px
md	40px × 40px	40px	16px
lg	48px × 48px	48px	20px
xl	56px × 56px	56px	24px

Behavior

Value Management

• Controlled - Use value and onChange for external state management
• Uncontrolled - Use defaultValue for internal state management
• Validation - Values are automatically clamped to min/max bounds

Input Handling

• Direct Input - Users can type values directly into the input field
• Button Controls - Plus/minus buttons for incremental changes
• Keyboard Support - Arrow keys for increment/decrement
• Focus Behavior - Input selects all text on focus

Symbol Positioning

• Left Symbol - Positioned on the left side with appropriate padding
• Right Symbol - Positioned on the right side with appropriate padding
• Responsive - Symbol size adjusts based on component size

Accessibility

The NumberStepper component includes comprehensive accessibility features:

• Keyboard Navigation - Arrow keys, Enter, and Tab support
• Screen Reader Support - Proper ARIA labels and descriptions
• Focus Management - Clear focus indicators and logical tab order
• Button Labels - Descriptive aria-labels for increment/decrement buttons
• Value Announcements - Changes announced to screen readers
• Disabled State - Proper disabled state handling

Common Use Cases

The NumberStepper component is perfect for:

• E-commerce - Product quantity selectors and pricing
• Forms - Numeric input fields with validation
• Settings - Configuration values and preferences
• Gaming - Score inputs and game parameters
• Financial - Currency amounts and percentages
• Measurements - Weight, distance, and unit conversions
• Time/Date - Duration and interval inputs
• Inventory - Stock quantities and limits

Best Practices

1. Appropriate Steps - Choose step values that make sense for your use case
2. Clear Labels - Always provide descriptive labels for the input
3. Reasonable Bounds - Set appropriate min/max values
4. Symbol Usage - Use symbols that clearly indicate the value type
5. Size Selection - Choose sizes that fit your interface design
6. Validation - Provide clear feedback for invalid values
7. Responsive Design - Test on different screen sizes
8. Performance - Debounce onChange callbacks for expensive operations