Widget Documentation
Complete guide to embedding and customizing the Currency.Wiki currency converter widget on your website.
Table of Contents
1 Getting Started
Adding a currency converter widget to your website is easy. Follow these simple steps:
- Go to the Widget Builder page and customize your widget appearance
- Select your preferred widget style, currencies, and theme
- Copy the generated embed code (Script or Iframe)
- Paste the code into your website's HTML where you want the widget to appear
Tip: Use the Quick Start Presets in the Widget Builder to get started quickly with a pre-configured widget.
2 Embed Methods
Script Embed (Recommended)
The script embed method injects the widget directly into your page. Currency dropdown menus will display in front of surrounding content for easy selection.
<div id="currency-wiki-widget"></div>
<script src="https://widget.currency.wiki/v3/script.js?style=compact&theme=light&from=USD&to=EUR"></script>
- Dropdowns display outside the widget container
- Best for interactive currency selection
- Seamless integration with your page
Iframe Embed
The iframe embed method creates an isolated container for the widget. This method is secure and works in environments with strict content policies.
<iframe src="https://widget.currency.wiki/v3/embed?style=compact&theme=light&from=USD&to=EUR"
width="300" height="180" frameborder="0"></iframe>
- Completely isolated from your page styles
- Works with strict Content Security Policies
- Simple and secure implementation
Note: Use Script embed for full interactivity (dropdowns display over content). Use Iframe embed when you need isolation or have CSP restrictions.
3 Widget Styles
Choose from 11 different widget styles to match your website's design. Each style is optimized for different use cases and display sizes.
mini
250x140px
Compact single-line converter. Perfect for headers or tight spaces.
square
250x250px
1:1 ratio widget with swap button. Great for sidebars.
compact
300x180px
Small footprint converter with all essential features.
inline
480x56px
Horizontal layout. Ideal for embedding within content or navigation.
tall
200x280px
Vertical sidebar layout with classic labels.
mini-chart
250x260px
Compact converter with sparkline chart showing rate history.
multi-expandable
300x320px
Multi-currency converter. Users can add/remove currencies.
multi-fixed
300x300px
Fixed list of exchange rates. Best for displaying specific rates.
rates-compact
250x320px
Condensed exchange rates list with last updated time.
rates-viewer
300x500px
Full chart view with detailed rate information.
rates-viewer-compact
300x400px
Compact version of rates viewer with charts.
4 URL Parameters
Customize your widget using URL parameters. These parameters work with both Script and Iframe embed methods.
| Parameter | Default | Description |
|---|---|---|
| style | compact | Widget style (mini, square, compact, inline, tall, mini-chart, multi-expandable, multi-fixed, rates-compact, rates-viewer, rates-viewer-compact) |
| theme | light | Color theme (light, dark, or auto) |
| from | USD | Source currency code (e.g., USD, EUR, GBP) |
| to | EUR | Target currency code (e.g., EUR, USD, JPY) |
| amount | 1000 | Default amount for conversion |
| accent | #2563eb | Accent color in hex format (without #) |
| lang | en | Widget language code (e.g., en, es, fr, de) |
| flags | 1 | Show country flags (1=show, 0=hide) |
| display | iso | Currency display format (iso=USD, symbol=$) |
| lock | 0 | Lock currencies (1=locked, 0=unlocked) |
| currencies | EUR,GBP,JPY | Comma-separated list of currencies for multi-currency widgets |
| dropdown | all | Currencies in dropdown (all, top10, top20, or comma-separated list) |
| branding | 1 | Show branding (1=show, 0=hide) |
| brandinglink | 1 | Make branding clickable (1=link, 0=text only) |
| format | auto | Number format (auto, us, eu, french, indian) |
| decimals | 2 | Number of decimal places (0-6) |
| chart | 0 | Enable chart (1=enabled, 0=disabled) |
| chartperiod | 7d | Chart period (7d, 14d, 30d, 90d) |
Examples
Dark theme compact converter:
?style=compact&theme=dark&from=USD&to=EUR
Multi-currency exchange rates:
?style=multi-fixed&from=USD¤cies=EUR,GBP,JPY,CAD
Mini converter with 30-day chart:
?style=mini-chart&from=EUR&to=USD&chartperiod=30d
Display currency symbols instead of codes:
?style=compact&display=symbol&from=USD&to=EUR
Locked currencies with custom amount:
?style=compact&from=GBP&to=USD&lock=1&amount=100
5 Customization Options
Theme Options
- light - Light background with dark text
- dark - Dark background with light text
- auto - Automatically matches user's system preference
Currency Display Format
- iso - Shows ISO codes like USD, EUR, GBP
- symbol - Shows currency symbols like $, €, £
Number Formats
- auto - Automatically detects visitor's browser settings
- us - US format: 1,234.56
- eu - European format: 1.234,56
- french - French format: 1 234,56
- indian - Indian format: 1,23,456.78
Dropdown Currency Options
- all - All 170+ supported currencies
- top10 - Top 10 most popular currencies
- top20 - Top 20 currencies by trading volume
- USD,EUR,GBP,... - Custom list of specific currencies
Tip: Use the Widget Builder to visually configure all these options and generate the embed code automatically.
6 Troubleshooting
Widget Not Showing
Ensure the embed code is placed correctly in your HTML. For script embed, make sure the container div exists with the correct ID. Check your browser console for any JavaScript errors.
Dropdown Not Working
If using iframe embed, dropdowns will scroll inside the widget area. For full dropdown functionality with overlays, use the script embed method instead.
Style Conflicts
If your website's CSS is affecting the widget appearance, try using the iframe embed method which isolates the widget styles from your page.
Content Security Policy Issues
If you have a strict CSP, you may need to add currency.wiki to your allowed script-src and frame-src directives. Example: script-src 'self' currency.wiki; frame-src 'self' currency.wiki;
Need Help?
Can't find what you're looking for? Our support team is here to help.
