Kewti Numerals

A lightweight Ethiopian numeral formatter and conversion component supporting traditional Ge'ez numerals (፩, ፲, ፻, ፼), Amharic words & currency (ብር / ሳንቲም) via to-words, Hindu-Arabic formatting with locale support, and standalone utility functions.

const NumeralExample = () => {
const [num, setNum] = useState(1999);
const [system, setSystem] = useState<'geez' | 'arabic' | 'words'>('words');
const [currency, setCurrency] = useState(false);

return (
  <div className="space-y-4">
    <div className="flex flex-wrap gap-3 items-center">
      <input
        type="number"
        step="0.01"
        value={num}
        onChange={(e) => setNum(Number(e.target.value))}
        className="border rounded px-3 py-1.5 w-36 bg-background"
      />
      <select
        value={system}
        onChange={(e) => setSystem(e.target.value as any)}
        className="border rounded px-3 py-1.5 bg-background text-sm"
      >
        <option value="geez">Ge'ez (፩, ፪, ፲)</option>
        <option value="words">Amharic Words</option>
        <option value="arabic">Arabic (Standard)</option>
      </select>
      <label className="flex items-center gap-1.5 text-sm cursor-pointer select-none">
        <input
          type="checkbox"
          checked={currency}
          onChange={(e) => setCurrency(e.target.checked)}
          className="rounded"
        />
        Currency (ብር)
      </label>
    </div>

    <div className="p-4 rounded border bg-card flex flex-col sm:flex-row items-baseline gap-2">
      <span className="text-sm text-muted-foreground whitespace-nowrap">Output:</span>
      <KewtiNumerals
        value={num}
        system={system}
        currency={currency}
        className="text-lg text-primary font-medium"
      />
    </div>
  </div>
);
};

render(<NumeralExample />);

Installation

npx kewti-cli add numerals

Usage

import { KewtiNumerals, toGeez, toAmharicWords } from "@/kewti/ui"
import type { KewtiNumeralsProps } from "@/kewti/ui"

Amharic Words Mode (`system="words"`)

Spells out numbers into full Amharic words using Ethiopian Fidel characters.

<KewtiNumerals value={12345} system="words" />
// Output: አስራ ሁለት ሺህ ሦስት መቶ አርባ አምስት

Amharic Currency Support (Ethiopian Birr & Santim)

Combine system="words" with currency to format values with Birr (ብር) and Santim (ሳንቲም):

<KewtiNumerals value={452.36} system="words" currency />
// Output: አራት መቶ ሃምሳ ሁለት ብር ከ ሠላሳ ስድስት ሳንቲም

Ge'ez Mode (Default)

Converts standard integer values into classical Ethiopian Ge'ez numerals following traditional base-100 grouping and multiplier rules.

<KewtiNumerals value={2024} system="geez" />
// Output: ፳፻፳፬

Arabic Mode with Locale Support

Formats numbers using standard Hindu-Arabic digits with customizable locale-based thousands separators and currency notation.

// Standard formatting
<KewtiNumerals value={1250000} system="arabic" locale="en-US" />
// Output: 1,250,000

// Localized Currency formatting (ETB)
<KewtiNumerals value={1250000} system="arabic" locale="am-ET" currency />
// Output: ETB 1,250,000.00

Standalone Utility Functions

If you need conversion results without rendering a React component, use the standalone utility functions:

1. `toAmharicWords`

Converts a number to Amharic script words with optional Birr/Santim currency formatting:

import { toAmharicWords } from "@/kewti/ui"

// Spelled-out words
const words = toAmharicWords(12345)
// "አስራ ሁለት ሺህ ሦስት መቶ አርባ አምስት"

// With Ethiopian Birr & Santim currency
const money = toAmharicWords(452.36, { currency: true })
// "አራት መቶ ሃምሳ ሁለት ብር ከ ሠላሳ ስድስት ሳንቲም"

2. `toGeez`

Converts an integer into classical Ge'ez numerals:

import { toGeez } from "@/kewti/ui"

const geezYear = toGeez(2024)   // "፳፻፳፬"
const geezLarge = toGeez(200154) // "፳፼፻፶፬"

Custom Styling

KewtiNumerals forwards all standard HTML attributes to the underlying <span> element, allowing easy styling via Tailwind CSS classes or inline style objects.

<KewtiNumerals
  value={2024}
  system="geez"
  className="text-3xl font-extrabold text-amber-600 dark:text-amber-400 font-serif tracking-wider"
  style={{ letterSpacing: "0.15em" }}
/>

Features

Amharic Fidel Spelled-out Numbers: Convert numbers directly into natural Amharic words via the to-words engine.
Ethiopian Birr Currency Formatting: Seamless support for currency breakdown into ብር (Birr) and ሳንቲም (Santim).
Authentic Ge'ez Grammar & Multipliers: Accurately formats powers of 100 (፻) and 10,000 (፼) with correct omission of leading unit prefixes (e.g., 100 converts to ፻ rather than ፩፻).
Tri-mode Conversion System: Switch seamlessly between classical Ge'ez notation (geez), spelled-out Amharic letters (words), and standard localized Arabic digits (arabic).
Non-intrusive Span Wrapper: Renders as a lightweight inline <span> element forwarding all native HTML attributes (id, aria-*, onClick, style, className).
Pure Standalone Utilities: Exports pure helper functions (toGeez, toAmharicWords) for use in non-React environments, server-side APIs, reports, or invoices.

Types

import type { ToWordsOptions } from "to-words"

export type NumeralSystem = "geez" | "arabic" | "words"

export interface KewtiNumeralsProps extends React.HTMLAttributes<HTMLSpanElement> {
  /** The numerical value to display */
  value: number
  /**
   * The numeral system to format the output in:
   * - 'geez': Classical Ge'ez numeral symbols (፩, ፪, ፲)
   * - 'words': Spelled-out words in Amharic script (አንድ ሺህ...)
   * - 'arabic': Standard Hindu-Arabic digits (1,234)
   * @default 'geez'
   */
  system?: NumeralSystem
  /**
   * Whether to format the value as currency.
   * - In 'words' mode: appends "ብር" and "ሳንቲም".
   * - In 'arabic' mode: formats using Intl.NumberFormat currency styling.
   * @default false
   */
  currency?: boolean
  /**
   * BCP 47 locale code.
   * - Defaults to 'am-ET' when system="words"
   * - Defaults to 'en-US' when system="arabic"
   */
  locale?: string
  /** Optional extra options passed directly to to-words when system="words" */
  wordOptions?: Omit<ToWordsOptions, "localeCode" | "currency">
}

Props

`KewtiNumerals` Props

Prop	Type	Default	Description
`value`	`number`	—	Required. The numerical value to convert and display.
`system`	`"geez" \| "words" \| "arabic"`	`"geez"`	The formatting system used for the output.
`currency`	`boolean`	`false`	When `true`, formats value as currency (adds ብር/ሳንቲም in `words` mode or standard currency symbols in `arabic` mode).
`locale`	`string`	`"am-ET"` / `"en-US"`	BCP 47 locale code for words or Arabic number formatting.
`wordOptions`	`Omit<ToWordsOptions, "localeCode" \| "currency">`	`undefined`	Advanced options forwarded to `to-words` when `system="words"` (e.g. `doNotAddOnly`, `ignoreDecimal`).
`className`	`string`	`""`	Optional CSS classes applied to the root `<span>` container.
`style`	`React.CSSProperties`	—	Direct inline styles applied to the root `<span>` container.
`...rest`	`React.HTMLAttributes<HTMLSpanElement>`	—	Any other standard HTML span attributes (`id`, `role`, `aria-*`, `title`, etc.).

Docs