Currency Manager
A flexible set of components for managing currency display and selection. Users provide exchange rates relative to a fixed base currency, and the component handles fetching currency names and performing conversions.
Installation
Install the Currency Manager component using your preferred package manager.
Usage
The Currency Manager allows users to select their preferred currency and see values converted in real-time.
Discover Its Features
The Currency Manager component is packed with powerful features designed to provide an exceptional user experience.
Real-time Currency Conversion
Convert monetary values between 180+ currencies with live exchange rates or your custom rates.
Smart Caching & Persistence
Automatically caches exchange rates and currency data for faster loading and offline resilience.
Flexible Rate Sources
Use static rates, live API data, or your custom rate fetching function with configurable refresh intervals.
Global Currency Support
Supports 180+ currencies with proper symbols, names, and locale-aware formatting for international use.
Production Ready
SSR-safe, TypeScript support, error handling, fallback mechanisms, and optimized performance.
Smart Refresh Logic
Intelligent rate refreshing that only fetches when needed, respecting your specified intervals.
Components
The Currency Manager consists of the following components:
CurrencyProvider
A context provider that manages currency selection, conversion rates (user-provided), and formatting. Fetches available currency names dynamically from a CDN and provides real-time currency conversion functionality to child components.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode | — | The content to wrap with the currency provider. |
| fixedBaseCurrencyCode* | string | — | The currency code (e.g., "USD") against which all provided exchange rates are relative. This is required. |
| initialRates | Record<string, number> | {} | An initial object of exchange rates, relative to `fixedBaseCurrencyCode`. Example: `{ "EUR": 0.92, "INR": 83.5 }` if `fixedBaseCurrencyCode` is "USD". |
| fetchRatesFunction | () => Promise<Record<string, number>> | — | A user-provided async function that returns a promise resolving to an object of exchange rates, relative to `fixedBaseCurrencyCode`. The returned object should have currency codes as keys (e.g., "EUR", "INR") and positive numbers as values representing conversion rates. If the function throws an error or returns invalid data, cached rates will be used as fallback. |
| refetchIntervalMs | number | — | Interval in milliseconds to call `fetchRatesFunction`. Requires `fetchRatesFunction` to be set. Minimum recommended value is 60000 (1 minute). |
| defaultSelectedCurrencyCode | string | "INR" | The currency code to be selected by default. The component will try to find this code in the fetched list of available currencies. |
| loaderComponent | ComponentType | Internal <Loader /> icon | A custom component to display while loading data (e.g., currency names or exchange rates). |
CurrencySelector
A searchable combobox component that allows users to easily find and select their preferred currency from a dynamically fetched list of 180+ currencies. Features instant search, displays both currency codes and full names (e.g., "USD - United States Dollar"), and provides a smooth user experience.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | — | Additional CSS class for the selector. |
CurrencyDisplay
A component that displays monetary values with proper currency formatting, converting them based on user-provided exchange rates and the selected currency. Supports different source currencies and custom styling.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number | — | The monetary value to display. Should be a positive number. |
| sourceCurrency | string | `fixedBaseCurrencyCode` from Provider | The currency code of the input `value`. If not provided, the `value` is assumed to be in the `fixedBaseCurrencyCode` set in the `CurrencyProvider`. |
| className | string | — | Additional CSS class for the display. |