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.
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.
Preview
Section titled “Preview”<form
id="phone-demo"
style="
display: flex;
flex-direction: column;
gap: 1rem;
width: 100%;
max-width: 24rem;
"
>
<nana-phone-input
label="Phone number"
name="phone"
required
helper-text="We text the policy documents here."
style="width: 100%"
></nana-phone-input>
<nana-button type="submit">Send documents</nana-button>
<p
id="phone-sent"
style="
margin: 0;
font-size: 0.875rem;
color: var(--nana-surface-text-muted);
"
>
Nothing sent yet
</p>
</form>
<script type="module">
const form = document.getElementById("phone-demo");
form.addEventListener("submit", (event) => {
event.preventDefault();
document.getElementById("phone-sent").textContent =
"Sending to " + new FormData(form).get("phone");
});
</script> <script lang="ts">
import { NanaButton, NanaPhoneInput } from '$lib';
let value = $state('');
let sent = $state('');
</script>
<form
class="flex w-full max-w-sm flex-col gap-4"
onsubmit={(event) => {
event.preventDefault();
sent = value;
}}
>
<NanaPhoneInput
bind:value
label="Phone number"
name="phone"
required
helperText="We text the policy documents here."
/>
<NanaButton type="submit" class="self-start">Send documents</NanaButton>
<p class="text-sm text-foreground-muted">{sent ? `Sending to ${sent}` : 'Nothing sent yet'}</p>
</form> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add phone-input --framework web-componentsnpx @nana-tec/ui add phone-input --framework svelteLands 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.
Typing and pasting
Section titled “Typing and pasting”- A leading
0, the trunk prefix most countries dial at home, is dropped:0712 345 678becomes712 345 678. - A pasted number starting with
+or00switches to its country:+256 772 123 456picks Uganda. - A number typed with its dialling code but no
+, such as254712345678, 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.
Countries
Section titled “Countries”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),);Validation
Section titled “Validation”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.
Accessibility
Section titled “Accessibility”- The number field is a
telinput withinputmode="tel", so phones show the dial pad, andautocomplete="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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
countries | — | readonly PhoneCountry[] | PHONE_COUNTRIES | The countries offered |
country | country | — | DEFAULT_PHONE_COUNTRY | The country for an empty field; a given number decides its own |
countryLabel | country-label | string | 'Country code' | Names the country picker for screen readers |
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
errorMessage | error-message | string | '' | Shown while invalid is set |
helperText | helper-text | string | '' | Text under the field, in the help part. |
invalid | invalid | boolean | false | Marks the field invalid and shows error-message in place of the helper text. |
label | label | string | '' | Visible label |
name | name | string | '' | Name the value is submitted under in a form. |
placeholder | placeholder | string | '' | Hint text shown while the field is empty. |
required | required | boolean | false | The form will not submit while this has no value. |
value | value | string | '' | The number in international form, such as +254712345678; empty when blank |
Events
| Event | Description |
|---|---|
nana-input | While typing; detail: { value, country, complete } |
nana-change | When the field is left or the country changes; detail: { value, country, complete } |
CSS parts
| Part | Description |
|---|---|
::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
| Property | Description |
|---|---|
--nana-phone-input-height | Height of the field |
NanaPhoneInput
| Prop | Type | Default |
|---|---|---|
valuebind: | string | '' |
countrybind: | string | DEFAULT_PHONE_COUNTRY |
countries | readonly PhoneCountry[] | PHONE_COUNTRIES |
label | string | |
countryLabel | string | |
helperText | string | |
errorMessage | string | |
invalid | boolean | false |
onValueChange | (value: string, detail: { country: string; complete: boolean }) => void |
Also accepts Omit<HTMLInputAttributes, 'class' | 'value' | 'type'>.