# PhoneInput
Package: @mantine/core
Import: import { PhoneInput } from '@mantine/core';
Description: International phone number input with country selector

## Usage

`PhoneInput` is an international phone number input with a country selector
and per-country formatting. Set `defaultCountry` prop: without it, no country is selected
until the user picks one or types a dial code:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## PhoneInput with uncontrolled forms

Set `name` to submit the formatted phone number shown in the input. The raw number is available from `onChange`:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('phone'));
      }}
    >
      <PhoneInput
        name="phone"
        label="Phone"
        defaultCountry="us"
        defaultValue="+12025551234"
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

## Input features

PhoneInput component supports [Input](https://mantine.dev/core/input) and [Input.Wrapper](https://mantine.dev/core/input) components features and all input element props. PhoneInput documentation does not include all features supported by the component – see [Input](https://mantine.dev/core/input) documentation to learn about all available features.

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
       variant="default" size="sm" radius="md" label="Input label" withAsterisk={false} description="Input description" error=""
      placeholder="Your phone number"
      defaultCountry="us"
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Loading state

Set `loading` prop to display a loading indicator in the input:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      loading
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Controlled

`onChange` is called with the raw value and a details object with the formatted value and
the selected country:

```tsx
import { useState } from 'react';
import { Code, PhoneInput, PhoneInputCountryData } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('+1');
  const [country, setCountry] = useState<PhoneInputCountryData | null>(null);
  const [formattedValue, setFormattedValue] = useState('');

  return (
    <>
      <PhoneInput
        label="Phone number"
        placeholder="Your phone number"
        defaultCountry="us"
        value={value}
        onChange={(rawValue, details) => {
          setValue(rawValue);
          setFormattedValue(details.formattedValue);
          setCountry(details.country);
        }}
        renderFlag={(c) => (
          <img
            src={`https://hatscripts.github.io/circle-flags/flags/${c?.iso2 ?? 'xx'}.svg`}
            alt={c?.name ?? 'Select country'}
            style={{ width: 20, height: 20, borderRadius: 20 }}
          />
        )}
      />
      <Code block mt="md">
        {[
          `Raw value: ${value}`,
          `Formatted: ${formattedValue}`,
          `Country: ${country?.iso2 ?? '–'}`,
        ].join('\\n')}
      </Code>
    </>
  );
}
```


## Phone extensions

Set `withExtension` to allow extensions separated by `x`, for example `+12025551234x1234`.
The extension is included in `value` and available separately as `details.extension` in `onChange`.
With this prop, `details.extension` is an empty string when no extension digits are entered:

```tsx
import { useState } from 'react';
import { Code, PhoneInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('+12025551234x1234');

  return (
    <>
      <PhoneInput
        label="Office phone"
        description="Enter an extension after x"
        withExtension
        value={value}
        onChange={setValue}
      />
      <Code block mt="md">{value}</Code>
    </>
  );
}
```


## Preferred countries

Use `preferredCountries` prop to pin countries to the top of the dropdown:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      preferredCountries={['us', 'gb', 'ca']}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Filter countries

Use `onlyCountries` to show only specific countries or `excludeCountries` to hide some of them:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      onlyCountries={['us', 'gb', 'ca', 'au', 'de', 'fr']}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="de"
      excludeCountries={['us', 'gb']}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Virtualized dropdown

Use `virtualizer` to render countries as they scroll into view. Open the country picker to choose a dialing code:

```tsx
import { PhoneInput } from '@mantine/core';
import { VirtualList } from './VirtualList';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Enter your phone number"
      defaultCountry="us"
      virtualizer={VirtualList}
    />
  );
}
```


## Custom flags

Use `renderFlag` to display SVG flags from [country-flag-icons](https://www.npmjs.com/package/country-flag-icons):

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      renderFlag={(country) =>
        country ? (
          <img
            src={`https://purecatamphetamine.github.io/country-flag-icons/3x2/${country.iso2.toUpperCase()}.svg`}
            alt=""
            width={21}
            height={14}
            loading="lazy"
          />
        ) : '🌐'
      }
    />
  );
}
```


## Searchable

Country search is enabled by default. Set `searchable={false}` to disable it:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      searchable={false}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Country auto-detection

Set `withCountryAutoDetect` to switch the country as the user types a dial code.
It also detects area codes, such as `+1 204` for Canada:

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Type +44 to switch to UK"
      defaultCountry="us"
      withCountryAutoDetect
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Shared dial codes

Countries sharing a dial code are selected by area code and priority by default.
Use `resolveCountry` to choose one by ISO2 code, or return `undefined` to keep the default:

```tsx
<PhoneInput
  defaultCountry="ru"
  withCountryAutoDetect
  resolveCountry={(value, countries) =>
    value.startsWith('+77') && countries.some((country) => country.iso2 === 'kz') ? 'kz' : undefined
  }
/>
```

## National prefixes

`PhoneInput` removes known trunk prefixes from pasted national numbers. For example, pasting
`8 999 123-45-67` with Russia selected produces `+79991234567`. Clearing the input emits `''`.

In an empty international input, a typed leading trunk prefix is also removed.
Typing an explicit dial code, such as `+7`, preserves the national digits that follow in both `"auto"` and `"strip"` modes.

Ambiguous digits typed after a prefilled dial code are preserved by default. Set `nationalPrefixBehavior="strip"`
when users should enter numbers in national form, or `"preserve"` to disable prefix removal.

With `"strip"`, unprefixed numbers use the selected country. Include `+` to enter another country's dial code:

```tsx
<PhoneInput defaultCountry="ru" nationalPrefixBehavior="strip" />
```

## Localization

Use `renderCountryOption` to change how countries are displayed in the dropdown,
for example to translate country names:

`getCountryLabel` returns the translated name of a country. It is used as the
country button label for screen readers and in the dropdown search, so users
can search by translated names. `searchPlaceholder` and `selectCountryLabel`
translate the search input placeholder and the button label shown before a
country is selected:

```tsx
import { PhoneInput } from '@mantine/core';

const COUNTRIES_ES: Record<string, string> = {
  us: 'Estados Unidos',
  gb: 'Reino Unido',
  es: 'España',
  mx: 'México',
  ar: 'Argentina',
};

function Demo() {
  return (
    <PhoneInput
      label="Número de teléfono"
      placeholder="Tu número de teléfono"
      defaultCountry="es"
      onlyCountries={['us', 'gb', 'es', 'mx', 'ar']}
      nothingFoundMessage="No se encontraron países"
      searchPlaceholder="Buscar países"
      selectCountryLabel="Seleccionar país"
      getCountryLabel={(country) => COUNTRIES_ES[country.iso2] ?? country.name}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country ? COUNTRIES_ES[country.iso2] ?? country.name : 'Seleccionar país'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
      renderCountryOption={(country) => (
        <span style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
          <img
            src={`https://hatscripts.github.io/circle-flags/flags/${country.iso2}.svg`}
            alt={COUNTRIES_ES[country.iso2] ?? country.name}
            style={{ width: 20, height: 20, borderRadius: 20 }}
          />
          <span style={{ flex: 1 }}>{COUNTRIES_ES[country.iso2] ?? country.name}</span>
          <span style={{ opacity: 0.5, fontSize: 'var(--mantine-font-size-xs)' }}>
            +{country.dialCode}
          </span>
        </span>
      )}
    />
  );
}
```


## Dropdown position

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Disabled state

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      defaultValue="+12025551234"
      disabled
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Read only

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      defaultValue="+12025551234"
      readOnly
      renderFlag={(country) => (
        <img
          src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
          alt={country?.name ?? 'Select country'}
          style={{ width: 20, height: 20, borderRadius: 20 }}
        />
      )}
    />
  );
}
```


## Error state

```tsx
import { PhoneInput } from '@mantine/core';

function Demo() {
  return (
    <>
      <PhoneInput
        label="Boolean error"
        placeholder="Your phone number"
        defaultCountry="us"
        error
        renderFlag={(country) => (
          <img
            src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
            alt={country?.name ?? 'Select country'}
            style={{ width: 20, height: 20, borderRadius: 20 }}
          />
        )}
      />
      <PhoneInput
        mt="md"
        label="With error message"
        placeholder="Your phone number"
        defaultCountry="us"
        error="Invalid phone number"
        renderFlag={(country) => (
          <img
            src={`https://hatscripts.github.io/circle-flags/flags/${country?.iso2 ?? 'xx'}.svg`}
            alt={country?.name ?? 'Select country'}
            style={{ width: 20, height: 20, borderRadius: 20 }}
          />
        )}
      />
    </>
  );
}
```



#### Props

**PhoneInput props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| comboboxProps | ComboboxProps | - | Props passed down to the underlying Combobox component |
| defaultCountry | string | - | Default country ISO2 code, e.g. "us" |
| defaultValue | string | - | Uncontrolled default value |
| description | React.ReactNode | - | Contents of `Input.Description` component. If not set, description is not displayed. |
| descriptionProps | InputDescriptionProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Description` component |
| disabled | boolean | - | Sets `disabled` attribute on the `input` element |
| dropdownOpened | boolean | - | Controlled dropdown opened state |
| error | React.ReactNode | - | Contents of `Input.Error` component. If not set, error is not displayed. |
| errorProps | InputErrorProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Error` component |
| excludeCountries | string[] | - | Hide these countries, ISO2 codes |
| getCountryLabel | (country: PhoneInputCountryData) => string | - | Returns a localized country name, used as the country button `aria-label` and matched in search in addition to the English name |
| inputContainer | (children: ReactNode) => ReactNode | (children) => children | Render function to wrap the input element. Useful for adding tooltips, popovers, or other wrappers around the input. |
| inputSize | string | - | HTML `size` attribute for the input element (number of visible characters) |
| inputWrapperOrder | ("input" \| "label" \| "description" \| "error")[] | ['label', 'description', 'input', 'error'] | Controls order and visibility of wrapper elements. Only elements included in this array will be rendered. |
| international | boolean | true | Show +dialCode in input |
| label | React.ReactNode | - | Contents of `Input.Label` component. If not set, label is not displayed. |
| labelProps | InputLabelProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Label` component |
| leftSection | React.ReactNode | - | Content section displayed on the left side of the input |
| leftSectionPointerEvents | React.CSSProperties["pointerEvents"] | 'none' | Sets `pointer-events` styles on the `leftSection` element. Use `'all'` when section contains interactive elements (buttons, links). |
| leftSectionProps | React.ComponentProps<"div"> | - | Props passed down to the `leftSection` element |
| leftSectionWidth | React.CSSProperties["width"] | - | Left section width, used to set `width` of the section and input `padding-left`, by default equals to the input height |
| loaderProps | LoaderProps | - | Props passed down to the `Loader` component displayed when `loading` prop is set |
| loading | boolean | false | Displays loading indicator in the left or right section |
| loadingPosition | "left" \| "right" | 'right' | Position of the loading indicator |
| maxDropdownHeight | string \| number | 250 | Maximum dropdown height in px |
| nationalPrefixBehavior | "auto" \| "strip" \| "preserve" | 'auto' | Handling of national trunk prefixes: 'auto' preserves ambiguous typed digits, 'strip' removes a typed prefix, 'preserve' disables prefix removal (the mask still applies) |
| nothingFoundMessage | React.ReactNode | - | Message displayed when no countries match the search query |
| onChange | (rawValue: string, details: PhoneInputChangeDetails) => void | - | Called when value changes |
| onCountryChange | (country: PhoneInputCountryData) => void | - | Called when selected country changes |
| onDropdownClose | () => void | - | Called when dropdown closes |
| onDropdownOpen | () => void | - | Called when dropdown opens |
| onlyCountries | string[] | - | Only show these countries, ISO2 codes |
| pointer | boolean | false | Determines whether the input should use the theme cursor type. Use when input acts as a button-like trigger (e.g., `component="button"` for Select/DatePicker). |
| preferredCountries | string[] | - | Countries pinned to top of dropdown with separator, ISO2 codes |
| radius | MantineRadius \| number | theme.defaultRadius | Key of `theme.radius` or any valid CSS value to set `border-radius`, numbers are converted to rem |
| renderCountryOption | (country: PhoneInputCountryData) => ReactNode | - | Custom renderer for country dropdown options |
| renderFlag | (country: PhoneInputCountryData \| null) => ReactNode | - | Custom flag renderer for country selector button and dropdown options, receives null when no country is selected |
| required | boolean | false | Adds required attribute to the input and a red asterisk on the right side of label |
| resolveCountry | ((rawValue: string, countries: PhoneInputCountryData[]) => string) \| undefined | - | Selects a country by ISO2 code when multiple countries share the detected dial code; return undefined to use the default area-code and priority detection |
| rightSection | React.ReactNode | - | Content section displayed on the right side of the input |
| rightSectionPointerEvents | React.CSSProperties["pointerEvents"] | 'none' | Sets `pointer-events` styles on the `rightSection` element. Use `'all'` when section contains interactive elements (buttons, links). |
| rightSectionProps | React.ComponentProps<"div"> | - | Props passed down to the `rightSection` element |
| rightSectionWidth | React.CSSProperties["width"] | - | Right section width, used to set `width` of the section and input `padding-right`, by default equals to the input height |
| scrollBehavior | ScrollBehavior | 'instant' | `behavior` passed down to `element.scrollIntoView` when options are scrolled into view with keyboard navigation |
| searchPlaceholder | string | 'Search countries' | Placeholder of the search input in the dropdown |
| searchable | boolean | true | Enable search in country dropdown |
| selectCountryLabel | string | 'Select country' | `aria-label` of the country button when no country is selected |
| size | MantineSize | 'sm' | Controls input `height`, horizontal `padding`, and `font-size` |
| success | React.ReactNode | - | Contents of `Input.Success` component. If not set, success is not displayed. |
| successProps | InputSuccessProps & DataAttributes & PlaceholderPolymorphicProps | - | Props passed down to the `Input.Success` component |
| value | string | - | Controlled value — raw digits with + prefix, e.g. "+12025551234", with an optional "x1234" suffix when `withExtension` is enabled |
| virtualizer | ComponentType<ComboboxVirtualizerProps> | - | Component that renders visible countries and manages scrolling in place of the dropdown ScrollArea |
| withAsterisk | boolean | false | If set, the required asterisk is displayed next to the label. Overrides `required` prop. Does not add required attribute to the input. |
| withChevron | boolean | false | Display chevron in the country button |
| withCountryAutoDetect | boolean | false | Auto-detect country from typed dial code digits |
| withErrorStyles | boolean | true | Determines whether the input should have red border and red text color when the `error` prop is set |
| withExtension | boolean | false | Allow a phone extension separated by "x", e.g. "+12025551234x1234" |
| withSuccessStyles | boolean | true | Determines whether the input should have green border when the `success` prop is set |
| wrapperProps | WrapperProps | - | Props passed down to the root element |


#### Styles API

PhoneInput component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**PhoneInput selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| wrapper | .mantine-PhoneInput-wrapper | Root element of the Input |
| input | .mantine-PhoneInput-input | Input element |
| section | .mantine-PhoneInput-section | Left and right sections |
| bottomSection | .mantine-PhoneInput-bottomSection | Bottom section element, rendered inside the input border at the bottom |
| root | .mantine-PhoneInput-root | Root element |
| childrenWrapper | .mantine-PhoneInput-childrenWrapper | Container of `children`, rendered only when `withBlockChildren` prop is set |
| label | .mantine-PhoneInput-label | Label element |
| required | .mantine-PhoneInput-required | Required asterisk element, rendered inside label |
| description | .mantine-PhoneInput-description | Description element |
| error | .mantine-PhoneInput-error | Error element |
| success | .mantine-PhoneInput-success | Success element |
| countryButton | .mantine-PhoneInput-countryButton | Country selector button in leftSection |
| countryButtonFlag | .mantine-PhoneInput-countryButtonFlag | Flag wrapper inside country button |
| countryButtonCode | .mantine-PhoneInput-countryButtonCode | Country ISO2 code text inside country button |
| dropdown | .mantine-PhoneInput-dropdown | Combobox dropdown |
| search | .mantine-PhoneInput-search | Search input in dropdown |
| countryOption | .mantine-PhoneInput-countryOption | Country option content wrapper in dropdown |
| optionName | .mantine-PhoneInput-optionName | Country name text in option |
| optionDialCode | .mantine-PhoneInput-optionDialCode | Dial code text in option |
| divider | .mantine-PhoneInput-divider | Divider between preferred and other countries |
