PHPackages                             erlenwald/filament-phone-input - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. erlenwald/filament-phone-input

ActiveLibrary[Utility & Helpers](/categories/utility)

erlenwald/filament-phone-input
==============================

A Filament phone input field with country dropdown, masks, country detection and CSS flag atlas.

v0.2.4(1mo ago)07↓100%MITPHPPHP ^8.2

Since May 9Pushed 1mo agoCompare

[ Source](https://github.com/Erlenwald/filament-phone-input)[ Packagist](https://packagist.org/packages/erlenwald/filament-phone-input)[ RSS](/packages/erlenwald-filament-phone-input/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (7)Used By (0)

Filament Phone Input
====================

[](#filament-phone-input)

A Filament form field for entering phone numbers with country selection, masks, country detection, configurable output formats, and optional flag icons.

Features
--------

[](#features)

- Country dropdown with search
- Favorite countries group
- Country-specific phone masks
- Automatic country detection while typing or pasting
- Optional selected country state field
- Configurable phone state path
- Configurable output format
- Optional default country
- Optional IP-based country lookup
- Optional SVG flags
- `1x1` and `4x3` flag aspect modes
- Publishable translations
- Publishable custom CSS
- English and Russian translations
- No dependency on `intl-tel-input`

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel
- Filament 5

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require erlenwald/filament-phone-input
```

Publish the required flag assets:

```
php artisan vendor:publish --tag=filament-phone-input-assets
```

Publish Filament assets:

```
php artisan filament:assets
```

Clear the application cache if needed:

```
php artisan optimize:clear
```

Optional publishing
-------------------

[](#optional-publishing)

You can publish only the files you need.

TagPublishes`filament-phone-input-assets`Flag atlas files to `public/vendor/erlenwald/filament-phone-input/flags``filament-phone-input-translations`Translation files to `lang/vendor/erlenwald-filament-phone-input``filament-phone-input-styles`Custom CSS file to `resources/css/vendor/erlenwald/filament-phone-input/phone-input.css``filament-phone-input-customization`Translations and custom CSS`filament-phone-input-full`Flags, translations, and custom CSSPublish everything:

```
php artisan vendor:publish --tag=filament-phone-input-full
```

Publish everything and overwrite existing files:

```
php artisan vendor:publish --tag=filament-phone-input-full --force
```

Use `--force` carefully because it overwrites already published translations and custom CSS.

After publishing or changing custom CSS, run:

```
php artisan filament:assets
php artisan optimize:clear
```

Basic usage
-----------

[](#basic-usage)

```
use Erlenwald\FilamentPhoneInput\PhoneInput;

PhoneInput::make('phone');
```

By default, the normalized phone number is written to the same state path as the field name:

```
[
    'phone' => '+[country_code][national_number]',
]
```

To also store the selected country ISO2 code:

```
PhoneInput::make('phone')
    ->countryStatePath();
```

Submitted state:

```
[
    'phone' => '+[country_code][national_number]',
    'phone_country' => 'RU',
]
```

Full example
------------

[](#full-example)

```
use Erlenwald\FilamentPhoneInput\Enums\PhoneNumberFormat;
use Erlenwald\FilamentPhoneInput\PhoneInput;

PhoneInput::make('phone')
    ->countryStatePath('phone_country')
    ->defaultCountry('RU')
    ->countries(['RU', 'BY', 'KZ'])
    ->favoriteCountries(['RU', 'BY'])
    ->displayCountryFlag()
    ->flagAspect('4x3')
    ->phoneNumberFormat(PhoneNumberFormat::E164);
```

Configuration methods
---------------------

[](#configuration-methods)

MethodDescription`phoneStatePath(string|Closure|null $path)`Overrides the state path where the normalized phone number is written. If not set, the field state path is used.`countryStatePath(string|Closure|null $path = 'phone_country')`Enables writing the selected country ISO2 code to form state. If called without arguments, writes to `phone_country`.`countries(array|Closure|null $countries = null)`Restricts the visible country list. If not set, all supported countries are displayed.`favoriteCountries(array|Closure|null $countries = null)`Displays selected countries in a separate group at the top of the dropdown.`defaultCountry(string|Closure|null $country)`Sets the initial fallback country. Does not restrict the country list.`displayCountryFlag(bool|Closure $condition = true)`Displays flag icons instead of ISO2 country codes.`flagAspect(string|Closure $aspect)`Sets the flag aspect ratio. Supported values: `'4x3'`, `'1x1'`.`phoneNumberFormat(PhoneNumberFormat|string|Closure $format)`Sets the submitted phone number format.`enableIpLookup(bool|Closure $condition = true)`Enables IP lookup without changing the configured endpoint.`ipLookup(string|Closure|null $url = null, string|Closure|null $countryKey = 'country_code')`Configures and enables IP lookup.All standard Filament field methods such as `required()`, `label()`, `helperText()`, `disabled()`, and `hidden()` are available because the component extends Filament's `Field`.

Phone number formats
--------------------

[](#phone-number-formats)

Use the `PhoneNumberFormat` enum:

```
use Erlenwald\FilamentPhoneInput\Enums\PhoneNumberFormat;

PhoneInput::make('phone')
    ->phoneNumberFormat(PhoneNumberFormat::E164);
```

Available formats:

EnumValueExample`PhoneNumberFormat::E164``e164``+[country_code][national_number]``PhoneNumberFormat::National``national``8 (XXX) XXX-XX-XX``PhoneNumberFormat::International``international``+[country_code] (XXX) XXX-XX-XX``PhoneNumberFormat::Rfc3966``rfc3966``tel:+[country_code][national_number]``PhoneNumberFormat::Digits``digits``[country_code][national_number]``PhoneNumberFormat::NationalDigits``national_digits``[national_number]`You can also pass a string:

```
PhoneInput::make('phone')
    ->phoneNumberFormat('international');
```

State paths
-----------

[](#state-paths)

### Default phone state

[](#default-phone-state)

```
PhoneInput::make('phone');
```

Submitted state:

```
[
    'phone' => '+[country_code][national_number]',
]
```

### Phone and country state

[](#phone-and-country-state)

```
PhoneInput::make('phone')
    ->countryStatePath();
```

Submitted state:

```
[
    'phone' => '+[country_code][national_number]',
    'phone_country' => 'RU',
]
```

### Custom country state path

[](#custom-country-state-path)

```
PhoneInput::make('phone')
    ->countryStatePath('country');
```

Submitted state:

```
[
    'phone' => '+[country_code][national_number]',
    'country' => 'RU',
]
```

### Custom phone state path

[](#custom-phone-state-path)

```
PhoneInput::make('contact_phone_input')
    ->phoneStatePath('phone')
    ->countryStatePath('phone_country');
```

Submitted state:

```
[
    'phone' => '+[country_code][national_number]',
    'phone_country' => 'RU',
]
```

Countries
---------

[](#countries)

Restrict visible countries:

```
PhoneInput::make('phone')
    ->countries(['RU', 'BY', 'KZ']);
```

Show favorite countries at the top:

```
PhoneInput::make('phone')
    ->favoriteCountries(['RU', 'BY']);
```

Set an initial fallback country:

```
PhoneInput::make('phone')
    ->defaultCountry('RU');
```

`defaultCountry()` does not restrict the list. It is only used as an initial fallback when the field is empty and no country state is available.

Flags
-----

[](#flags)

By default, the component displays ISO2 country codes.

Enable flag icons:

```
PhoneInput::make('phone')
    ->displayCountryFlag();
```

Use rectangular flags:

```
PhoneInput::make('phone')
    ->displayCountryFlag()
    ->flagAspect('4x3');
```

Use square flags:

```
PhoneInput::make('phone')
    ->displayCountryFlag()
    ->flagAspect('1x1');
```

Flag icons require published flag assets:

```
php artisan vendor:publish --tag=filament-phone-input-assets
```

The package ships both WebP and SVG flag atlases.

By default, WebP atlases are used because they are much smaller:

AtlasSVG sizeWebP size`atlas-1x1`~1.5 MB~188 KB`atlas-4x3`~1.5 MB~210 KBIf you prefer SVG atlases, publish the custom CSS file:

```
php artisan vendor:publish --tag=filament-phone-input-styles
```

Then edit:

```
resources/css/vendor/erlenwald/filament-phone-input/phone-input.css

```

and override the flag atlas variables:

```
.fi-phone-input__flag-aspect-1x1 {
    --fi-phone-input-flag-atlas-1x1: url('/vendor/erlenwald/filament-phone-input/flags/atlas-1x1.svg');
}

.fi-phone-input__flag-aspect-4x3 {
    --fi-phone-input-flag-atlas-4x3: url('/vendor/erlenwald/filament-phone-input/flags/atlas-4x3.svg');
}
```

After changing custom CSS, run:

```
php artisan filament:assets
php artisan optimize:clear
```

IP lookup
---------

[](#ip-lookup)

IP lookup is optional and does not override a value already typed by the user.

```
PhoneInput::make('phone')
    ->defaultCountry('RU')
    ->ipLookup('/ip-country', 'country_code');
```

The endpoint may return JSON:

```
{
    "country_code": "RU"
}
```

Nested keys are supported:

```
PhoneInput::make('phone')
    ->ipLookup('/ip-country', 'location.country_code');
```

Expected JSON:

```
{
    "location": {
        "country_code": "RU"
    }
}
```

Plain text is also supported:

```
RU

```

Cloudflare-like trace text is supported too:

```
loc=RU

```

Customization
-------------

[](#customization)

### Translations

[](#translations)

Publish translations:

```
php artisan vendor:publish --tag=filament-phone-input-translations
```

Published files:

```
lang/vendor/erlenwald-filament-phone-input/en/phone-input.php
lang/vendor/erlenwald-filament-phone-input/ru/phone-input.php

```

You can edit these files to override labels, country names, search placeholder, and group names.

### Styles

[](#styles)

Publish custom CSS:

```
php artisan vendor:publish --tag=filament-phone-input-styles
```

Published file:

```
resources/css/vendor/erlenwald/filament-phone-input/phone-input.css

```

This file is loaded after the package CSS, so you can override component styles and CSS variables there.

After changing the custom CSS, run:

```
php artisan filament:assets
php artisan optimize:clear
```

Validation
----------

[](#validation)

This package focuses on input formatting and state normalization.

Server-side validation should still be handled by your application according to your own business rules:

```
PhoneInput::make('phone')
    ->required();
```

Assets
------

[](#assets)

The component uses generated flag atlas files.

WebP atlases are used by default:

```
atlas-1x1.webp
atlas-4x3.webp

```

SVG atlases are also included and can be enabled through custom CSS:

```
atlas-1x1.svg
atlas-4x3.svg

```

All flag atlases are published to:

```
public/vendor/erlenwald/filament-phone-input/flags

```

The base JavaScript and CSS assets are registered through Filament:

```
php artisan filament:assets
```

After package updates, refresh published assets:

```
php artisan vendor:publish --tag=filament-phone-input-assets --force
php artisan filament:assets
php artisan optimize:clear
```

If you also want to refresh translations and custom CSS, use:

```
php artisan vendor:publish --tag=filament-phone-input-full --force
```

Be careful: this overwrites customized translation and CSS files.

Credits
-------

[](#credits)

Flag assets are based on the `flag-icons` project.

See `NOTICE.md` for third-party attribution.

License
-------

[](#license)

The MIT License.

See `LICENSE`.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance94

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

6

Last Release

31d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f688bbbc2c82609d7847dba033b2e1fb6c7e3fea48ab6c58edaa7afd68194795?d=identicon)[Erlenwald](/maintainers/Erlenwald)

---

Tags

laravelphoneflagslivewirefilamentfilamentphpphone-numberalpinejsphone-inputcountry-picker

### Embed Badge

![Health badge](/badges/erlenwald-filament-phone-input/health.svg)

```
[![Health](https://phpackages.com/badges/erlenwald-filament-phone-input/health.svg)](https://phpackages.com/packages/erlenwald-filament-phone-input)
```

###  Alternatives

[ysfkaya/filament-phone-input

A phone input component for Laravel Filament

3131.2M25](/packages/ysfkaya-filament-phone-input)[dotswan/filament-map-picker

Easily pick and retrieve geo-coordinates using a map-based interface in your Filament applications.

127173.7k3](/packages/dotswan-filament-map-picker)[jibaymcs/filament-tour

Bring the power of DriverJs to your Filament panels and start a tour !

12351.0k](/packages/jibaymcs-filament-tour)[asosick/filament-layout-manager

Allow users to create & customize their own FilamentPHP pages composed of Livewire components

5721.3k3](/packages/asosick-filament-layout-manager)[guava/filament-modal-relation-managers

Allows you to embed relation managers inside filament modals.

7976.7k4](/packages/guava-filament-modal-relation-managers)[defstudio/filament-searchable-input

A searchable autocomplete input for Filament forms

3418.5k](/packages/defstudio-filament-searchable-input)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)