MUI Tel Input

https://viclafouch.github.io/mui-tel-input
Admin
MUI Tel Input is a phone number input component for React applications built with MUI and...
Tokens:4,753
Snippets:40
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install MUI Tel Input

Source: https://viclafouch.github.io/mui-tel-input/docs/getting-started

Run this command to install the package in your project.

```bash
npm install mui-tel-input
```

--------------------------------

### Style MuiTelInput with styled-components/emotion

Source: https://viclafouch.github.io/mui-tel-input/docs/css

Integrate MuiTelInput with styled-components or Emotion to apply custom styles directly to the component's elements. This example targets the input field.

```jsx
import { styled } from 'styled-components' // or emotion
import { MuiTelInput } from 'mui-tel-input'

const MuiTelInputStyled = styled(MuiTelInput)`
  & input {
    color: red;
  }
`

function MyComponent() {
  return <MuiTelInputStyled />
}
```

--------------------------------

### Style MuiTelInput Flag with styled-components/emotion and classes

Source: https://viclafouch.github.io/mui-tel-input/docs/css

Customize specific parts of the MuiTelInput component, like the flag container, by using the exported `classes` object with styled-components or Emotion. This example applies a grayscale filter to the flag image.

```jsx
import { styled } from 'styled-components' // or emotion
import { MuiTelInput, classes } from 'mui-tel-input'

const WithStyledFlag = styled(MuiTelInput)`
  .${classes.flagContainer} > img {
    filter: grayscale(100%);
    width: 20px;
  }
`

function MyComponent() {
  return <WithStyledFlag />
}
```

--------------------------------

### Handling Phone Number Changes

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use the `onChange` prop to get the updated phone number string and related information. The callback provides the new value and an object with details like country, national number, etc.

```javascript
const handleChange = (value, info) => {
  /**
  value: "+33123456789"
  info: {
    countryCallingCode: "33",
    countryCode: "FR",
    nationalNumber: "123456789",
    numberType: "FIXED_LINE_OR_MOBILE",
    numberValue: "+33123456789",
    reason: "input"
  }
  **/
}

<MuiTelInput onChange={handleChange} />
```

--------------------------------

### Customizing MUI Menu Props

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Pass `MenuProps` to customize the underlying MUI Menu component. For example, `disableAutoFocusItem: true` prevents the menu from automatically focusing on the first item.

```jsx
<MuiTelInput MenuProps={{ disableAutoFocusItem: true }} />
```

--------------------------------

### Using MuiTelInput with TypeScript

Source: https://viclafouch.github.io/mui-tel-input/docs/typescript

Demonstrates importing necessary types and implementing the MuiTelInput component with typed props and state.

```typescript
import React from 'react'  
import {  
  MuiTelInput,  
  type MuiTelInputProps,  
  type MuiTelInputCountry,  
  type MuiTelInputInfo,  
  type MuiTelInputContinent,  
  type MuiTelInputFlagElement,  
  type MuiTelInputReason  
} from 'mui-tel-input'  
  
const MyComponent = () => {  
  const [value, setValue] = React.useState<string>('')  
  
  const handleChange = (newValue: string, info: MuiTelInputInfo) => {  
    setValue(newValue)  
  }  
  
  const continents: MuiTelInputContinent[] = ['EU']  
  const excludedCountries: MuiTelInputCountry[] = ['FR']  
  // It's also the return value for the `getFlagElement` function prop  
  const unknownFlag: MuiTelInputFlagElement = <img src=".." />  
  
  return (  
    <MuiTelInput  
      value={value}  
      onChange={handleChange}  
      continents={continents}  
      unknownFlagElement={unknownFlag}  
      excludedCountries={excludedCountries}  
    />  
  )  
}  
```

--------------------------------

### MuiTelInput Styling API

Source: https://viclafouch.github.io/mui-tel-input/docs/css

Overview of the styling interface for MuiTelInput, including the className prop and exported class constants.

```APIDOC
## MuiTelInput Styling

### Description
Customize the appearance of the MuiTelInput component using the `className` prop or by targeting specific global class names. Classes are also exported as a `classes` object for stable reference in CSS-in-JS.

### Props
- **className** (string) - Optional - Custom CSS class name applied to the root element.

### Exported Classes
- **classes.textField** (.MuiTelInput-TextField) - Styles applied to the root element.
- **classes.flagButton** (.MuiTelInput-IconButton) - Styles applied to the IconButton of the current flag.
- **classes.flagContainer** (.MuiTelInput-Flag) - Styles applied to the element around the image of a flag.
- **classes.flagImg** (.MuiTelInput-FlagImg) - Styles applied to the image within a flag element.
- **classes.menu** (.MuiTelInput-Menu) - Styles applied to Menu component.
- **classes.menuItem** (.MuiTelInput-MenuItem) - Styles applied to a flag item of the Menu.
- **classes.listItemIconFlag** (.MuiTelInput-ListItemIcon-flag) - Styles applied to the ListItemIcon of a flag item.
- **classes.listItemTextCountry** (.MuiTelInput-ListItemText-country) - Styles applied to the ListItemText of a flag item.
- **classes.callingCode** (.MuiTelInput-Typography-calling-code) - Styles applied to the calling code of a flag item.

### Usage Example
```jsx
<MuiTelInput className="my-class-name" />
```
```

--------------------------------

### MuiTelInput Component Props

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

This section covers the core props for configuring the MuiTelInput component.

```APIDOC
## MuiTelInput Component Props

This section covers the core props for configuring the MuiTelInput component.

### `value`
  * Type: `string` | `undefined`
  * Default: `''`

### `onChange`
  * Type: `(value: string, info: MuiTelInputInfo) => void`
  * Default: `undefined`

Gets called once the user updates the tel value. The callback gives you 2 parameters: the new tel value stringified and an object of different useful informations about the tel (`country`, `extension`, etc..).

### `onBlur`
  * Type: `(event: React.FocusEvent<HTMLInputElement>, info: MuiTelInputInfo) => void`
  * Default: `undefined`

Callback fired when the input loses focus. Provides the same `info` object as `onChange`.

### `defaultCountry`
  * Type: `string`
  * Default: `undefined`

Sets the selected country on component mount.

### `forceCallingCode`
  * Type: `boolean`
  * Default: `false`

Displays the calling code (e.g: +33) as read-only next to the flag and with a divider instead of as part of the input field. Needs `defaultCountry` prop to be defined or will default to `US`.

### `focusOnSelectCountry`
  * Type: `boolean`
  * Default: `false`

Autofocus the input when the user selects a country in the list.

### `onlyCountries`
  * Type: `MuiTelInputCountry[]`
  * Default: `undefined`

Country codes to be included in the list of countries.

### `excludedCountries`
  * Type: `MuiTelInputCountry[]`
  * Default: `undefined`

Country codes to be excluded of the list of countries.

### `preferredCountries`
  * Type: `MuiTelInputCountry[]`
  * Default: `undefined`

Country codes to be highlighted to the top of the list of countries.

### `continents`
  * Type: `MuiTelInputContinent[]`
  * Default: `undefined`

Continent codes to include a group of countries.

### `disableDropdown`
  * Type: `boolean`
  * Default: `false`

No country list / The current flag is a `span` instead of a `button`.

### `disableFormatting`
  * Type: `boolean`
  * Default: `false`

Remove format (spaces..) from the input value.

### `langOfCountryName`
  * Type: `string`
  * Default: `en`

An `Intl` locale to translate country names (see Intl locales). All countries will be translated in this language.

### `MenuProps`
  * Type: MenuProps
  * Default: `undefined`

Props for the MUI Menu component.

### `getFlagElement`
  * Type: `GetFlagElement`
  * Default: `(isoCode, { imgProps, countryName, isSelected }) => <img {...imgProps} />`

By default, the flag icons are loaded from https://flagcdn.com. But, with this prop, you can customize the `img` element, or use another CDN, or use SVG, etc.. `getFlagElement` empower you to use your own flag library, CDN, SVGs, etc. For those who desire offline functionality, it's possible as you can pass your own SVG components (no internet connection required). You could also customize the CSS of the `img` element.
```

--------------------------------

### Configure Next.js Integration

Source: https://viclafouch.github.io/mui-tel-input/docs/getting-started

Add the package to the transpilePackages array in your next.config.mjs file to support ESM.

```javascript
// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
 transpilePackages: ['mui-tel-input'],
 // your config
}

export default nextConfig
```

--------------------------------

### Basic MuiTelInput Usage

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Renders a basic MuiTelInput component. Use the `value` prop to set an initial phone number.

```jsx
<MuiTelInput />
```

```jsx
<MuiTelInput value="+12133734253" />
```

--------------------------------

### Implement Simple Usage

Source: https://viclafouch.github.io/mui-tel-input/docs/getting-started

Basic implementation of the MuiTelInput component using React state to manage the phone number value.

```javascript
import React from 'react'
import { MuiTelInput } from 'mui-tel-input'

const MyComponent = () => {
  const [phone, setPhone] = React.useState('')

  const handleChange = (newPhone) => {
    setPhone(newPhone)
  }

  return (
    <MuiTelInput value={phone} onChange={handleChange} />
  )
}
```

--------------------------------

### MuiTelInput Component Props

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Overview of the primary props available for the MuiTelInput component to manage phone input behavior and UI customization.

```APIDOC
## MuiTelInput Component

### Description
The MuiTelInput component provides a phone number input field with country selection capabilities, built for Material UI.

### Props
- **value** (string) - The current phone number value.
- **onChange** (function) - Callback fired when the value changes.
- **onBlur** (function) - Callback fired when the input loses focus.
- **defaultCountry** (string) - The ISO code of the default country.
- **onlyCountries** (array) - List of allowed country ISO codes.
- **excludedCountries** (array) - List of excluded country ISO codes.
- **preferredCountries** (array) - List of countries to show at the top of the list.
- **disableDropdown** (boolean) - If true, the country selection dropdown is disabled.
- **disableFormatting** (boolean) - If true, phone number formatting is disabled.
- **getFlagElement** (function) - Custom renderer for the country flag element.
- **FlagIconButtonProps** (object) - Custom props for the flag icon button.
- **unknownFlagElement** (ReactNode) - Custom element for unknown country flags.
```

--------------------------------

### Use MUI TextField Props on MuiTelInput

Source: https://viclafouch.github.io/mui-tel-input/docs/inheritance

Demonstrates using standard MUI TextField props like 'size', 'variant', and 'disabled' directly on the MuiTelInput component.

```jsx
<MuiTelInput size="small" variant="outlined" disabled />  
```

--------------------------------

### Setting Country Name Language

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use `langOfCountryName` to specify an `Intl` locale (e.g., 'fr') to translate the displayed country names in the dropdown list.

```jsx
<MuiTelInput langOfCountryName="fr" />
```

--------------------------------

### Customizing Flags with getFlagElement

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use the `getFlagElement` prop to provide custom flag components for specific countries. This allows for advanced customization beyond default flag images.

```javascript
import React from 'react'  
import FlagFR from 'my-svg/fr/flag'  
import FlagBE from 'my-svg/be/flag'  
import { MuiTelInput, MuiTelInputCountry } from 'mui-tel-input'  
  
const flags: Partial<Record<MuiTelInputCountry, React.ElementType>> = {  
  FR: FlagFR,  
  BE: FlagBE  
}  
  
export const MyComponent = () => {  
  const [phone, setPhone] = React.useState('')  
  
  const handleChange = (newPhone: string) => {  
    setPhone(newPhone)  
  }  
  
  return (  
    <MuiTelInput  
      onlyCountries={['FR', 'BE']}  
      value={phone}  
      {/* You could also use another CDN, use 'styled-component', or whatever you want...  
      isSelected is for the `button` that contains the selected country flag, maybe you want to add border for example... */}  
      getFlagElement={(isoCode, { imgProps, countryName, isSelected }) => {  
        const Component = flags[isoCode]  
        return <Component aria-label={countryName} />  
      }}  
      onChange={handleChange}  
    />  
  )  
}
```

--------------------------------

### Handling Input Blur Events

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

The `onBlur` prop is called when the input loses focus. It provides the same `info` object as `onChange`, with the `reason` set to 'blur'.

```javascript
const handleBlur = (event, info) => {
  /**
  info: {
    countryCallingCode: "33",
    countryCode: "FR",
    nationalNumber: "123456789",
    numberType: "FIXED_LINE_OR_MOBILE",
    numberValue: "+33123456789",
    reason: "blur"
  }
  **/
}

<MuiTelInput onBlur={handleBlur} />
```

--------------------------------

### Setting Default Country

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use the `defaultCountry` prop to specify the country that the phone input should default to when the component mounts. This is useful for pre-selecting a country.

```jsx
<MuiTelInput defaultCountry="DE" />
```

--------------------------------

### Highlighting Preferred Countries

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use `preferredCountries` to specify an array of country codes that should appear at the top of the country selection list, making them easily accessible.

```jsx
<MuiTelInput preferredCountries={['BE', 'FR']} />
```

--------------------------------

### Integrate MuiTelInput with React Hook Form

Source: https://viclafouch.github.io/mui-tel-input/docs/react-hook-form

Uses the Controller component to manage form state and validation for the telephone input.

```javascript
import React from "react";  
import ReactDOM from "react-dom";  
import Button from "@mui/material/Button";  
import { MuiTelInput, matchIsValidTel } from "mui-tel-input";  
import { Controller, useForm } from "react-hook-form";  
  
const App = () => {  
  const { control, handleSubmit } = useForm({  
    defaultValues: {  
      tel: ""  
    }  
  });  
  
  const onSubmit = (data) => {  
    alert(JSON.stringify(data));  
  };  
  
  return (  
    <form onSubmit={handleSubmit(onSubmit)}>  
      <Controller  
        name="tel"  
        control={control}  
        rules={{ validate: (value) => matchIsValidTel(value, { onlyCountries: ['FR'] }) }}  
        render={({ field: { ref: fieldRef, value, ...fieldProps }, fieldState }) => (  
          <MuiTelInput  
            {...fieldProps}  
            value={value ?? ''}  
            inputRef={fieldRef}  
            onlyCountries={["FR"]}  
            helperText={fieldState.invalid ? "Tel is invalid" : ""}  
            error={fieldState.invalid}  
          />  
        )}  
      />  
     <div>  
        <Button type="submit" variant="contained" sx={{ mt: 2 }}>  
          Submit  
        </Button>  
      </div>  
    </form>  
  )  
}  
```

--------------------------------

### Customizing Flag Element

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

The `getFlagElement` prop allows for custom rendering of flag icons. You can use different CDNs, SVG components, or apply custom styling to the flag image.

```javascript
getFlagElement: (isoCode, { imgProps, countryName, isSelected }) => <img {...imgProps} />
```

--------------------------------

### Forcing Calling Code Display

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

The `forceCallingCode` prop displays the calling code (e.g., +33) as read-only next to the flag. It requires `defaultCountry` to be defined.

```jsx
<MuiTelInput forceCallingCode defaultCountry="BE" />
```

--------------------------------

### Apply Custom Class Name to MuiTelInput

Source: https://viclafouch.github.io/mui-tel-input/docs/css

Use the `className` prop to apply a custom CSS class to the root element of the MuiTelInput component. This allows for global style overrides.

```jsx
<MuiTelInput className="my-class-name" />
```

--------------------------------

### Customizing Unknown Flag Element

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Replace the default unknown flag image using the `unknownFlagElement` prop. You can use a custom image, SVG, or any React node.

```javascript
import React from 'react'  
import { MuiTelInput } from 'mui-tel-input'  
import unknownFlag from 'path/to/what/u/want'  
  
const MyComponent = () => {  
  const [phone, setPhone] = React.useState('')  
  
  const handleChange = (newPhone: string) => {  
    setPhone(newPhone)  
  }  
  
  return (  
    <MuiTelInput  
       value={phone}  
       onChange={handleChange}  
       {/* Could be SVG, another CDN, etc... */}  
       unknownFlagElement={<img src={unknownFlag} width={26} alt="unknown" />}  
    />  
  )  
}
```

--------------------------------

### Customizing Flag Icon Button

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Customize the `IconButton` component used for the country flag with `FlagIconButtonProps`. This is useful for accessibility, such as adding ARIA labels.

```javascript
<MuiTelInput FlagIconButtonProps={{ 'aria-label': 'Ouvrir la liste des pays' }} />
```

--------------------------------

### Filtering Countries with `onlyCountries`

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Use the `onlyCountries` prop to provide an array of country codes that should be included in the selectable list. This restricts the available country options.

```jsx
<MuiTelInput onlyCountries={['FR', 'BE']} />
```

--------------------------------

### Autofocus on Country Select

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Set `focusOnSelectCountry` to `true` to automatically focus the input field when a user selects a country from the dropdown list.

```jsx
<MuiTelInput focusOnSelectCountry />
```

--------------------------------

### Disabling Input Formatting

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

When `disableFormatting` is enabled, the input value will not have any formatting characters like spaces or hyphens applied, providing a raw phone number string.

```jsx
<MuiTelInput disableFormatting />
```

--------------------------------

### Filtering Countries by Continents

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

The `continents` prop allows you to filter the country list by providing an array of continent codes (e.g., 'EU' for Europe, 'OC' for Oceania).

```jsx
<MuiTelInput continents={['EU', 'OC']} />
```

--------------------------------

### Validate phone numbers with matchIsValidTel

Source: https://viclafouch.github.io/mui-tel-input/docs/phone-validation

Use matchIsValidTel to verify phone number validity within a React component. The function accepts optional configuration for country filtering.

```javascript
import React from 'react'  
import { MuiTelInput, matchIsValidTel } from 'mui-tel-input'  
  
const MyComponent = () => {  
  const [value, setValue] = React.useState('+33123456789')  
  
  const handleChange = (newValue) => {  
    matchIsValidTel(newValue, {  
      onlyCountries: [], // optional,  
      excludedCountries: [], // optional  
      continents: [] // optional  
    }) // true | false  
  }  
  
  return <MuiTelInput value={value} onChange={handleChange} />  
}  
```

--------------------------------

### Excluding Countries with `excludedCountries`

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

The `excludedCountries` prop accepts an array of country codes to be removed from the list of available countries. This is useful for excluding specific regions.

```jsx
<MuiTelInput excludedCountries={['CA', 'PT']} />
```

--------------------------------

### Disabling Country Dropdown

Source: https://viclafouch.github.io/mui-tel-input/docs/api-reference

Set `disableDropdown` to `true` to hide the country selection dropdown. In this mode, the flag becomes a non-interactive `span` element.

```jsx
<MuiTelInput disableDropdown />
```
Tokens:
Raw