# Kiltel.js — Lightweight, Modern International Phone Input

> Beautiful flag + dial-code selector, **no jQuery**, no paid APIs. MIT licensed.

## ✨ Features

- 🌍 Flag + country code dropdown (keyboard + mouse)
- 🔎 Search by country **name / ISO code / dial code**
- 🎨 Pure CSS styling — fits Bootstrap or custom UIs
- 🧩 Works with server-rendered pages (EJS, Pug) and SPA frameworks
- ✅ Optional **validation** via `intl-tel-input` (auto-loaded when enabled)
- 🔢 Outputs three values: **full** (`+<dial><national>`), **country_code** (`+<dial>`), **contact** (`<national>`)
- 📦 Restrict list (only/exclude) and set preferred countries
- 🧠 Handles prefilled values, autofill, and paste
- 🛡️ No tracking, no paid APIs, **MIT License**

---

## Table of Contents

- [CDN Quick Start](#cdn-quick-start)
- [HTML Markup (Required Structure)](#html-markup-required-structure)
- [Attributes Reference](#attributes-reference)
- [What Gets Submitted](#what-gets-submitted)
- [Enable Validation (Optional)](#enable-validation-optional)
- [Multiple Fields on the Same Page](#multiple-fields-on-the-same-page)
- [React/SPA Usage](#reactspa-usage)
- [Styling & Theming](#styling--theming)
- [Accessibility](#accessibility)
- [Advanced Notes](#advanced-notes)
- [Troubleshooting / FAQ](#troubleshooting--faq)
- [Credits](#credits)
- [License](#license)

---

## CDN Quick Start

Include the CSS and JS from jsDelivr:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/kiltel@1.0.12/kiltel.css">
<script src="https://cdn.jsdelivr.net/npm/kiltel@1.0.12/kiltel.min.js"></script>
```

> Kiltel **auto-initializes** on `DOMContentLoaded`.  
> You can also call `window.kiltelInit()` manually if you inject HTML later (e.g., via AJAX).

---

## HTML Markup (Required Structure)

> The main input and its two hidden fields **must** be inside a wrapper with class `kiltel-phone-wrap`.

> The block below is shown **as-is** in README (inside a fenced code block) so it renders exactly:

```html
<div class="form-group row width-50">
  <label class="col-5 control-label">Contact No.</label>
  <div class="kiltel-phone-wrap col-6">
    <button type="button" class="kiltel-country-trigger"></button>
    <input
      type="tel"
      class="form-control"
      data-kilvish-tel
      id="kilvishcontact"
      name="full_contact"
      placeholder="Enter mobile number"
      data-kiltel-init="IT"
      data-kiltel-validation="yes"
      data-kilvish-only="IN,IT,US"
      data-kilvish-preferred="IN"
      required
      readonly
      value="+393381112223"
    >
      Prefilled/readonly for demo!
    <span class="fa fa-fw fa-phone" style="position: absolute; top: 10px; right: 25px; cursor: pointer;"></span>
    <input type="hidden" id="country_code" name="country_code">
    <input type="hidden" id="contact" name="contact">
  </div>
  <div id="kiltel-error" style="color:red; font-size:0.93em; margin-top:5px;"></div>
</div>
```

**Notes**
- The `button.kiltel-country-trigger` is either auto-created or you can place it manually (as above).
- For **readonly** demo, keep `readonly` and a sample `value`. For real forms, remove `readonly`.

---

## Attributes Reference

| Attribute | Description | Example |
|---|---|---|
| `data-kilvish-tel` | Activates Kiltel for this input | *(required)* |
| `data-kiltel-init` | Initial country (ISO code) | `"IT"`, `"US"`, `"IN"` |
| `data-kiltel-validation` | Validates number (loads `intl-tel-input` automatically) | `"yes"` |
| `data-kilvish-only` | Show **only** these countries (comma-separated ISO codes) | `"IN,US,IT"` |
| `data-kilvish-exclude` | **Exclude** these countries from dropdown | `"CN,RU"` |
| `data-kilvish-preferred` | Pin these at top of list | `"IN,US"` |

**Hidden fields inside `.kiltel-phone-wrap`**
- `<input type="hidden" name="country_code">` — will contain `+<dial>` (e.g., `+91`)
- `<input type="hidden" name="contact">` — will contain national digits (e.g., `1234567890`)

---

## What Gets Submitted

- **Main input** (`name="full_contact"` in the example) shows `+<dial><national>` (e.g., `+911234567890`).
- **Hidden `country_code`** → `+<dial>` (e.g., `+91`)
- **Hidden `contact`** → national number (e.g., `1234567890`)

Kiltel keeps these in sync as the user types, pastes, or switches country.

---

## Enable Validation (Optional)

Add `data-kiltel-validation="yes"` on the input to enable validation-on-blur.  
Kiltel **dynamically loads** `intl-tel-input@17.0.8` (and `utils.js`) — no extra tags needed.

- Unknown/invalid country code → shows `"Unknown country code!"`
- Invalid format for selected country → shows `"Invalid phone number for <Country>"`

Error is written into an element with id `kiltel-error` if present; otherwise one is created next to the input wrapper.

---

## Multiple Fields on the Same Page

Just repeat the wrapper block:

```html
<div class="kiltel-phone-wrap">
  <button type="button" class="kiltel-country-trigger"></button>
  <input type="tel" class="form-control" data-kilvish-tel name="billing_phone">
  <input type="hidden" name="billing_country_code">
  <input type="hidden" name="billing_contact">
</div>

<div class="kiltel-phone-wrap">
  <button type="button" class="kiltel-country-trigger"></button>
  <input type="tel" class="form-control" data-kilvish-tel name="shipping_phone" data-kilvish-only="IN,US" data-kilvish-preferred="IN">
  <input type="hidden" name="shipping_country_code">
  <input type="hidden" name="shipping_contact">
</div>
```

Kiltel guards against double-initialization automatically.

---

## React/SPA Usage

If the field is rendered after page load, call `window.kiltelInit()` once the DOM is updated:

```jsx
useEffect(() => {
  // render phone input DOM first, then:
  window.kiltelInit?.();
}, []);
```

For frameworks with virtual DOM, prefer **uncontrolled** inputs or refs; Kiltel manipulates the real input value (`.value`).

---

## Styling & Theming

Kiltel ships with a minimalist CSS. Common hooks:

- `.kiltel-phone-wrap` — container (set `position:relative` in your form CSS if needed)
- `.kiltel-country-trigger` — flag/dropdown button
- `.kiltel-country-list` — popup list container
- `.kiltel-country-option` — each option (active option has `.active`)
- `.kiltel-country-search` — search input inside the dropdown

You can safely override sizes, fonts, borders, shadows, etc.

---

## Accessibility

- Trigger is a real `<button>` — keyboard & screen-reader friendly
- Search input focuses automatically when the dropdown opens
- You can add `aria-label` on the trigger if needed

---

## Advanced Notes

- **Restrict candidates**: Kiltel will **only** match country by number within the available (allowed) list if you used `data-kilvish-only` or `data-kilvish-exclude`.
- **IP-based default**: If `data-kiltel-init` is not provided and the input is empty, Kiltel attempts to set the country based on `https://ipapi.co/json/` (best-effort).
- **Prefilled values**: If the input already contains a `+<dial>...` value on load, Kiltel sets the correct flag without overwriting the text (read-only friendly).

---

## Troubleshooting / FAQ

**The dropdown width looks off**  
Kiltel auto-fits the dropdown to the wrapper width. Ensure `.kiltel-phone-wrap` (or the input) has a width in your layout.

**The flag doesn’t show**  
We load flags from jsDelivr: `https://cdn.jsdelivr.net/npm/kiltel@latest/svg/<country>.svg`.  
Check network access or override via CSS if you host flags yourself.

**Validation doesn’t run**  
Ensure the input has `data-kiltel-validation="yes"`. Kiltel auto-loads `intl-tel-input@17.0.8` and its `utils.js` at runtime.

**I need read-only view**  
Keep the input `readonly` with a prefilled `value="+<dial><national>"`. Kiltel will render the flag and dial code correctly.

---

## Credits

- **Author**: Kilvish (Vasu Birla) — <https://github.com/Vasu-Birla> / <mailto:kilvishbirla@gmail.com>
- **Idea, code & maintenance**: Kilvish Birla, with community feedback and UX tuning
- **Special thanks**: [intl-tel-input](https://github.com/jackocnr/intl-tel-input) — used optionally for validation only
- **Community**: Contributors, testers, and developers who improve Kiltel

---

## License

**MIT** — Fork, remix, and use in commercial projects. No attribution required (but appreciated!).