to_words #

A Dart port of the popular to-words JavaScript library for converting numbers (including decimals) into words with multi-locale and currency support. Ideal for invoicing, e-commerce, and financial apps.

Features #

• Number to Words: Convert integers and decimals to text.
• Currency Support: Easily handle conversions with locale-specific currency options.
• Multi-Locale: Supports multiple languages and regions.
• Highly Configurable: Tailor conversion rules to your needs.
• Written in Dart: Modern, fast, and cross-platform.
• Well-tested: Ensuring reliability and accuracy.

Use Cases #

• Financial Applications: Generate amount-in-words for invoices or cheques.
• E-commerce Platforms: Display totals in words for user receipts.
• Educational Tools: Teach number systems through text conversions.
• Localization: Support multiple languages and currencies seamlessly.

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  to_words: ^0.2.1

Then run dart pub get or flutter pub get.

Usage #

Import the library:

import 'package:to_words/to_words.dart';

The toWords function is highly configurable through the ToWordsOptions and ConverterOptions classes.

Basic Conversion #

void main() {
  // Simple number to words
  print(toWords(123));
  // > One Hundred Twenty Three

  // Number with a decimal part
  print(toWords(123.45));
  // > One Hundred Twenty Three Point Four Five

  // Decimal part starting with zero
  print(toWords(123.045));
  // > One Hundred Twenty Three Point Zero Four Five
  // Note: When the fractional part starts with zero, the digits are converted individually.

  // Negative number
  print(toWords(-123.45));
  // > Minus One Hundred Twenty Three Point Four Five
}

Currency Conversion #

To convert a number to currency words, set currency: true.

void main() {
  final currencyOptions = const ToWordsOptions(
    converterOptions: ConverterOptions(
      currency: true,
    ),
  );

  print(toWords(452, options: currencyOptions));
  // > Four Hundred Fifty Two Dollars Only

  print(toWords(452.36, options: currencyOptions));
  // > Four Hundred Fifty Two Dollars And Thirty Six Cents Only

  // Ignore the decimal part
  final ignoreDecimalOptions = const ToWordsOptions(
    converterOptions: ConverterOptions(
      currency: true,
      ignoreDecimal: true,
    ),
  );
  print(toWords(452.36, options: ignoreDecimalOptions));
  // > Four Hundred Fifty Two Dollars Only

  // Ignore the currency if it's zero
  final ignoreZeroOptions = const ToWordsOptions(
    converterOptions: ConverterOptions(
      currency: true,
      ignoreZeroCurrency: true,
    ),
  );
  print(toWords(0.57, options: ignoreZeroOptions));
  // > Fifty Seven Cents Only

  // Do not add "Only" at the end
  final noOnlyOptions = const ToWordsOptions(
    converterOptions: ConverterOptions(
      currency: true,
      doNotAddOnly: true,
    ),
  );
  print(toWords(100, options: noOnlyOptions));
  // > One Hundred Dollars
}

Locale and Custom Currency #

Specify a locale or override default currency settings.

void main() {
  // Use a different locale (example for a future implementation)
  // final ptBrOptions = const ToWordsOptions(localeCode: 'pt-BR');
  // print(toWords(13, options: ptBrOptions));
  // > Treze

  // Override default currency options for the 'en-US' locale
  final euroOptions = const ToWordsOptions(
    converterOptions: ConverterOptions(
      currency: true,
      currencyOptions: CurrencyOptions(
        name: 'Euro',
        plural: 'Euros',
        symbol: '€',
        fractionalUnit: FractionalUnit(
          name: 'Cent',
          plural: 'Cents',
          symbol: '¢',
        ),
      ),
    ),
  );
  print(toWords(123.45, options: euroOptions));
  // > One Hundred Twenty Three Euros And Forty Five Cents Only
}

Configuration Options #

Supported Locales #