AddressAutocompleteField

Summary

Mapbox-powered address search without a map — combobox autocomplete with structured or string storage. Shares geocoding logic with MapPickerField but omits coordinates by default. On phones and tablets, suggestions open as a bottom sheet with an in-sheet search field (same overlay stack as SelectField) instead of a desktop dropdown.


Class	`Bjanczak\FilamentFlexFields\Filament\Forms\Components\AddressAutocompleteField`
State type	`array` — canonical address structure
Model cast	`'address' => 'array'` · `'address' => 'string'`
FieldType	`address_autocomplete`
Playground	`address-autocomplete` slug in Flex Fields playground

Requires Mapbox token in config('filament-flex-fields.mapbox.access_token') or per-field mapboxToken().

Basic usage

Structured address storage

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\AddressAutocompleteField;

AddressAutocompleteField::make('delivery_address')
    ->label('Delivery address')
    ->fields(['street', 'city', 'postcode', 'country', 'place_name'])
    ->requiredFields(['city'])
    ->streetAddressesOnly()
    ->countries(['PL'])
    ->size('md')
    ->variant('primary');

String storage

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\AddressAutocompleteField;

AddressAutocompleteField::make('billing_city')
    ->storeFormat(AddressAutocompleteField::STORE_STRING)
    ->stringFormat('{city}, {country_name}')
    ->variant('secondary')
    ->size('sm');

State & storage

Canonical keys

The field uses a standard set of keys for internal state: street, city, region, postcode, country, country_name, place_name.

Storage formats

`storeFormat`	Dehydrated value
`structured` (default)	Array with only keys from `fields()`
`string`	Single string from `stringFormat()` placeholders `{field}`

Configuration API

All methods accept Closure unless noted.

Method	Type	Default	Description
`fields(array\|Closure $fields)`	Setup	all	Address components to store in the array
`storeFormat(string\|Closure $format)`	Setup	`'structured'`	`structured` or `string`
`stringFormat(string\|Closure $format)`	Setup	auto	Template for string storage (e.g. `{street}, {city}`)
`requiredFields(array\|Closure $fields)`	Setup	`[]`	Fields that must be present in the result
`mapboxToken(string\|Closure\|null $token)`	Setup	config	Mapbox API access token
`countries(array\|Closure\|null $countries)`	Setup	`null`	Whitelist of ISO country codes
`streetAddressesOnly(bool\|Closure $condition = true)`	Setup	`false`	Reject results without a house number
`searchTypes(array\|Closure\|null $types)`	Setup	`null`	Limit results to types (e.g. `poi`, `place`)
`minSearchLength(int\|Closure $length)`	Setup	`2`	Minimum characters to trigger search
`searchDebounce(int\|Closure $ms)`	Setup	`350`	Milliseconds to wait after typing
`language(string\|Closure\|null $language)`	Setup	config	Preferred results language
`prefixIcon(...)`	Setup	`MapPin`	Custom leading icon
`clearIcon(...)`	Setup	`CircleXmark`	Custom clear button icon
`variant(string\|Closure $variant)`	Setup	`'primary'`	Visual style: `primary`, `secondary`, `flat`
`size(string\|ControlSize\|Closure $size)`	Setup	`'md'`	Control size: `sm`, `md`, `lg`
`rounding(string\|Closure\|null $rounding)`	Setup	config	Border radius token

`searchTypes()`

Limit results to specific Mapbox place types:

use Bjanczak\FilamentFlexFields\Enums\MapboxSearchType;

AddressAutocompleteField::make('venue')
    ->searchTypes([MapboxSearchType::Poi]);

Supported type strings / enum cases: country, region, postcode, district, place, locality, neighborhood, address, poi.

Note: Mapbox Geocoding v5 treats poi as general points of interest. It does not filter by category (restaurant vs cafe). Category search requires Mapbox Search Box (not wired in this field).

`language()`

Preferred language for result labels. When null (or omitted), the field falls back to config('filament-flex-fields.mapbox.default_language'), then app()->getLocale().

FlexField / Flex Forms schema config

When building via FlexFieldFormBuilder / Flex Forms Studio, these config keys map onto the fluent API (see also GeocodingSearchScope presets):

Config key	Maps to / behaviour
`search_scope`	Preset → `searchTypes()` + `streetAddressesOnly()`. Values: `all`, `address`, `cities`, `regions`, `countries`, `admin`, `poi`, `custom`
`search_types`	Used when `search_scope=custom` — raw Mapbox types list
`street_addresses_only`	Used when `search_scope=custom`
`search_area`	`global` clears country filter; `countries` applies `countries`
`countries`	ISO codes when `search_area=countries` (empty = worldwide)
`language_mode`	`auto` → `language(null)`; `manual` → `language`
`language`	BCP 47 / ISO code when `language_mode=manual`
`layout`	Studio-only: `input` vs `map` (switches to `map_picker`)
`min_search_length` / `search_debounce`	Search UX
`fields` / `store_format` / `string_format` / `required_fields` / `searchable` / `size` / `variant`	Standard field API

GeocodingSearchScope enum (Bjanczak\FilamentFlexFields\Enums\GeocodingSearchScope) is the shared preset map used by Address Autocomplete and Map Picker configurators.

Real-world examples

Simple city picker

AddressAutocompleteField::make('city')
    ->searchTypes(['place'])
    ->fields(['city', 'country_name'])
    ->storeFormat('string')
    ->stringFormat('{city}, {country_name}');

Full shipping address

AddressAutocompleteField::make('shipping_address')
    ->streetAddressesOnly()
    ->fields(['street', 'city', 'postcode', 'country'])
    ->requiredFields(['street', 'city', 'postcode'])
    ->countries(['US', 'CA']);

Playground

/admin/flex-fields-playground/address-autocomplete See Playground for setup.

Component	When to use instead
MapPickerField	When you also need to store coordinates (lat/lng)
CountryField	For picking a country only
FlexTextInput	For manual address entry without Mapbox

CSS classes (reference)

Class	Role
`fff-address-autocomplete-field`	Root wrapper
`fff-address-autocomplete__search-wrap`	Input + dropdown container
`fff-map-picker__dropdown-panel`	Suggestions list
`fff-address-autocomplete__selection-error`	Validation error overlay

Performance

Mechanism	What it does
Debounced Search	Prevents excessive API calls while typing
Lazy JS	Mapbox geocoding logic is loaded only when needed
Wire:ignore	Uses `wire:ignore` to prevent Livewire from disrupting Alpine state

Getting Started

Guides & Resources

Text & Input

Number & Range

Choice & Selection

Date & Time

Media, Color & Location

Rating & Tables

Actions & Enterprise

Layout & Display (Schemas)

Summary

Basic usage

Structured address storage

String storage

State & storage

Canonical keys

Storage formats

Configuration API

`searchTypes()`

`language()`

FlexField / Flex Forms schema config

Real-world examples

Simple city picker

Full shipping address

Playground

CSS classes (reference)

Performance

​Summary

​Basic usage

​Structured address storage

​String storage

​State & storage

​Canonical keys

​Storage formats

​Configuration API

​searchTypes()

​language()

​FlexField / Flex Forms schema config

​Real-world examples

​Simple city picker

​Full shipping address

​Playground

​Related components

​CSS classes (reference)

​Performance

Summary

Basic usage

Structured address storage

String storage

State & storage

Canonical keys

Storage formats

Configuration API

`searchTypes()`

`language()`

FlexField / Flex Forms schema config

Real-world examples

Simple city picker

Full shipping address

Playground

Related components

CSS classes (reference)

Performance