Phone Input

Use catnip-input-phone when a user enters a phone number that should be stored with an explicit country code. For arbitrary text, use Input. For numeric quantities, use Number Input. For choosing a country without entering a phone number, use Dropdown.

Behaviour

• State: Bind model-value / .modelValue as { countryCode, countryIsoCode, phoneNumber } | null. countryCode is the dial prefix, while countryIsoCode keeps countries with shared prefixes distinct. The local phoneNumber is stored as digits only; Catnip does not validate it by country.
• Defaults: Use default-country-code when the product context knows the expected country. Keep the default auto for account/profile forms where browser locale is a reasonable hint.
• International entry: Users can type or paste +47..., +44..., and similar values. The component selects the longest matching dial code and moves the remaining digits into the local number field.
• Filtering: The country picker supports country names, ISO codes, and dial codes. The built-in search row is sticky inside the list; avoid adding a separate country search field around it.

Composition

• Labels: label prop or label slot; label.action / label.suffix match Input.
• Supporting text: Pass supporting-text on the host. Use it for format hints or validation messages such as “Include your mobile number.”
• Clear button: Enable show-clear-button when phone input is optional or frequently edited. Clearing removes the model value while keeping the current country selection visible.

Validation

V1 does not include libphonenumber or country-aware validation. Validate in the product layer when exact formatting or reachability matters, then set intent="danger" and supporting-text for errors.

Best practices

• Prefer a visible label such as Phone number over relying on placeholder copy.
• Do not store only the dial code; keep countryIsoCode with countryCode so countries sharing a dial code remain distinguishable.
• Do not use the phone field for one-time passcodes, PINs, or numeric IDs; those are text inputs with different semantics.