ts-numbers

A comprehensive, lightweight TypeScript library for formatting numbers, currencies, and handling numeric inputs with advanced features.

Features

Core Formatting

• 🔢 Versatile number formatting with precise control over decimal places, separators, and more
• 💰 Multiple currency support with automatic formatting
• 🌎 Internationalization with locale-specific formatting and RTL support
• 🔣 Scientific notation for large or small numbers

Specialized Formats

• 📞 Phone number formatting with various patterns
• 🌡️ Temperature units with automatic conversion (°C, °F, K)
• ⚖️ Weight units with automatic conversion (kg, g, lb, oz)
• 📏 Length units with automatic conversion (m, cm, mm, km, in, ft, yd, mi)
• ⏱️ Time formatting (12h/24h)
• 🔢 IP address formatting (IPv4/IPv6)
• 💳 Credit card number formatting

User Experience

• ⌨️ Input events with automatic formatting and validation
• 📋 Copy/paste format conversion
• 📱 Mobile-friendly with touch controls
• ♿ Accessibility improvements (ARIA attributes, screen reader support)
• 🎨 Customizable styling with themes

Advanced Features

• 🧩 Presets for common number formats
• 💾 Extended persistence (localStorage, sessionStorage)
• 🔄 History tracking with undo/redo functionality
• 📊 Style rules for dynamic formatting based on value

Installation

# npm
npm install ts-numbers

# bun
bun add ts-numbers

# pnpm
pnpm add ts-numbers

# yarn
yarn add ts-numbers

Quick Start

import { Numbers } from 'ts-numbers'

// Create a new instance on an input element
const myNum = new Numbers('#amount', {
  decimalPlaces: 2,
  currencySymbol: '$',
  digitGroupSeparator: ',',
})

// Set a value
myNum.set(1234.56) // Will display as "$1,234.56"

// Get the numeric value
const value = myNum.getNumber() // Returns 1234.56

See Usage Guide for more examples.

Configuration

ts-numbers supports extensive configuration options:

const config = {
  // Core formatting options
  decimalPlaces: 2,
  decimalCharacter: '.',
  digitGroupSeparator: ',',
  currencySymbol: '$',

  // Keyboard shortcuts
  keyboardShortcuts: {
    increment: 'Alt+ArrowUp',
    decrement: 'Alt+ArrowDown',
    toggleSign: 'Alt+-',
    clear: 'Alt+C',
  },

  // Multiple currencies
  currencies: {
    USD: { symbol: '$', placement: 'p', decimalPlaces: 2 },
    EUR: { symbol: '€', placement: 's', decimalPlaces: 2 },
    JPY: { symbol: '¥', placement: 'p', decimalPlaces: 0 }
  },

  // Specialized formatting
  useScientificNotation: true,
  scientificNotationThreshold: 1000000,

  // Localization
  locale: 'en-US',

  // Accessibility
  ariaLabel: 'Amount in dollars'
}

const myNum = new Numbers('#amount', config)

See Configuration Guide for the full list of options.

Advanced Examples

Multiple Currencies

// Configure with multiple currencies
const myNum = new Numbers('#amount', {
  currencies: {
    USD: { symbol: '$', placement: 'p', decimalPlaces: 2 },
    EUR: { symbol: '€', placement: 's', decimalPlaces: 2 },
    JPY: { symbol: '¥', placement: 'p', decimalPlaces: 0 }
  },
  activeCurrency: 'USD'
})

// Switch currency
myNum.setCurrency('EUR')

Scientific Notation

const myNum = new Numbers('#amount', {
  useScientificNotation: true,
  scientificNotationThreshold: 1000000
})

myNum.set(1234567) // Will display as "1.23e+6"

Data Persistence

const myNum = new Numbers('#amount', {
  persistenceMethod: 'localStorage',
  persistenceKey: 'user-amount'
})

For more advanced examples, see the Advanced Features section of the documentation.

Testing

Run the test suite with:

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where ts-numbers is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• Autonumeric - The original inspiration for this library

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙