# dirham

> UAE Dirham (د.إ) currency symbol as a web font, CSS, React component, and Web Component for Vue, Angular, Svelte & vanilla JS — built on the official Unicode 18.0 codepoint U+20C3.

## Overview

The `dirham` npm package provides the UAE Dirham currency symbol (U+20C3) for use in web applications. It ships a custom web font, CSS, SCSS, React components, framework-agnostic Web Components (`<dirham-symbol>` and `<dirham-price>`), and JavaScript/TypeScript utilities for formatting and parsing Dirham amounts. The Web Components work natively in Vue, Angular, Svelte, and any JavaScript framework — no wrappers needed.

The glyph is sourced from the Central Bank of UAE and mapped to the official Unicode 18.0 codepoint U+20C3 (UAE DIRHAM SIGN), approved by the Unicode Technical Committee on 2025-Jul-22. When OS/browser fonts adopt Unicode 18.0 (expected September 2026), the web font gracefully becomes unnecessary with zero migration needed.

## Links

- Live Demo: https://dirham.js.org/
- npm: https://www.npmjs.com/package/dirham
- GitHub: https://github.com/pooyagolchian/dirham
- License: MIT

## Installation

```bash
npm install dirham
pnpm add dirham
yarn add dirham
```

## Package Exports

| Subpath | Description |
|---|---|
| `dirham` | Core JS/TS utilities (formatDirham, parseDirham, copyDirhamSymbol, copyDirhamAmount, VAT helpers, conversion, constants) |
| `dirham/react` | React components (DirhamSymbol, DirhamIcon, DirhamPrice, AnimatedDirhamPrice, DirhamInput, useDirhamRate) |
| `dirham/react-native` | React Native components (DirhamSymbol, DirhamPrice) — requires react-native-svg |
| `dirham/web-component` | Framework-agnostic `<dirham-symbol>`, `<dirham-price>`, `<dirham-animated-price>`, `<dirham-input>` custom elements |
| `dirham/tailwind` | Tailwind CSS plugin with utility classes (dirham-bold, dirham-sm, etc.) |
| `dirham/next` | Next.js font optimization (dirhamFont, dirhamFontConfig) |
| `dirham/css` | CSS with @font-face for the Dirham web font |
| `dirham/scss` | SCSS with @font-face for the Dirham web font |
| `dirham/font/woff2` | WOFF2 font file |
| `dirham/font/woff` | WOFF font file |
| `dirham/font/ttf` | TTF font file |
| `dirham/font/sans/woff2` | Sans-serif variant WOFF2 |
| `dirham/font/serif/woff2` | Serif variant WOFF2 |
| `dirham/font/mono/woff2` | Monospace variant WOFF2 |
| `dirham/font/arabic/woff2` | Arabic variant WOFF2 |

## React Components

### DirhamSymbol (Recommended)

Zero-config, SSR-safe, tree-shakeable SVG component. No font loading required.

```tsx
import { DirhamSymbol } from "dirham/react";
<DirhamSymbol size={16} color="currentColor" weight="regular" />
```

Props:
- `size`: number | string (default: 24) — width & height in px or CSS unit
- `color`: string (default: "currentColor") — fill color
- `weight`: DirhamWeight (default: "regular") — visual weight
- `aria-label`: string (default: "UAE Dirham") — accessible label

Weight values: thin, extralight, light, regular, medium, semibold, bold, extrabold, black

### DirhamPrice

All-in-one price display component. Renders the SVG symbol inline with a formatted amount.

```tsx
import { DirhamPrice } from "dirham/react";
<DirhamPrice amount={1234.5} />
<DirhamPrice amount={5000000} notation="compact" />
<DirhamPrice amount={99.9} decimals={0} useCode />
```

Props:
- `amount`: number (required) — the numeric value to display
- `locale`: string (default: "en-AE") — locale for number formatting
- `decimals`: number (default: 2) — decimal places
- `useCode`: boolean (default: false) — show "AED" text instead of symbol
- `notation`: "standard" | "compact" (default: "standard") — compact shows K/M/B
- `symbolSize`: number | string (default: "0.75em") — size of the inline symbol
- `weight`: DirhamWeight (default: "regular") — symbol weight

### AnimatedDirhamPrice

Animated count-up/count-down price display using requestAnimationFrame.

```tsx
import { AnimatedDirhamPrice } from "dirham/react";
<AnimatedDirhamPrice amount={1250} />
<AnimatedDirhamPrice amount={5000} duration={800} easing="easeInOut" />
```

Props:
- `amount`: number (required) — target value to animate to
- `duration`: number (default: 600) — animation duration in ms
- `easing`: "linear" | "easeIn" | "easeOut" | "easeInOut" (default: "easeOut")
- `locale`, `decimals`, `useCode`, `notation`, `symbolSize`, `weight` — same as DirhamPrice

### DirhamInput

Masked currency input with auto-formatting. Supports controlled and uncontrolled modes.

```tsx
import { DirhamInput } from "dirham/react";
<DirhamInput defaultValue={100} onChange={(v) => console.log(v)} />
<DirhamInput value={amount} onChange={setAmount} min={0} max={999999} />
```

Props:
- `value`: number | undefined — controlled value
- `defaultValue`: number — initial value (uncontrolled mode)
- `onChange`: (value: number | null) => void — called on value change
- `locale`: string (default: "en-AE") — locale for formatting
- `decimals`: number (default: 2) — max decimal places
- `min` / `max`: number — value clamping on blur
- `showSymbol`: boolean (default: true) — show inline SVG symbol
- `useCode`: boolean (default: false) — show AED text instead of symbol
- `selectOnFocus`: boolean (default: true) — auto-select on focus

### useDirhamRate

React hook for fetching and using live exchange rates.

```tsx
import { useDirhamRate } from "dirham/react";
const { rate, convert, convertBack, loading, error, refetch } = useDirhamRate("USD");
```

Returns:
- `rate`: number | undefined — current exchange rate
- `loading`: boolean — fetch in progress
- `error`: string | undefined — error message
- `convert(amount)`: number — convert AED to target currency
- `convertBack(amount)`: number — convert target currency to AED
- `refetch()`: void — clear cache and re-fetch

### DirhamIcon

Font-based icon component. Requires `dirham/css` to be imported.

```tsx
import "dirham/css";
import { DirhamIcon } from "dirham/react";
<DirhamIcon size={16} />
```

Props:
- `size`: number | string (default: "inherit") — font size
- `color`: string (default: "currentColor") — icon color
- `as`: "i" | "span" (default: "i") — HTML tag
- `className`: string — additional CSS classes
- `aria-label`: string (default: "UAE Dirham") — accessible label

## JavaScript/TypeScript Utilities

### Constants

```ts
import {
  DIRHAM_UNICODE,        // "\u20C3" — the Unicode character
  DIRHAM_CODEPOINT,      // 0x20C3 — numeric codepoint
  DIRHAM_HTML_ENTITY,    // "&#x20C3;" — HTML entity
  DIRHAM_CSS_CONTENT,    // "\\20C3" — for CSS pseudo-elements
  DIRHAM_CURRENCY_CODE,  // "AED" — ISO 4217 code
  DIRHAM_SYMBOL_TEXT,    // "د.إ" — Arabic text representation
  DIRHAM_FONT_FAMILY,    // Font family name for the web font
} from "dirham";
```

### formatDirham(amount, options?)

Format a number as a Dirham currency string.

```ts
formatDirham(1234.5);                          // "د.إ 1,234.50"
formatDirham(1234.5, { locale: "ar-AE" });     // "١٬٢٣٤٫٥٠ د.إ"
formatDirham(100, { useCode: true });          // "AED 100.00"
formatDirham(100, { decimals: 0 });            // "د.إ 100"
formatDirham(100, { symbolFirst: false });     // "100.00 د.إ"
formatDirham(5000000, { notation: "compact" }); // "د.إ 5M"
```

Options:
- `locale`: string (default: "en-AE") — locale for number formatting
- `decimals`: number (default: 2) — decimal places
- `symbolFirst`: boolean — symbol placement (auto-detected from locale if omitted)
- `useCode`: boolean (default: false) — use "AED" instead of symbol
- `separator`: string (default: non-breaking space) — between symbol and amount
- `notation`: "standard" | "compact" (default: "standard") — compact uses K/M/B abbreviations

### parseDirham(formatted)

Parse a formatted Dirham string back to a number.

```ts
parseDirham("د.إ 1,234.50");  // 1234.5
parseDirham("AED 100.00");    // 100
```

### copyDirhamSymbol(format?)

Copy the Dirham symbol to the clipboard in various formats.

```ts
import { copyDirhamSymbol } from "dirham";
await copyDirhamSymbol();          // copies "\u20C3" (unicode)
await copyDirhamSymbol("html");    // copies "&#x20C3;"
await copyDirhamSymbol("css");     // copies "\\20C3"
await copyDirhamSymbol("arabic");  // copies "د.إ"
```

Formats: `"unicode"` (default), `"html"`, `"css"`, `"arabic"`

### copyDirhamAmount(amount, options?)

Copy a formatted Dirham amount to the clipboard.

```ts
import { copyDirhamAmount } from "dirham";
await copyDirhamAmount(1234.5);                    // copies "د.إ 1,234.50"
await copyDirhamAmount(1234.5, { useCode: true }); // copies "AED 1,234.50"
```

### VAT Helpers

UAE VAT calculation utilities (5% standard rate by default).

```ts
import { addVAT, removeVAT, getVAT, UAE_VAT_RATE } from "dirham";
addVAT(100);                        // 105
removeVAT(105);                     // 100
getVAT(100);                        // 5
addVAT(100, { rate: 0.1 });         // 110 (custom rate)
addVAT(99.99, { decimals: 4 });     // 104.9895
```

Options: `rate` (default: 0.05), `decimals` (default: 2)

### Currency Conversion

Convert between AED and other currencies. Rates fetched from open.er-api.com (no auth required), cached for 1 hour.

```ts
import { convertFromAED, convertToAED, fetchExchangeRates, clearRateCache } from "dirham";
const usd = await convertFromAED(100, "USD");
const aed = await convertToAED(27.23, "USD");
const manual = await convertFromAED(100, "USD", { rate: 0.2723 }); // skip fetch
const rates = await fetchExchangeRates(); // { USD: 0.2723, EUR: 0.2511, ... }
clearRateCache(); // force re-fetch on next call
```

Options: `decimals` (default: 2), `rate` (override, skips network fetch)

## Web Component

Framework-agnostic custom elements, usable in any HTML page or framework (Vue, Angular, Svelte, etc.).

```html
<script type="module">
  import "dirham/web-component";
</script>
<dirham-symbol size="24" color="currentColor" weight="regular"></dirham-symbol>
<dirham-price amount="1250"></dirham-price>
<dirham-price amount="5000000" notation="compact"></dirham-price>
<dirham-price amount="500" use-code></dirham-price>
```

`<dirham-symbol>` attributes: `size`, `color`, `weight`, `aria-label`
`<dirham-price>` attributes: `amount`, `locale`, `decimals`, `notation`, `use-code`, `symbol-size`, `weight`, `currency`
`<dirham-animated-price>` attributes: `amount`, `duration`, `easing`, `locale`, `decimals`, `notation`, `use-code`, `symbol-size`, `weight`
`<dirham-input>` attributes: `value`, `locale`, `decimals`, `min`, `max`, `placeholder`, `disabled`, `readonly`, `show-symbol`, `use-code`, `symbol-size`, `weight` — fires `dirham-change` event

## React Native

Requires `react-native-svg` as a peer dependency. Same SVG path data as web version.

```tsx
import { DirhamSymbol, DirhamPrice } from "dirham/react-native";
<DirhamSymbol size={24} color="#000" weight="bold" />
<DirhamPrice amount={1250} />
<DirhamPrice amount={500} locale="ar-AE" useCode />
```

DirhamSymbol props: `size` (default: 24), `color` (default: "#000"), `weight`, `accessibilityLabel`
DirhamPrice props: `amount`, `locale`, `decimals`, `useCode`, `notation`, `symbolSize`, `weight`, `color`, `fontSize`

## Tailwind CSS Plugin

Provides utility classes for the Dirham symbol. No React dependency.

```js
// tailwind.config.js
import dirhamPlugin from "dirham/tailwind";
export default { plugins: [dirhamPlugin] };
```

Utilities:
- `.dirham` — base class, sets font-family
- `.dirham-thin` through `.dirham-black` — weight variants
- `.dirham-xs` through `.dirham-4xl` — size utilities
- `.dirham-before` / `.dirham-after` — pseudo-elements with `\20C3` content
- `.dirham-price` — component class (nowrap + tabular-nums)

## Next.js Font Optimization

Pre-configured `next/font/local` instance.

```tsx
import { dirhamFont } from "dirham/next";
<html className={dirhamFont.className}>...</html>
// CSS variable: var(--font-dirham)
```

For manual setup: `import { dirhamFontConfig } from "dirham/next";`

## CDN Usage (No Install)

Use via jsDelivr or unpkg without npm install:

```html
<!-- CSS web font -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dirham/dist/css/dirham.css" />
<i class="dirham-symbol"></i>

<!-- Web Component -->
<script type="module" src="https://cdn.jsdelivr.net/npm/dirham/dist/web-component/index.js"></script>
<dirham-symbol size="20"></dirham-symbol>
<dirham-price amount="1250"></dirham-price>
```

## CLI

```bash
npx dirham          # prints symbol info table
npx dirham copy     # copies Unicode symbol to clipboard
npx dirham copy html # copies HTML entity
```

Formats: `unicode`, `html`, `css`, `js`, `arabic`, `code`

## CSS / Web Font Usage

```html
<!-- Import CSS -->
<link rel="stylesheet" href="node_modules/dirham/dist/css/dirham.css" />

<!-- Use the icon class -->
<i class="dirham-symbol" aria-label="UAE Dirham"></i>
```

Or import in JS:
```ts
import "dirham/css";
```

## Font Variants

The package includes 5 font variants to match different typeface styles:
- **Default** — balanced design for general use
- **Sans** — clean sans-serif variant
- **Serif** — serif variant for editorial contexts
- **Mono** — monospace variant for code/data
- **Arabic** — Arabic calligraphic variant

## Unicode

Codepoint: U+20C3 (UAE DIRHAM SIGN)
Unicode version: 18.0
Status: Accepted by UTC on 2025-Jul-22, expected to ship September 2026
Migration: Zero — when native support arrives, the web font becomes optional automatically

## Technical Details

- Tree-shakeable ESM and CJS builds
- TypeScript types included
- React 17+ compatible (react is an optional peer dependency)
- SSR-safe (SVG component requires no font loading)
- Zero runtime dependencies for the core module
- Web Component (custom element) for framework-agnostic usage
- CLI tool (`npx dirham`) for quick access