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:

Add a new address data source implementation for the country.
Register the new source in the source factory.
Generate the country dataset in the canonical JSON format used by the package.
Add or update translations if the country needs localized messages.
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.

dominasys / filament-location

Maintainers

Package info

Fund package maintenance!

Statistics

Security