--- name: phone-input-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit PhoneInput for international phone entry with country selection, libphonenumber details, hidden E.164 form value, native validation, validation status, and compound country picker slots. metadata: component_version: "1.3.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux select-usage app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/molecules/phone-input.tsx libs/ui/src/tokens/components/molecules/_phone-input.css libs/ui/stories/molecules/phone-input.stories.tsx" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit PhoneInput Usage Use PhoneInput for telephone fields. Do not compose country Select and Input manually. ## Shared field contract Use `sm`, `md` (default), or `lg`. The prefix uses a compact, component-token width so the phone number retains useful space, including at large size. `PhoneInput.StatusText` generates a unique ID for each mounted message and merges all messages with the input's existing description; errors also register an error-message association. Error, warning and success messages keep their icons. The country picker mounts its own visually hidden label so its accessible name never points at an absent Select label. `readOnly` preserves focus, text selection/copy and the hidden form value while blocking both number and country mutations. The control uses the shared readonly surface and a text-selection cursor on the number; disabled remains the stronger state. Use a distinct “Read-only” example rather than treating it as disabled. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `PhoneInput`. **Use it when** - Any telephone field, with country code selection and formatting. **Use something else when** | Need | Use instead | | --- | --- | | Other numeric identifiers | FormInput | **Do** - Default the country from the store/locale; allow changing it. - Validate on blur with a message showing the expected format. - Set `autoComplete="tel"`. **Don't** - Compose a country Select and an Input by hand. - Reject valid numbers because of spaces or dashes — normalise instead. **Copy and states** - Label `Phone`; help text says why you need it (`For delivery updates only.`). **Behaviour (from the UX spec)** - A valid format (`isValid`) is not a verified number; never label it "verified". - Changing the country keeps the typed digits; pasting `+420 …` switches the country to match. - Default placeholder and country names are English; pass localized `placeholder` and `countries`. **Figma → code** | Figma | Code | | --- | --- | | `state=error` / `success` / `warning` | `validateStatus` | | `state=disabled` | `disabled` | | `state=readonly` | `readOnly` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/PhoneInput → UX guidelines*. ## Setup ```tsx import { PhoneInput } from "@techsio/ui-kit/molecules/phone-input" Phone ``` Supported root props: ```text countries, country/defaultCountry, value/defaultValue name, countryName, form required, disabled, readOnly, nativeValidation, nativeValidationMessage validateStatus: default | error | success | warning onValueChange(details), onCountryChange(details) size: sm | md | lg ``` ## Core Patterns ### Use the compound parts Use `Label`, `Control`, `CountryPicker` or lower-level country slots, and `Input`. ### Consume structured details `onValueChange` gives `value`, `e164`, `country`, `callingCode`, `nationalNumber`, `isPossible`, and `isValid`. ### Let PhoneInput own country selection It uses Select internally for countries and syncs country from typed values. ## Common Mistakes ### HIGH Native tel input only Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/phone-input.tsx ### HIGH Manual country select wrapper Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/phone-input.tsx ### HIGH Inline validation styling Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_phone-input.css ## Validation Commands ```sh rg -P -n "type=\"tel\"|]*className=.*(border-|bg-|text-|p-)" apps rg -U -P -n "]*validateStatus=\"(danger|invalid)\"" apps ``` ### Editing, reset and refs Formatting preserves logical digit positions for middle insertion, deletion, replacement and international paste. Deleting beside a generated separator removes the adjacent digit rather than trapping the caret. IME composition is left unformatted until composition ends. An uncancelled native form reset restores uncontrolled number/country defaults together, including explicit `form` association. Controlled props remain owned by the parent. Reset is not a user edit and does not emit change callbacks. `PhoneInput.Input` supports React 19 callback-ref cleanup and legacy/object refs. The shared focus outline appears only while a descendant is focus-visible; validation borders remain persistent. Neutral interaction surfaces preserve prefix/placeholder contrast, and highlighted/selected country metadata inherits the option foreground.