PHPackages otavio-araujo/filament-smart-cep - 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. [Validation & Sanitization](/categories/validation) 4. / 5. otavio-araujo/filament-smart-cep ActiveLibrary[Validation & Sanitization](/categories/validation) otavio-araujo/filament-smart-cep ================================ A FilamentPHP plugin that validates Brazilian postal codes (CEP) and automatically fills address fields (street, neighborhood, city, state, country) using ViaCEP as the primary source, with multiple API fallbacks for reliability. 4.0.1(10mo ago)82.9k3[3 PRs](https://github.com/otavio-araujo/filament-smart-cep/pulls)MITPHPPHP ^8.2|^8.3CI passing Since Aug 11Pushed 6mo agoCompare [ Source](https://github.com/otavio-araujo/filament-smart-cep)[ Packagist](https://packagist.org/packages/otavio-araujo/filament-smart-cep)[ Docs](https://github.com/otavio-araujo/filament-smart-cep)[ GitHub Sponsors](https://github.com/otavio-araujo)[ RSS](/packages/otavio-araujo-filament-smart-cep/feed)WikiDiscussions 4.x Synced 3d ago READMEChangelog (2)Dependencies (15)Versions (6)Used By (0) Filament Smart CEP ================== [](#filament-smart-cep) [![Basic Usage](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/hero.png)](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/hero.png) **Filament Smart CEP** is a plugin for **FilamentPHP v4** that validates Brazilian postal codes (CEP) and automatically fills address fields with accurate data. It uses **[ViaCEP](https://viacep.com.br/)** as the primary API, with multiple backup providers to ensure reliability and uptime. --- [![Pint](https://github.com/otavio-araujo/filament-smart-cep/actions/workflows/pint.yml/badge.svg)](https://packagist.org/packages/otavio-araujo/filament-smart-cep)[![PEST](https://github.com/otavio-araujo/filament-smart-cep/actions/workflows/pest.yml/badge.svg)](https://packagist.org/packages/otavio-araujo/filament-smart-cep)[![PHPStan](https://github.com/CodeWithDennis/larament/actions/workflows/phpstan.yml/badge.svg)](https://github.com/CodeWithDennis/larament/actions/workflows/phpstan.yml)[![Total Installs](https://camo.githubusercontent.com/a2968175f50ab32e3b51ae5a3e57709829f11410373825e51c95b13a4ec571f8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f746176696f2d617261756a6f2f66696c616d656e742d736d6172742d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/otavio-araujo/filament-smart-cep)[![Latest Version on Packagist](https://camo.githubusercontent.com/f3e511052c68475ad283f357ab7fe78776830fe7732eb0c985282d1ec5272e2a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f746176696f2d617261756a6f2f66696c616d656e742d736d6172742d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/otavio-araujo/filament-smart-cep) --- Filament Compatibility ---------------------- [](#filament-compatibility) Compatible with Filament v4. --- ✨ Features ---------- [](#-features) - **CEP validation** with instant feedback. - **Automatic address filling**: street, neighborhood, city, state, state abbreviation, country, and country abbreviation. - **Multiple API fallback**: if ViaCEP is unavailable, the plugin tries alternative providers automatically. - **Seamless FilamentPHP integration** — works out-of-the-box with Forms. - **Customizable field mapping** to match your resource structure. - **Fast and lightweight** — no heavy dependencies. --- 🚀 How It Works -------------- [](#-how-it-works) 1. User inputs a Brazilian postal code (CEP) in a Filament form. 2. The plugin validates the code format. 3. The plugin queries **ViaCEP** first. 4. If ViaCEP fails, other APIs are used as fallback. 5. Address fields are automatically populated. --- 📦 Installation -------------- [](#-installation) You can install the package via composer: ``` composer require otavio-araujo/filament-smart-cep ``` --- ⚙️ Configuration ---------------- [](#️-configuration) You can customize: - Which fields are auto-filled. - Which field is going to receive focus after CEP autofill. - Use prefix ou suffix action. --- 📖 Basic Usage ------------- [](#-basic-usage) The custom field searches for CEP and fills up the form fields with the data returned by the web service. **By default, the fields that will be filled up are:** - street; - neighborhood; - city; - state; - state\_code; - ibge\_code; - country; - and country\_code. *By default, the number field is focused after field-autofill.* ``` public static function configure(Schema $schema): Schema { return $schema ->components([ SmartCep::make('postal_code'), TextInput::make('street'), TextInput::make('neighborhood'), TextInput::make('city'), TextInput::make('state'), TextInput::make('state_code'), TextInput::make('ibge_code'), TextInput::make('country'), TextInput::make('country_code'), TextInput::make('number'), ]); } ``` [![Basic Usage](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4b75fca50f5b29ccf571389cd329c8be28b8f46f/art/4x/basic_usage.png)](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4b75fca50f5b29ccf571389cd329c8be28b8f46f/art/4x/basic_usage.png) --- 🏷️ Using Custom Field Names --------------------------- [](#️-using-custom-field-names) If you want to customize the fields that will be filled up, you can chain on the following methods: ``` public static function configure(Schema $schema): Schema { return $schema ->components([ SmartCep::make('postal_code') ->bindStreetField('custom_street') ->bindNeighborhoodField('custom_neighborhood') ->bindCityField('custom_city') ->bindStateField('custom_state') ->bindStateCodeField('custom_state_code') ->bindIbgeCodeField('custom_ibge_code') ->bindCountryField('custom_country') ->bindCountryCodeField('custom_country_code'), TextInput::make('custom_street'), TextInput::make('custom_neighborhood'), TextInput::make('custom_city'), TextInput::make('custom_state'), TextInput::make('custom_state_code'), TextInput::make('custom_ibge_code'), TextInput::make('custom_country'), TextInput::make('custom_country_code'), TextInput::make('number'), ]); } ``` [![Basic Usage](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/custom_fields.png?raw=true)](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/custom_fields.png?raw=true) --- ⏪🖌️⏩ Customize Action's Button Icon and Position ------------------------------------------------ [](#️-customize-actions-button-icon-and-position) If you want to customize the action's button icon and position, you can chain on the following methods: ``` public static function configure(Schema $schema): Schema { return $schema ->components([ SmartCep::make('postal_code') ->actionIcon(Heroicon::OutlinedDocumentMagnifyingGlass), // Default: Heroicon::OutlinedMagnifyingGlass ->actionPosition('prefix') // Options: 'prefix', 'suffix' | Default: 'suffix' ]); } ``` [![Basic Usage](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/custom_icon_and_action_position.png?raw=true)](https://raw.githubusercontent.com/otavio-araujo/filament-smart-cep/4.x/art/4x/custom_icon_and_action_position.png?raw=true) --- 🎯 Set Focus on an Input After Filling up the Fields --------------------------------------------------- [](#-set-focus-on-an-input-after-filling-up-the-fields) If you want to set focus on an input after filling up the fields, you can chain on the following methods: ``` public static function configure(Schema $schema): Schema { return $schema ->components([ SmartCep::make('postal_code') ->nextFocusField('number'), ... TextInput::make('number'), ]); } ``` --- 👨‍💻 Code Quality ---------------- [](#‍-code-quality) ``` composer analyse ``` ``` composer lint ``` ``` composer test ``` --- 📋 Changelog ----------- [](#-changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. --- 🤝 Contributing -------------- [](#-contributing) Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. --- 🛡️ Security Vulnerabilities --------------------------- [](#️-security-vulnerabilities) Please review [our security policy](.github/SECURITY.md) on how to report security vulnerabilities. --- ⭐ Credits --------- [](#-credits) - [Otávio Araújo](https://github.com/otavio-araujo) - [All Contributors](.github/CONTRIBUTING.md) --- 🚨 License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 42 — FairBetter than 88% of packages Maintenance63 Regular maintenance activity Popularity26 Limited adoption so far Community11 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 88.6% of commits — single point of failure 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 ~8 days Total 3 Last Release 311d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/30505243?v=4)[Otávio Araújo](/maintainers/otavio-araujo)[@otavio-araujo](https://github.com/otavio-araujo) --- Top Contributors [![otavio-araujo](https://avatars.githubusercontent.com/u/30505243?v=4)](https://github.com/otavio-araujo "otavio-araujo (39 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags laravelcepfilamentbrazil ### Code Quality TestsPest Static AnalysisPHPStan, Rector Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/otavio-araujo-filament-smart-cep/health.svg) ``` [![Health](https://phpackages.com/badges/otavio-araujo-filament-smart-cep/health.svg)](https://phpackages.com/packages/otavio-araujo-filament-smart-cep) ``` ### Alternatives [codewithdennis/filament-select-tree The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths. 329530.5k29](/packages/codewithdennis-filament-select-tree)[relaticle/flowforge Flowforge is a lightweight Kanban board package for Filament that works with existing Eloquent models. 413106.5k6](/packages/relaticle-flowforge)[awcodes/richer-editor A collection of extensions and tools to enhance the Filament Rich Editor field. 3912.9k9](/packages/awcodes-richer-editor)[danihidayatx/image-optimizer Optimize your Filament images before they reach your database. Forked from joshembling/image-optimizer for Filament v4 & v5 support. 3218.1k](/packages/danihidayatx-image-optimizer)[rawilk/filament-password-input Enhanced password input component for filament. 52263.4k14](/packages/rawilk-filament-password-input)[schmeits/filament-character-counter This is a Filament character counter TextField and Textarea form field for Filament v4 and v5 34226.4k13](/packages/schmeits-filament-character-counter) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)