Africa-first phone number library for JavaScript/TypeScript. Lightweight, carrier-aware, mobile-money-aware, multi-format output.
- < 3 KB gzipped for the Côte d'Ivoire build.
- Zero runtime dependencies.
- Carrier and mobile-money aware (Orange, MTN, Moov, Wave).
- Multi-format: ESM, CJS, IIFE,
.d.ts. - Bilingual errors: English (default) / French.
libphonenumber-js is great for global use but ships ~145 KB of metadata. afrophone is scoped to Africa, ships idiomatic local formatting (CI numbers grouped XX XX XX XX XX), surfaces the mobile-money picture, and explicitly flags number-portability uncertainty so you don't ship false carrier guarantees.
npm install afrophone
# or
bun add afrophoneOr via <script>:
<script src="https://unpkg.com/afrophone/dist/afrophone.min.js"></script>
<script>
const r = Afrophone.parse("0707070707", "CI");
</script>import { parse, format, isValid } from "afrophone";
parse("0707070707", "CI");
// {
// valid: true,
// e164: "+2250707070707",
// national: "07 07 07 07 07",
// international: "+225 07 07 07 07 07",
// uri: "tel:+2250707070707",
// carrier: "orange",
// portabilityCaveat: true,
// presumedMobileMoneyProviders: ["wave", "orange_money"],
// ...
// }
format("0707070707", "international", { country: "CI" });
// "+225 07 07 07 07 07"
isValid("9907070707", "CI"); // falseParses dirty input. Accepts spaces, dashes, dots, parentheses, leading 00 or +. Never throws.
parse("+225 07 07 07 07 07"); // auto-detects CI
parse("00225 0707070707"); // 00 prefix accepted
parse("0707070707", { country: "CI", locale: "fr" });style is "e164" | "national" | "international" | "uri". Accepts a string or a ParseResult (avoids re-parsing). Returns "" (or options.fallback) on invalid input.
One-line wrapper for form validators.
Returns universal providers (Wave) first, then the carrier-aligned provider.
Module-global default locale for error messages. Per-call override is available via parse(..., { locale }).
| Country | Code | Status |
|---|---|---|
| Côte d'Ivoire | CI |
✅ v0.1.0 |
| Sénégal, Mali, Burkina Faso | SN ML BF |
🔜 v0.2 |
| Bénin, Togo, Niger, Guinée | BJ TG NE GN |
🔜 v0.3 |
| Nigeria, Ghana | NG GH |
🔜 v0.4 |
Carrier identification is based on the prefix assigned by the regulator. Number portability is active in Côte d'Ivoire and most West African countries, so a number originally allocated to Orange may now route through MTN or Moov. Every successful parse therefore sets portabilityCaveat: true. Treat the carrier as a presumption, never a guarantee.
| Carrier | Provider |
|---|---|
| Orange | Orange Money |
| MTN | MTN MoMo |
| Moov | Moov Money |
| (any) | Wave (universal) |
PRs welcome — see CONTRIBUTING.md. Good first issues are labeled in GitHub.
MIT © Souleymane Diallo