kilfx

UI-only currency pair selector (flags + search) for:

• CDN <script> (single JS file with auto CSS injection)
• Node/Express pages
• Next.js / React (npm install kilfx)

kilfx does not fetch FX rates or call external FX APIs.
It only handles UI + emits change events so your app can fetch rates manually.

Install

npm install kilfx

DOM Convention

<div class="kilfx" kilfx_int="JMD" kilfx_only="JMD,USD,GBP">
  <select name="kilfx_base"></select>
  <select name="kilfx_to"></select>
  <input type="text" name="fx_rate" readonly />
</div>

Required in same .kilfx block:

• select[name="kilfx_base"]
• select[name="kilfx_to"]

Optional:

• input[name="fx_rate"] (forced readonly and cleared on pair change)

Also supported for Bootstrap-style split layout (different .kilfx columns):

• base_currency (alias of base)
• display_currency (alias of to)
• exchange_rate (alias of rate)

CDN Usage

<script src="https://yourcdn.com/kilfx.iife.min.js"></script>

That alone auto-inits .kilfx blocks on page load.

If you want custom config, add:

<script src="https://yourcdn.com/kilfx.iife.min.js"></script>
<script>
  KILFX.init({
    flagsPath: "/svg",
    defaultBase: "JMD",
    defaultTo: "USD"
  });
</script>

Optional explicit helper:

<script>
  KILFX.autoInit({ flagsPath: "/svg" });
</script>

npm / ESM Usage

import { init } from "kilfx";
init({ flagsPath: "/svg" });

Optional CSS import (JS still injects CSS automatically):

import "kilfx/dist/kilfx.css";

React / Next Usage

"use client";
import { KilFx } from "kilfx/react";

export default function Page() {
  return <KilFx flagsPath="/svg" defaultBase="JMD" defaultTo="USD" />;
}

Or render your own .kilfx markup and call init() in useEffect.

Events

On every base/to change, kilfx:

1. Updates hidden native <select> value
2. Dispatches native change on that <select>
3. Dispatches global event:

document.addEventListener("kilfx:change", (e) => {
  const { base, to, rootEl, baseSelectEl, toSelectEl, rateInputEl, baseItem, toItem } = e.detail;
});

detail shape:

• base / to: currency code ("USD", "JMD", etc.)
• rootEl: current .kilfx container
• baseSelectEl, toSelectEl: underlying native selects
• rateInputEl: resolved rate input in same form/group
• baseItem, toItem: { code, name, flag_code }

API

init({
  rootSelector: ".kilfx",
  baseName: "kilfx_base",
  toName: "kilfx_to",
  rateName: "fx_rate",
  flagsPath: "/svg",
  fileCase: "auto",       // auto | upper | lower
  enableSearch: true,
  defaultBase: "JMD",
  defaultTo: "JMD",
  initCurrency: "JMD",    // fallback for both (kilfx_int also works)
  only: "JMD,USD,GBP",    // restrict both dropdowns by currency code
  onlyBase: "JMD,USD",    // optional base-only restriction
  onlyTo: "USD,EUR",      // optional to-only restriction
  data: null              // custom currency data or null for built-in
});

Attribute Shortcuts (Per .kilfx)

Container attributes:

• kilfx_int="JMD": default code for both dropdowns (if specific defaults not set)
• kilfx_only="JMD,USD,GBP": restrict both dropdowns to selected currency codes
• kilfx_base_int="USD" / kilfx_to_int="JMD": specific defaults
• kilfx_base_only="USD,CAD" / kilfx_to_only="JMD,EUR": specific allowed lists

Select-level overrides also supported:

• select ... kilfx_int="USD"
• select ... kilfx_only="USD,JMD"

If nothing is provided, both dropdowns default to JMD.

Acceptance Example

<div class="kilfx">
  <select name="kilfx_base"></select>
  <select name="kilfx_to"></select>
  <input name="fx_rate" readonly />
</div>

<script src="/dist/kilfx.iife.min.js"></script>
<script>
  KILFX.init({ flagsPath: "/svg", defaultBase: "JMD", defaultTo: "USD" });

  document.addEventListener("kilfx:change", async (e) => {
    const { base, to, rateInputEl } = e.detail;
    const rateInput = rateInputEl;
    rateInput.value = "...";
    // const { data } = await axios.get("/api/fx/rate", { params: { base, to } });
    // rateInput.value = data.rate;
  });
</script>