KQ-1163 · GLOBE/PHONE

Globe Phone

A phone number field whose country picker is a small orthographic globe: choosing a country turns it there the short way round on a spring derived from drift and scaled by spin, the country's pin drops onto the centre on recoil, and the dial code rolls digit by digit on glide. The globe also follows a horizontal drag 1:1 and a throw comes to rest on the country nearest where it would stop; the number formats for its country as it is typed and keeps its caret. Pressing the globe opens a searchable combobox and listbox whose highlight previews each country on the globe; arrows move, Enter chooses, Escape closes and turns it back, and Left/Right on the globe step east and west.

KQ-1163 · GLOBE/PHONE

Mobile number

Sign-in codes are texted here.

GB +44 · 0 of 10 digits

Open it on the Atelier stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/globe-phone

Props

label: string; default "Phone number"; What the number is for: the visible label and the input's accessible name.
value / defaultValue: string; default ""; Controlled or initial national number: digits only, without the country code.
onValueChange: (value: string, international: string) => void; default —; Fires with the digits and the full international number on every edit.
country / defaultCountry: string; default "GB"; Controlled or initial country, by ISO code.
onCountryChange: (code: string) => void; default —; Fires from the list, the throw or the arrow key that chose a country.
countries: PhoneCountry[]; default thirty, from Argentina to the United States; The countries on offer, each { code, name, dial, pattern, lat, lon, alias? }; # in a pattern is a digit.
spin: number; default 1; How fast the globe turns to a country, 0.3 to 1.5; the whir runs higher with it.
grid: boolean; default true; Draw the graticule: meridians and parallels every 30 degrees.
format: boolean; default true; Format the number for its country as it is typed; off keeps bare digits.
name: string; default —; The form field name; a hidden input carries the international number under it.
hint: string; default —; Helper text under the field, wired with aria-describedby.
error: string | null; default —; What is wrong, from the host: shown under the field, marked with aria-invalid, and announced once. A number short for its country is flagged on blur the same way.
required: boolean; default false; Marks the number input required.
sound: boolean; default false; Play the globe's whir while it turns and the ticks of countries passing and dial digits landing. Nothing plays, and no audio context exists, unless this is on; sounds only ever answer the visitor.
disabled: boolean; default false; Disables the field and dims it.
className: string; default —; Merged onto the root element's classes.

Prop	Type	Default	Description
label	string	"Phone number"	What the number is for: the visible label and the input's accessible name.
value / defaultValue	string	""	Controlled or initial national number: digits only, without the country code.
onValueChange	(value: string, international: string) => void	—	Fires with the digits and the full international number on every edit.
country / defaultCountry	string	"GB"	Controlled or initial country, by ISO code.
onCountryChange	(code: string) => void	—	Fires from the list, the throw or the arrow key that chose a country.
countries	PhoneCountry[]	thirty, from Argentina to the United States	The countries on offer, each { code, name, dial, pattern, lat, lon, alias? }; # in a pattern is a digit.
spin	number	1	How fast the globe turns to a country, 0.3 to 1.5; the whir runs higher with it.
grid	boolean	true	Draw the graticule: meridians and parallels every 30 degrees.
format	boolean	true	Format the number for its country as it is typed; off keeps bare digits.
name	string	—	The form field name; a hidden input carries the international number under it.
hint	string	—	Helper text under the field, wired with aria-describedby.
error	string \| null	—	What is wrong, from the host: shown under the field, marked with aria-invalid, and announced once. A number short for its country is flagged on blur the same way.
required	boolean	false	Marks the number input required.
sound	boolean	false	Play the globe's whir while it turns and the ticks of countries passing and dial digits landing. Nothing plays, and no audio context exists, unless this is on; sounds only ever answer the visitor.
disabled	boolean	false	Disables the field and dims it.
className	string	—	Merged onto the root element's classes.