🇸🇦 Saudi Riyal

The definitive Saudi Riyal (SAR) library. Display and format the Saudi Riyal symbol with automatic Unicode 17 detection, smart fallbacks, and beautiful formatting.

🇸🇦 اقرأ بالعربي

Why This Library?

| Feature | saudi-riyal | Others | |---------|-------------|--------| | Unicode 17 (U+20C1) auto-detection | ✅ | ❌ | | Smart fallback chain | ✅ | ❌ | | Works without custom fonts | ✅ | ❌ | | Number formatting (Arabic/English) | ✅ | ❌ | | React/Vue components | ✅ | ❌ | | TypeScript support | ✅ | Partial | | Zero dependencies (core) | ✅ | ❌ | | Tree-shakeable | ✅ | ❌ |

Quick Start

npm install saudi-riyal

import { sar, formatSAR } from 'saudi-riyal';

// Get the symbol (auto-detects best method)
console.log(sar()); // ﷼ or the new Unicode 17 symbol

// Format currency
console.log(formatSAR(1234.56)); // ﷼ 1,234.56

That's it. No font setup, no configuration. It just works.

Features

🔮 Future-Proof

Automatically uses Unicode 17's official Saudi Riyal symbol (U+20C1) when the system supports it. Falls back gracefully on older systems.

import { supportsUnicode17, detectBestStrategy } from 'saudi-riyal';

if (supportsUnicode17()) {
  console.log('Your system supports the new symbol!');
}

console.log(detectBestStrategy()); // 'unicode17' | 'font' | 'legacy'

💰 Beautiful Formatting

import { formatSAR, format } from 'saudi-riyal';

// Basic formatting
formatSAR(1234.56);                    // ﷼ 1,234.56

// Arabic numerals
formatSAR(1234.56, { arabicNumerals: true }); // ﷼ ١٬٢٣٤٫٥٦

// Arabic style (symbol after)
format.ar(1234.56);                    // ١٬٢٣٤٫٥٦ ﷼

// English style
format.en(1234.56);                    // SAR 1,234.56

// Compact notation
format.compactAr(1500000);             // ١.٥ مليون ﷼
format.compactEn(1500000);             // SAR 1.5M

// Accounting format (negative in parentheses)
format.accounting(-1234.56);           // (﷼ 1,234.56)

⚛️ React Components

import { SaudiRiyal, SaudiRiyalPrice, useSaudiRiyal } from 'saudi-riyal/react';

// Simple symbol
<SaudiRiyal /> 100

// Formatted price
<SaudiRiyalPrice amount={1234.56} />
<SaudiRiyalPrice amount={1234.56} arabicNumerals />
<SaudiRiyalPrice amount={1500000} compact />

// Hook for custom usage
function PriceDisplay() {
  const { symbol, strategy } = useSaudiRiyal();
  return <span>{symbol} 100</span>;
}

💚 Vue Components

<script setup>
import { SaudiRiyal, SaudiRiyalPrice } from 'saudi-riyal/vue';
</script>

<template>
  <SaudiRiyal /> 100
  <SaudiRiyalPrice :amount="1234.56" />
  <SaudiRiyalPrice :amount="1234.56" arabic-numerals />
</template>

🎨 CSS Utilities

<!-- Include the CSS -->
<link rel="stylesheet" href="https://unpkg.com/saudi-riyal/dist/saudi-riyal.css">

<!-- Use the classes -->
<span class="sar"></span> 100
<span class="sar-before">100</span>
<span class="sar-after">100</span>

<!-- With the price component -->
<span class="sar-price">1,234.56</span>

Installation

npm / yarn / pnpm

npm install saudi-riyal
yarn add saudi-riyal
pnpm add saudi-riyal

CDN

<!-- ESM -->
<script type="module">
  import { sar, formatSAR } from 'https://esm.sh/saudi-riyal';
</script>

<!-- CSS only -->
<link rel="stylesheet" href="https://unpkg.com/saudi-riyal/dist/saudi-riyal.css">

API Reference

Symbol Functions

sar(options?)

Get the Saudi Riyal symbol string.

sar()                           // Auto-detect best symbol
sar({ strategy: 'legacy' })     // Force legacy symbol (﷼)
sar({ strategy: 'unicode17' })  // Force Unicode 17 (may not render)
sar({ strategy: 'text-ar' })    // Use text (ر.س)

getSymbol(options?)

Get the symbol with metadata.

const result = getSymbol();
console.log(result.symbol);     // The symbol string
console.log(result.strategy);   // Which strategy was used
console.log(result.isPreferred); // Whether this is the best available

Formatting Functions

formatSAR(amount, options?)

Format a number as Saudi Riyal currency.

| Option | Type | Default | Description | |--------|------|---------|-------------| | locale | string | 'ar-SA' | Locale for number formatting | | decimals | number | 2 | Decimal places | | symbolPosition | 'before' \| 'after' | auto | Symbol position | | space | boolean | true | Space between symbol and number | | arabicNumerals | boolean | false | Use ٠١٢٣٤٥٦٧٨٩ | | compact | boolean | false | Compact notation (1K, 1M) | | accounting | boolean | false | Parentheses for negative | | useCode | boolean | false | Use "SAR" instead of symbol |

parseSAR(formatted)

Parse a formatted string back to a number.

parseSAR('﷼ 1,234.56');     // 1234.56
parseSAR('١٬٢٣٤٫٥٦ ر.س');   // 1234.56

Detection Functions

supportsUnicode17()

Check if the system supports the Unicode 17 symbol.

supportsSaudiRiyalFont(fontFamily?)

Check if a custom font is loaded.

detectBestStrategy()

Get the recommended rendering strategy.

Symbol Reference

| Symbol | Code Point | Support | Use Case | |--------|------------|---------|----------| | (new) | U+20C1 | Unicode 17+ | Future-proof apps | | ﷼ | U+FDFC | Universal | Maximum compatibility | | (font) | U+E900 | Custom font | When font is loaded | | ر.س | Text | Universal | Fallback | | SAR | Text | Universal | International |

Browser Support

• ✅ Chrome 80+
• ✅ Firefox 75+
• ✅ Safari 13+
• ✅ Edge 80+
• ✅ Node.js 16+

Unicode 17 symbol support depends on system fonts (expected in OS updates 2025-2026).

Migration from Other Libraries

From @emran-alhaddad/saudi-riyal-font

// Before: Required font setup
import "@emran-alhaddad/saudi-riyal-font/index.css";
// <span class="icon-saudi_riyal_new"></span>

// After: Just works
import { sar } from 'saudi-riyal';
console.log(sar()); // Automatically uses best available method

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Abdullah Alzhrani