PhoneInput

The PhoneInput component is a specialized input field for international phone numbers that offers country selection and automatic formatting. It includes a searchable dropdown with country flags and applies region-specific formatting masks.

tsx

import { PhoneInput } from "@arkyn/components";

Basic usage

Basic usage of an input requires a name property.

tsx

<PhoneInput name="phone" />

Country

The component allows you to set a default country using the defaultCountry property (it will only take effect when a phone number is not available in the defaultValue property), using the country's ISO code (e.g., "BR" for Brazil, "US" for the USA).

Standardization

The component can automatically detect the country based on the number entered, without the need to specify defaultCountry. However, the number must begin with the country code (e.g., +55 for Brazil, +1 for the USA), following the international E.164 format. The phone number format should be: +[countryCode]-[countryPrefixCode][countryNumber].

Phone

tsx

<PhoneInput
  name="auto-detect"
  label="Phone"
  defaultValue="+55 11999999999" // Brazil
/>

Country search

The component offers search functionality to make it easier to select the desired country.

Phone with custom search

tsx

<PhoneInput
  name="phone-search"
  label="Phone with custom search"
  searchCountryPlaceholder="Enter the country name..."
  notFoundCountryText="Country not found"
/>

Sizes

The available sizes are md and lg, following the pattern for other input components.

Phone (medium)

Phone (large)

tsx

<PhoneInput
  name="phone-md"
  label="Phone (medium)"
  size="md"
/>
<PhoneInput
  name="phone-lg"
  label="Phone (large)"
  size="lg"
/>

Variants

The available variants are solid and outline, providing different visual styles.

Phone (solid)

Phone (outline)

tsx

<PhoneInput
  name="phone-solid"
  label="Phone (solid)"
  variant="solid"
/>
<PhoneInput
  name="phone-outline"
  label="Phone (outline)"
  variant="outline"
/>

Input states

The component supports different states, such as disabled, read-only, and loading.

Disabled input

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

Disabled phone

tsx

<PhoneInput
  name="phone-disabled"
  label="Disabled phone"
  defaultValue="+1-408 9876543"
  disabled
/>

Read-only input

The read-only state allows the user to view the field value but cannot edit it. Unlike the disabled state, the value can be selected and copied, and field data can be submitted via a form.

Phone

tsx

<PhoneInput
  name="phone-readonly-display"
  label="Phone"
  defaultCountry="GB"
  defaultValue="+44 2012345678"
  readOnly
  variant="outline"
/>

Loading state

The loading state displays a spinner and automatically disables input. The spinner appears on the left by default, or on the right if there is a rightIcon.

Validating phone number...

tsx

<PhoneInput
  name="phone-loading-value"
  label="Validating phone number..."
  defaultCountry="US"
  defaultValue="+1-408 0000000"
  isLoading
/>

Validation and errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.

Customizable Forms

For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

Phone

Invalid phone number

tsx

<PhoneInput
  name="phone-invalid"
  label="Phone"
  defaultCountry="BR"
  errorMessage="Invalid phone number"
  showAsterisk
/>

onChange callback

O callback onChange fornece o número formatado completo com código do país:

tsx

const handlePhoneChange = (formattedPhone: string) => {
  // formattedPhone: string - número formatado com código do país
  console.log("Número completo:", formattedPhone); // "+55 11999999999"

  // Use para salvar no estado ou enviar para API
  setPhoneNumber(formattedPhone);
};

<PhoneInput
  name="user-phone"
  label="Seu Telefone"
  defaultCountry="BR"
  onChange={handlePhoneChange}
/>;

Properties

name - string (required) Field name for form manipulation and identification

label - string Label text to display above the input

showAsterisk - boolean Whether to display an asterisk in the label for required fields

errorMessage - string Error message to display below the input

size - "md" | "lg" (default: "md") Input size variant

variant - "solid" | "outline" (default:solid`) Visual variant of the input

defaultValue - string Default phone number value

defaultCountry - string ISO code of the default country to select

disabled - boolean (default: false) If the input is disabled

readOnly - boolean (default: false) If the input is read-only

isLoading - boolean (default: false) If the input is in the loading state

className - string Additional CSS classes for styling

id - string Optional unique identifier for the input

searchCountryPlaceholder - string (default: `Search Country``) Text Placeholder for the country search field

notFoundCountryText - string (default: "No country found") Text displayed when no country matches the search

onChange - (formattedPhone: string) => void Callback function called when the number changes, receives the value formatted with the country code

Other properties

All other standard HTML properties of <input> are also supported, except type (which is fixed as tel).

Notes

The component uses country data from @arkyn/templates
Country search is case-insensitive
Loading, disabled, and readOnly states affect both the input and the dropdown

On this page