PhoneInput

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:

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:

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 and Input.Wrapper component features and all input element props. The PhoneInput documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Input description

Variant
Size
Radius
import { PhoneInput } from '@mantine/core';
function Demo() {
  return (
    <PhoneInput
      label="Input label"
      description="Input description"
      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:

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:

Raw value: +1
Formatted: 
Country: –
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:

Enter an extension after x

+12025551234x1234
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:

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:

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 }}
        />
      )}
    />
  );
}

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:

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:

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:

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:

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:

<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:

<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:

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

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

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

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

Invalid phone number

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 }}
          />
        )}
      />
    </>
  );
}

Success state

Looks good!

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

function Demo() {
  return (
    <PhoneInput
      label="Phone number"
      placeholder="Your phone number"
      defaultCountry="us"
      success="Looks good!"
      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 }}
        />
      )}
    />
  );
}

Styles API

PhoneInput supports the Styles API; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.

Component Styles API

Hover or focus a selector to highlight its elements

/*
 * Hover or focus a selector
 * to outline its elements
 */

Get element ref

import { useRef } from 'react';
import { PhoneInput } from '@mantine/core';

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <PhoneInput ref={ref} />;
}

Accessibility

If PhoneInput is used without the label prop, it will not be announced properly by screen readers:

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

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <PhoneInput />;
}

Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:

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

// Accessible input – it has aria-label
function Demo() {
  return <PhoneInput aria-label="My input" />;
}

If the label prop is set, the input will be accessible and it is not required to set aria-label:

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

// Accessible input – it has associated label element
function Demo() {
  return <PhoneInput label="My input" />;
}