💰 React Native Currency Number Pad

A highly customizable, TypeScript-ready currency input component for React Native with decimal precision, validation, and smooth animations.

✨ Features

• 🎯 Decimal precision handling with automatic formatting
• 💱 Multi-currency support with customizable symbols
• ✅ Built-in validation (min/max amounts, custom validators)
• 🎨 Fully customizable styling and theming
• 📱 Cross-platform (iOS & Android)
• 🔢 Smart number formatting with comma separators
• ⚡ Performance optimized with React.memo and useCallback
• 🎭 Smooth animations using React Native's Animated API
• 🧪 Test-friendly with comprehensive testID support
• 📝 TypeScript first with full type safety
• ♿ Accessibility ready with proper font scaling

🚀 Installation

Option 1: Direct Integration (Recommended)

Copy the component files directly into your project:

# No additional dependencies required!
# Just copy the component files to your project

Option 2: As NPM Package

npm install react-native-currency-numpad
# or
yarn add react-native-currency-numpad

📋 Requirements

• React Native 0.60+
• React 16.8+
• TypeScript (optional but recommended)

No additional native dependencies required! This package uses only React Native's built-in APIs.

🎯 Quick Start

import React from 'react';
import { SafeAreaView } from 'react-native';
import CurrencyNumberPad from './src/components/CurrencyNumberPad';

const App = () => {
  const handleValueChange = (value: string, numericValue: number) => {
    console.log('Formatted:', value, 'Numeric:', numericValue);
  };

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <CurrencyNumberPad
        currency="$"
        maxAmount={10000}
        onValueChange={handleValueChange}
      />
    </SafeAreaView>
  );
};

export default App;

📖 API Reference

Props

| Prop | Type | Default | Description | | ----------------- | ----------------------------------------------- | ------------ | ----------------------------- | | currency | string | "$" | Currency symbol to display | | initialValue | string | "0.00" | Initial amount value | | maxAmount | number | undefined | Maximum allowed amount | | minAmount | number | undefined | Minimum allowed amount | | maxWholeDigits | number | 6 | Maximum digits before decimal | | showCursor | boolean | true | Show blinking cursor | | disabled | boolean | false | Disable the input | | onValueChange | (value: string, numericValue: number) => void | Required | Called when value changes | | onError | (error: string) => void | undefined | Called when validation fails | | customValidator | (value: number) => string \| null | undefined | Custom validation function |

Styling Props

| Prop | Type | Description | | ------------------- | ----------- | ----------------------------- | | containerStyle | ViewStyle | Main container styling | | displayStyle | ViewStyle | Currency display area styling | | numpadStyle | ViewStyle | Number pad container styling | | buttonStyle | ViewStyle | Individual button styling | | currencyTextStyle | TextStyle | Currency symbol text styling | | amountTextStyle | TextStyle | Amount text styling |

Error Messages

| Prop | Type | Description | | ------------------------- | -------- | ------------------------------ | | errorMessages | object | Custom error message overrides | | errorMessages.maxAmount | string | Max amount error message | | errorMessages.minAmount | string | Min amount error message |

🎨 Customization Examples

Basic Styling

<CurrencyNumberPad
  currency="PKR"
  containerStyle={{ backgroundColor: '#f0f0f0' }}
  displayStyle={{
    backgroundColor: '#ffffff',
    borderRadius: 12,
    marginHorizontal: 20,
    padding: 15
  }}
  currencyTextStyle={{
    color: '#007AFF',
    fontSize: 28,
    fontWeight: 'bold'
  }}
  amountTextStyle={{
    color: '#333',
    fontSize: 28
  }}
  onValueChange={handleValueChange}
/>

Advanced Configuration

<CurrencyNumberPad
  currency="€"
  initialValue="0.00"
  maxAmount={50000}
  minAmount={10}
  maxWholeDigits={5}

  // Custom validation
  customValidator={(value) => {
    if (value > 0 && value < 5) {
      return 'Amount must be at least €5.00';
    }
    if (value % 5 !== 0) {
      return 'Amount must be multiple of 5';
    }
    return null;
  }}

  // Custom error messages
  errorMessages={{
    maxAmount: 'Maximum limit of €50,000 exceeded!',
    minAmount: 'Please enter at least €10.00',
  }}

  // Event handlers
  onValueChange={(value, numericValue) => {
    setAmount(value);
    console.log('Euro amount:', numericValue);
  }}

  onError={(error) => {
    setErrorMessage(error);
  }}

  // Custom styling
  numpadStyle={{ gap: 15 }}
  buttonStyle={{
    backgroundColor: '#007AFF',
    borderColor: '#005bb5',
    borderRadius: 12,
  }}

  testID="euro-currency-pad"
/>

Dark Theme Example

<CurrencyNumberPad
  currency="$"
  containerStyle={{ backgroundColor: '#1a1a1a' }}
  displayStyle={{ backgroundColor: '#2a2a2a' }}
  currencyTextStyle={{ color: '#ffffff' }}
  amountTextStyle={{ color: '#ffffff' }}
  buttonStyle={{
    backgroundColor: '#333333',
    borderColor: '#555555',
  }}
  onValueChange={handleValueChange}
/>

🏗️ Project Structure

src/components/CurrencyNumberPad/
├── index.ts                    # Main exports
├── types/
│   └── index.ts               # TypeScript interfaces
├── components/
│   ├── CurrencyNumberPad.tsx  # Main component
│   ├── CurrencyDisplay.tsx    # Display with cursor
│   └── NumPad.tsx            # Number pad buttons
├── hooks/
│   └── useCurrencyInput.ts   # Input logic hook
└── utils/
    └── formatters.ts         # Formatting utilities

🧪 Testing

The component includes comprehensive testID support:

// Main component
testID = 'currency-numpad';

// Error display
testID = 'currency-numpad-error';

// Individual buttons automatically get testIDs

Jest Testing Example

import { render, fireEvent } from '@testing-library/react-native';
import CurrencyNumberPad from './CurrencyNumberPad';

test('should format currency correctly', () => {
  const mockOnValueChange = jest.fn();

  const { getByTestId } = render(
    <CurrencyNumberPad
      currency="$"
      onValueChange={mockOnValueChange}
      testID="test-numpad"
    />
  );

  // Test number input
  fireEvent.press(getByTestId('test-numpad').findByText('1'));
  fireEvent.press(getByTestId('test-numpad').findByText('2'));

  expect(mockOnValueChange).toHaveBeenCalledWith('12.00', 12);
});

🚨 Common Issues & Solutions

Issue: Animation not working

Solution: Make sure you're not using any conflicting animation libraries.

Issue: Cursor not blinking

Solution: Ensure showCursor={true} is set and the component is properly mounted.

Issue: Formatting issues

Solution: Check that your initialValue is properly formatted (e.g., "0.00").

Issue: TypeScript errors

Solution: Ensure you're importing types correctly:

import type { CurrencyNumberPadProps } from './types';

🎯 Best Practices

1. Always handle errors: Implement onError callback for better UX
2. Use custom validation: Implement business logic with customValidator
3. Test on both platforms: Ensure consistent behavior on iOS and Android
4. Accessibility: Test with screen readers and font scaling
5. Performance: Use React.memo for parent components if re-rendering frequently

🔄 Migration Guide

From Version 1.x to 2.x

// Old API
<CurrencyInput onAmountChange={handleChange} />

// New API
<CurrencyNumberPad onValueChange={(value, numeric) => handleChange(numeric)} />

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/your-username/react-native-currency-numpad.git
cd react-native-currency-numpad
yarn install

# Run tests
yarn test

# Run linter
yarn lint

# Build TypeScript
yarn build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by financial apps requiring precise currency input
• Built with modern React Native best practices
• TypeScript-first approach for better developer experience

Made with ❤️ for the React Native community

Author

👤 Hamza Gulraiz

📬 Support me