PhoneField

PhoneField is a compound component that combines a masked phone input with a nested country-code Select.

Root API

PhoneField owns the phone input and country formatting model.

Prop	Type	Default
`value`	`string`	—
Controlled phone number, as the text of the input.
`defaultValue`	`string`	`''`
Initial phone number for uncontrolled usage. Defaults to `''`. Its country is selected unless `code` is set.
`onChangeValue`	`(value: string) => void`	—
Called with the phone number when it changes.
`code`	`CountryCode`	—
ISO 3166-1 alpha-2 country code used to determine the phone mask format. Example: 'US', 'RU', 'FR'.
`defaultCode`	`CountryCode`	`''`
ISO 3166-1 alpha-2 country code used to determine the phone mask format. Example: 'US', 'RU', 'FR'.
`onChangeCode`	`(code: CountryCode) => void`	—
ISO 3166-1 alpha-2 country code used to determine the phone mask format. Example: 'US', 'RU', 'FR'.
`strictMask`	`boolean`	`true`
If true, enforces the phone number mask strictly — only valid characters in the correct positions are allowed.
`size`	`TextFieldSize`	—
Visual size of the text field. Affects padding, font size, and overall height. 'sm': Compact input; 'md': Default; 'lg': Spacious layout
`ref`	`Ref<HTMLDivElement>`	—
Ref forwarded to wrapper element Useful for programmatic control, focus, or integration.
`error`	`boolean`	—
Shows the input in an error state.

Also accepts all <div> attributes.

Visible text input for the phone number.

Prop	Type	Default
`ref`	`Ref<HTMLInputElement>`	—
Ref forwarded to the underlying native `<input>` element.

Also accepts all <input> attributes.

Nested country-select family built around the same field state.

Prop	Type	Default
`size`	`SelectSize`	—
Visual size of the select control.
`variant`	`SelectVariant`	—
Visual style variant for the select control.
`disabled`	`boolean`	—
Whether the select is disabled. Prevents interaction and applies a disabled style.
`onChangeValue`	`(value: V \| undefined) => void`	—
Callback fired when an option is selected.
`ref`	`Ref<HTMLDivElement>`	—
Ref to the root element.
`readOnly`	`boolean`	—
If true, the select cannot be changed but remains focusable.
`typeahead`	`boolean`	`true`
Enables moving to an option by typing the start of its label.
`open`	`boolean`	—
Controls the open state of the Select dropdown. When provided, the Select becomes a controlled component and relies on this value to determine whether the listbox is open or closed.
`onChangeOpen`	`(open: boolean) => void`	—
Callback fired when the open state changes. Called with the next open state (`true` or `false`) whenever the Select is opened or closed by user interaction. Useful for synchronizing the Select state with external logic.
`defaultOpen`	`boolean`	—
Sets the initial open state of the Select when used in uncontrolled mode. Applied only on the first render and ignored afterward.

Also accepts all <div> attributes.

Also accepts all <select> attributes.

Prop	Type	Default
`ref`	`Ref<HTMLButtonElement>`	—
Ref to the underlying `<button>` element. Useful for focus management, positioning, and imperative access.

Also accepts all <button> attributes.

Prop	Type	Default
`placeholder`	`string`	—
Placeholder text shown when no option is selected. Displayed when the select value is empty or undefined. Once a value is selected, the placeholder is replaced by the selected option’s content.
`ref`	`Ref<HTMLSpanElement>`	—
Ref forwarded to the root span element.

Also accepts all <span> attributes.

Prop	Type	Default
`size`	`IconSize`	—
Predefined size token for the icon. Can be overridden by explicit width and height.
`ref`	`Ref<SVGSVGElement>`	—
Ref to the SVG element
`strokeWidth`	`number`	—
Stroke thickness for SVG lines and shapes (in px or pt).
`children`	`ReactNode`	—
Icon content (required). Accepts: icons from `~/icons`; custom inline SVG; third-party icon components (e.g. Lucide, Tabler)

Also accepts all HTML attributes.

Prop	Type	Default
`value`required	`CountryCode`	—
The value of this option, passed to the change callback when it is selected.
`label`	`string`	—
Plain text of this option for typeahead, used instead of the text of its content.
`children`	`ReactNode`	—
The content displayed for this option. Can include text, icons, or complex markup.
`size`	`OptionSize`	—
Size of the option for visual styling.
`disabled`	`boolean`	—
Disables the entire Option.
`ref`	`Ref<HTMLDivElement>`	—
Ref forwarded to the root div of the option.

Also accepts all <div> attributes.

Prop	Type	Default
`ref`	`Ref<HTMLDivElement>`	—
Ref to the listbox container element. Can be used for imperative access, for example measurements.

Also accepts all <div> attributes.

Advanced hook for custom wrappers and integrations.

Type	Definition	Notes
`PhoneFieldProps`	Root prop type	Main field integration surface.
`PhoneFieldInputProps`	Input part prop type	Number input behavior.
`PhoneFieldSelectProps`	Select root prop type	Nested country picker surface.