Skip to content
Nana UI

Forms & Inputs

Phone Input

A telephone field with a country picker that groups the number as it is typed and submits it in international form.

View .md Download

The phone input takes a mobile or landline number with its country. The country picker shows the flag and dialling code, Kenya by default, and the number is grouped as the country writes it while people type: 712 345 678. Whatever is typed or pasted, the value is the international form, +254712345678, ready to store or send an SMS to.

Send documents

Nothing sent yet

We text the policy documents here.

Nothing sent yet

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add phone-input --framework web-components
npx @nana-tec/ui add phone-input --framework svelte

Lands in src/lib/components/ui/phone-input/ as NanaPhoneInput.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

<script lang="ts">
import { NanaPhoneInput } from '$lib/components/ui/phone-input';
let phone = $state('');
</script>
<NanaPhoneInput bind:value={phone} label="Phone number" name="phone" required />

value is bindable and holds the international form, or an empty string. country is bindable too: it chooses the country for an empty field and follows the number once there is one. onValueChange receives the value with { country, complete }.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/phone-input";

Copied in with npx @nana-tec/ui add phone-input? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-phone-input label="Phone number" name="phone" required></nana-phone-input>
<script type="module">
const phone = document.querySelector('nana-phone-input');
phone.addEventListener('nana-change', (event) => {
console.log(event.detail.value, event.detail.country, event.detail.complete);
});
</script>

The element takes part in its form: it submits value under name, resets with the form, and is disabled with a disabled fieldset. nana-input fires while typing and nana-change when the field is left or the country changes.

Set value to show a stored number; its dialling code picks the country. Set country to an ISO code, such as UG, to start an empty field elsewhere.

  • A leading 0, the trunk prefix most countries dial at home, is dropped: 0712 345 678 becomes 712 345 678.
  • A pasted number starting with + or 00 switches to its country: +256 772 123 456 picks Uganda.
  • A number typed with its dialling code but no +, such as 254712345678, loses the code.
  • Anything that is not a digit is ignored, and typing stops at the country’s length.
  • Editing in the middle keeps the caret after the digit it followed.

The list starts with East Africa, then the rest of Africa and the countries most often called from it. Each country knows its dialling code, how its numbers are grouped, and how many digits they have. Pass countries to offer your own list, built from the same shape:

import { PHONE_COUNTRIES } from '@nana-tec/ui-core/phone';
const eastAfrica = PHONE_COUNTRIES.filter((country) =>
['KE', 'UG', 'TZ', 'RW', 'BI', 'SS'].includes(country.code),
);

A number shorter than its country’s numbers blocks the form, and once the field is left it shows “Enter a complete phone number”. With required, an empty field blocks the form too. For any other problem, such as a number already in use, set invalid with your own errorMessage.

  • The number field is a tel input with inputmode="tel", so phones show the dial pad, and autocomplete="tel-national", so browsers can fill it.
  • The country picker is a native select named “Country code”, with each option read as “Kenya (+254)”. The flag and code drawn over it are hidden from screen readers.
  • The help text describes the field; an error replaces it and is announced.

Properties

PropertyAttributeTypeDefaultDescription
countries—readonly PhoneCountry[]PHONE_COUNTRIESThe countries offered
countrycountry—DEFAULT_PHONE_COUNTRYThe country for an empty field; a given number decides its own
countryLabelcountry-labelstring'Country code'Names the country picker for screen readers
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
errorMessageerror-messagestring''Shown while invalid is set
helperTexthelper-textstring''Text under the field, in the help part.
invalidinvalidbooleanfalseMarks the field invalid and shows error-message in place of the helper text.
labellabelstring''Visible label
namenamestring''Name the value is submitted under in a form.
placeholderplaceholderstring''Hint text shown while the field is empty.
requiredrequiredbooleanfalseThe form will not submit while this has no value.
valuevaluestring''The number in international form, such as +254712345678; empty when blank

Events

EventDescription
nana-inputWhile typing; detail: { value, country, complete }
nana-changeWhen the field is left or the country changes; detail: { value, country, complete }

CSS parts

PartDescription
::part(label)The field label
::part(required)The asterisk after a required field's label
::part(base)The box around the country and the number
::part(country)The country picker, drawn as the flag and dialling code
::part(flag)The country's flag
::part(dial)The dialling code
::part(chevron)The arrow after the dialling code
::part(select)The native country list over the picker
::part(input)The number field
::part(help)The helper text
::part(error)The error message

CSS custom properties

PropertyDescription
--nana-phone-input-heightHeight of the field

NanaPhoneInput

PropTypeDefault
valuebind:string''
countrybind:stringDEFAULT_PHONE_COUNTRY
countriesreadonly PhoneCountry[]PHONE_COUNTRIES
labelstring
countryLabelstring
helperTextstring
errorMessagestring
invalidbooleanfalse
onValueChange(value: string, detail: { country: string; complete: boolean }) => void

Also accepts Omit<HTMLInputAttributes, 'class' | 'value' | 'type'>.