Phone input
Country-aware phone drafts with national formatting and E.164 output.
Installation
Import the component in your screen:
import { PhoneInput } from '@commenda/pathfinder/phone-input';Load the stylesheet once in your app root, after host styles:
import '@commenda/pathfinder/styles.css';Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See installation for the workspace setup.
Country artwork loads through an isolated lazy module; other field entry points do not import phone metadata or flags.
API reference
| Prop | Type | Behavior |
|---|---|---|
valueConditional | PhoneValueView fields | One is required; the app supplies its initial jurisdiction |
defaultValueConditional | PhoneValueView fields | One is required; the app supplies its initial jurisdiction |
onValueChangeConditional | (
value: PhoneValue
) => void | Required in controlled mode; receives the editable text |
countryConfig | ObjectView fields | All metadata-supported countries unless constrained |
onValidationChange | (
details: PhoneValueDetails
) => void | Normalized details when validation changes |
labelConditional | string | Visible field label. Supply an accessible name when it is omitted. |
hideLabel | boolean | Visually hide the label while preserving its accessible name. |
aria-labelConditional | string | Accessible name when the field has no visible label. |
requiredConditional | boolean | Mark the field as required. See validation guidance for the component. |
labelConfig | ObjectView fields · 2 shapes | Choose either optionalLabel or help, never both. never excludes the other field. |
description | string | Supporting guidance associated with the field. |
errorConfig | ObjectView fields | Validation message and when it becomes visible. |
disableConfig | DisableConfigView fields | Disabled state with an optional explanation. |
valueObject fields
| Field | Type | Requirement |
|---|---|---|
country | CountryCode | Required |
number | string | Required |
defaultValueObject fields
| Field | Type | Requirement |
|---|---|---|
country | CountryCode | Required |
number | string | Required |
countryConfigObject fields
| Field | Type | Requirement |
|---|---|---|
allowedCountries | readonly CountryCode[] | Optional |
labelConfigObject fields
Choose one of these 2 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
optionalLabel | string | Required |
Do not supply: help.
Option 2
| Field | Type | Requirement |
|---|---|---|
help | string | Required |
Do not supply: optionalLabel.
errorConfigObject fields
| Field | Type | Requirement |
|---|---|---|
message | string | Required |
reveal | "after-blur" | "immediate" | Optional |
disableConfigObject fields
| Field | Type | Requirement |
|---|---|---|
isDisabled | boolean | Required |
reason | string | Optional |
Shared presentation, native input attributes, and readOnly follow Input. Disabled fields do not submit. Read-only values remain copyable and valid values submit. CountryCode is a phone metadata type, with no application enum dependency.
Countries
Search by country name or calling code. Switching country preserves entered text for review. International input updates country only when metadata resolves it unambiguously; a partial shared dial code such as +1 does not guess US or Canada.
Validation and submission
Typing preserves spaces, brackets, dashes, and incomplete text. Valid numbers format nationally on blur. onValidationChange supplies E.164 separately; store the draft and canonical value according to application needs. E.164 excludes extensions; if your workflow uses extensions, retain the draft or collect an extension separately. Phone metadata validity is not proof that a number exists or belongs to a person; ownership verification is application-owned.
States
Read composite field rules.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Phones
- PHONE-001: One 28px border/focus ring, 16px country flag, 13px dial code, 12px chevron, and searchable country selector. Center artwork in flex containers, never through inline SVG baselines.
- PHONE-002: Preserve editable text; format valid numbers nationally on blur. Validate with libphonenumber metadata and expose E.164 separately. The app owns verification and storage.
- PHONE-003: The application must supply its jurisdiction. Resolve international input only when unambiguous; do not infer a country from shared partial dial codes or browser locale.
- PHONE-004: Country switches preserve typed text for review. Allowed-country policy comes from the application, and restricted countries cannot yield a valid canonical form value.
Shared rules
Labels activate the first input. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.