README

filament-location provides reusable Filament components for address forms, postal code lookup, and country-aware location fields.

Features

• PostalCode lookup with standardized results
• Reusable components for state, city, neighborhood, street, house number, and complement
• Frontend-only search for state and city
• Accent-insensitive and typo-tolerant search
• Canonical address dataset stored per country
• Localization for en and pt_BR

Installation

Install the package with Composer:

composer require dominasys/filament-location

Usage

Use the provided components in your Filament form schemas:

use Dominasys\FilamentLocation\Forms\Components\Address\City;
use Dominasys\FilamentLocation\Forms\Components\Address\Complement;
use Dominasys\FilamentLocation\Forms\Components\Address\HouseNumber;
use Dominasys\FilamentLocation\Forms\Components\Address\Neighborhood;
use Dominasys\FilamentLocation\Forms\Components\Address\State;
use Dominasys\FilamentLocation\Forms\Components\Address\Street;
use Dominasys\FilamentLocation\Forms\Components\PostalCode;

PostalCode::make('postal_code');
State::make('state');
City::make('city');
Neighborhood::make('neighborhood');
Street::make('street');
HouseNumber::make('house_number');
Complement::make('complement');

Supported Countries

Today the package ships with support for Brazil (BR).

The address dataset is country-based, so additional countries can be added without changing the public component API.

Extending With New Countries

To add support for another country, follow the same pattern used for Brazil:

1. Add a new address data source implementation for the country.
2. Register the new source in the source factory.
3. Generate the country dataset in the canonical JSON format used by the package.
4. Add or update translations if the country needs localized messages.
5. Add tests for lookup, state/city options, and dataset sync.

The package is intentionally structured so the UI components keep the same API even when the underlying data source changes.

Testing

Run the full local quality gate with:

composer check

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

If you want to add support for a new country, keep the implementation country-driven and avoid adding Brazil-specific assumptions to shared code.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Bruno Mangilli
• All Contributors

License

The MIT License (MIT). Please see License File for more information.