PhoneNumberField

A phone number input widget that combines country dialing-code selection, phone number formatting, and validation feedback in one reusable field. It uses @adaptavant/libphonenumber for parsing and as-you-type formatting, and exposes label, placeholder, country search, error, warning, size, and variant props so product surfaces can keep phone entry consistent without rebuilding the same field logic. variant="subtle" renders the inline ghost treatment.

View in Storybook View in Playroom API Reference

Quick Start

Installation: npm install @adaptavant/phone-number-field
Import: import { PhoneNumberField } from '@adaptavant/phone-number-field';

Key Features

The PhoneNumberField component provides a complete phone entry experience:

Country selection — Shows a dialing-code dropdown with searchable country options.
As-you-type formatting — Formats the phone number as the user enters digits based on the selected country.
Initial value sync — Accepts e164, countryCode, and countryName through phoneNumberProps so existing contact data can hydrate the field.
Validation feedback — Supports error and warning states through isErrorField, isWarningField, and errorMessage.
Localized labels — Lets consumers customize the country dropdown label, search copy, input label, and placeholder.
Change callbacks — Emits structured phone data when the number changes or the country is selected.

Basic Usage

Pass phoneNumberProps to initialize the selected country and phone number. The e164 value is formatted for display using the supplied country information.

Country

Phone number

return (
	<PhoneNumberField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			e164: '+15034524242',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
			},
		}}
	/>
);

View in Playroom

Inline variant

Set variant="subtle" for the inline ghost treatment. Both controls stay borderless at rest, pick up a neutral background on hover, and show a border on focus. size still applies. Field messages stay on the phone input.

return (
	<PhoneNumberField
		errorMessage="Enter a valid phone number"
		phoneNumberProps={{
			countryCode: 'AU',
			countryName: 'Australia',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
				placeholder: 'Phone number',
			},
		}}
		variant="subtle"
	/>
);

View in Playroom

Empty Field

Omit e164 when the field should start empty. Provide the country details to control which dialing code is selected by default.

Country

Phone number

return (
	<PhoneNumberField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
				placeholder: 'Enter your phone number',
			},
		}}
	/>
);

View in Playroom

With Custom Labels

Use nested countryCodeProps and inputProps to customize field labels, search text, fallback copy, and the phone input placeholder.

Dialing code

Mobile number

return (
	<PhoneNumberField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			countryCodeProps: {
				label: 'Dialing code',
				searchPlaceholder: 'Find a country',
				searchResultFallback: 'No matching country',
			},
			inputProps: {
				label: 'Mobile number',
				placeholder: 'Add mobile number',
			},
		}}
	/>
);

View in Playroom

With Error Message

Set isErrorField with errorMessage when the field should display an error state. The same errorMessage text is also used for warning states when isWarningField is set.

Country

Phone number

Enter a valid phone number

return (
	<PhoneNumberField
		errorMessage="Enter a valid phone number"
		isErrorField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			e164: '+1503',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
			},
		}}
	/>
);

View in Playroom

Large Size

Use size="large" when the phone field needs to align with larger form controls.

Country

Phone number

return (
	<PhoneNumberField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			e164: '+15034524242',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
			},
		}}
		size="large"
	/>
);

View in Playroom

formatPhoneNumberByLocation — National format

Formats a phone number into national format when the number's country matches the user's geolocation.

US number · US geolocation → (646) 980-4127UK number · GB geolocation → 020 7183 8750

return (
	<Box className="flex flex-col gap-3">
		<Text className="text-body-14">
			US number · US geolocation →{' '}
			{formatPhoneNumberByLocation('+16469804127', 'US')}
		</Text>
		<Text className="text-body-14">
			UK number · GB geolocation →{' '}
			{formatPhoneNumberByLocation('+442071838750', 'GB')}
		</Text>
	</Box>
);

View in Playroom

formatPhoneNumberByLocation — International format

Formats a phone number into international format when the number's country does not match the user's geolocation.

US number · GB geolocation → +1 646-980-4127UK number · US geolocation → +44 20 7183 8750

return (
	<Box className="flex flex-col gap-3">
		<Text className="text-body-14">
			US number · GB geolocation →{' '}
			{formatPhoneNumberByLocation('+16469804127', 'GB')}
		</Text>
		<Text className="text-body-14">
			UK number · US geolocation →{' '}
			{formatPhoneNumberByLocation('+442071838750', 'US')}
		</Text>
	</Box>
);

View in Playroom

formatPhoneNumberByLocation — Edge cases

Empty or invalid inputs are returned unchanged. Typical usage is displaying a stored E.164 number in a UI based on the user's location.

Empty input → ""Invalid input → notvalid(646) 980-4127

function ContactCard({ phone, userCountry }) {
	const displayPhone = formatPhoneNumberByLocation(phone, userCountry);
	return <Text className="text-body-14">{displayPhone}</Text>;
}

return (
	<Box className="flex flex-col gap-3">
		<Text className="text-body-14">
			Empty input → "{formatPhoneNumberByLocation('', 'US')}"
		</Text>
		<Text className="text-body-14">
			Invalid input → {formatPhoneNumberByLocation('notvalid', 'US')}
		</Text>
		<ContactCard phone="+16469804127" userCountry="US" />
	</Box>
);

View in Playroom

With End Adornment

Use inputProps.adornmentEnd to render trailing content inside the phone number input, such as a copy affordance. The node sits inside the input's focus container, so it shares the field's hover surface instead of being a separate target. Styling, interactivity, and accessibility of the node are the consumer's responsibility.

Country

Phone number

return (
	<PhoneNumberField
		phoneNumberProps={{
			countryCode: 'US',
			countryName: 'United States',
			e164: '+15034524242',
			countryCodeProps: {
				label: 'Country',
			},
			inputProps: {
				label: 'Phone number',
				adornmentEnd: (
					<IconButton
						aria-label="Copy phone number"
						className="me-2"
						icon={ClipboardCopyIcon}
						size="small"
						variant="neutralTertiary"
					/>
				),
			},
		}}
	/>
);

View in Playroom

API Reference