💸 Vue Currency Converter

Vue 3.x component for currency conversion with customizable styles and configurable API endpoints for data fetching.

Install

npm i vue-currency-converter
# or
npm i vue-currency-converter
# or
pnpm i vue-currency-converter

Demo ❤️

Playground 🚀

Open the online Playground on StackBlitz

Try out the component live, tweak props, and experiment with integration directly in your browser.

Documentation 📚

View full documentation site — guides, API reference, and more examples.

Features

• Configurable API for currency conversion rates
• Default API included
• Component can be styled with css variables
• No dependencies
• Ready-to-use with pre-written styles

Quick Start

<script setup lang="ts">
import { ref } from "vue";
import type { Model } from "vue-currency-converter";
import CurrencyConverter from "vue-currency-converter";
import "vue-currency-converter/style.css";

const model = ref<Model>({
  currencies: ["EUR", "USD"],
});
</script>

<template>
  <CurrencyConverter v-model="model" />
</template>

Props

| Prop | Type | Default | Description | | ------------ | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | modelValue | Model | — (req) | Bound value for v-model. Holds the current state of the currency input. | | listConfig | Partial<ListParams> | see below | Configuration for the currency list / behavior. Any subset of ListParams. Unspecified fields fall back to component defaults (below). | | itemHeight | number | — | Fixed pixel height for each item row (overrides CSS var–driven sizing if provided). | | size | Size | — | Component size token used by your design system (e.g., sm, md, …). Controls overall spacing/row heights via CSS vars. | | disabled | boolean | false | Disables user interaction with the input and list. |

listConfig

| Key | Type | Default | Description | | --------------------- | ---------------- | ------------------------ | ----------------------------------------------------------------- | | itemsPerView | number | DEFAULT_ITEMS_PER_VIEW | How many items are visible in the scroll viewport. | | itemHeight | number | — | Per-item row height (px). If omitted, size/CSS vars are used. | | availableCurrencies | CurrencyCode[] | — | Optional allowlist of currencies to display. | | animationName | string | — | Custom CSS animation name for list transitions. | | reverse | boolean | false | Reverses list order. | | needFormat | boolean | true | Whether to live-format typed values (e.g., thousands separators). | | openBlocked | boolean | false | If true, prevents opening the dropdown/list. | | item.hideCode | boolean | false | Hide the currency code (e.g., USD). | | item.hideName | boolean | false | Hide the currency name (e.g., “US Dollar”). | | item.hideSymbol | boolean | false | Hide the currency symbol (e.g., $). |

Related types

type ListParams = {
  itemsPerView: number;
  itemHeight: number;
  availableCurrencies: CurrencyCode[];
  animationName: string;
  reverse: boolean;
  needFormat: boolean;
  openBlocked: boolean;
  item: {
    hideCode: boolean;
    hideName: boolean;
    hideSymbol: boolean;
  };
};

listConfig is Partial<ListParams>, so you can pass only what you need; unspecified fields use the defaults listed above.

Slots

| Slot | Props | Description | | ---------------- | ----- | --------------------------------------------------------------------------------------------------------- | | header:before | — | Content rendered before the header (inside the input header area). Useful for adding icons or labels. | | header:after | — | Content rendered after the header. Good for action buttons or extra UI elements. | | header:chevron | — | Replaces the default dropdown chevron icon in the header. | | item:before | — | Content rendered before each list item (e.g., prepend icon/flag). | | item:after | — | Content rendered after each list item (e.g., trailing action or badge). |

Emits

| Event | Payload | Description | | ------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- | | setCurrencies | [CurrencyCode, CurrencyCode] | Emitted when the active currency pair changes (e.g., user selects different “from/to” currencies). | | update:modelValue | Model | Standard v-model update event. Emits the updated component state/value. | | request:error | unknown | Emitted when a rate-fetching request fails. The payload contains the error object/response. | | request:success | ApiData | Emitted when a rate-fetching request succeeds. The payload contains the API response data. |

Types

// 'USD' | 'EUR' | 'CAD' | ...
export type CurrencyCode = keyof typeof currencyJson;

export interface CurrencyConfig {
  symbol: string;
  name: string;
  symbol_native: string;
  decimal_digits: number;
  rounding: number;
  code: CurrencyCode;
  name_plural: string;
}

export type ListParams = {
  itemsPerView: number;
  itemHeight: number;
  availableCurrencies: CurrencyCode[];
  animationName: string;
  reverse: boolean;
  needFormat: boolean;
  openBlocked: boolean;
  item: {
    hideCode: boolean;
    hideName: boolean;
    hideSymbol: boolean;
  };
};

export interface CurrencyInputModel {
  currency: CurrencyCode;
  value: string;
}

export type ApiData = Partial<
  Record<CurrencyCode, Record<CurrencyCode, number>>
>;

export type ApiConfig = {
  cache: number;
  fetchOptions: RequestInit;
  disabled: boolean;
  url: {
    base: string;
    builder: (url: string, code?: CurrencyCode) => string;
  };
  setter: (response: any, mutable: Ref<ApiData>) => void;
};

export interface RequiredModel {
  currencies: [CurrencyCode, CurrencyCode];
  values: [string, string];
  hasFocus: [boolean, boolean];
  loading: boolean;
}

export type Model = Partial<RequiredModel>;

export type InternalApiData = Ref<ApiData>;

export interface DefaultApiResponse {
  base_code: CurrencyCode;
  rates: Record<CurrencyCode, number>;
}

export type Size = "sm" | "md" | "lg" | "xl" | "xxl";

🤝 Contributing

Contributions are very welcome! You can help by fixing bugs, improving docs, or adding features.

1. Fork the repo and create a new branch
2. npm i to install dependencies
3. npm watch:build to build the project JIT
4. npm link in directory folder
5. npm link vue-currency-converter in your project directory
6. Commit your changes and push your branch 😍
7. Create Pull-Request
8. Thank you

For UI changes please include screenshots or gifs so it’s easy to review 🥹

👉 Bug reports and feature requests should be submitted as GitHub Issues.

🚧 Project Status

This component is currently in beta. The API and behavior may still change before a stable release.

If you encounter any bugs, unexpected behavior, or have feature requests: 👉 please open an issue on GitHub

Your feedback will help improve and stabilize the component for production use.

License

MIT © 2025 Mark Minerov