TimezoneField

Summary

Searchable IANA timezone picker with a Gravity UI clock icon on the trigger and in menu rows. Stores a single timezone identifier string. Display labels are city, country (Warsaw, Poland / Warszawa, Polska), not generic names like “Poland Time”.


Class	`Bjanczak\FilamentFlexFields\Filament\Forms\Components\TimezoneField`
State type	`string\|null` — IANA timezone identifier
Model cast	`'timezone' => 'string'`
FieldType	(no dedicated FieldType mapping yet — use the class directly)
Playground	`timezone-field` slug in Flex Fields playground

Basic usage

Standard timezone picker

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

TimezoneField::make('timezone')
    ->label('User Timezone')
    ->defaultTimezone('Europe/Warsaw')
    ->showOffset()
    ->required();

Browser-aware detection

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

TimezoneField::make('timezone')
    ->browserTimezoneDefault()
    ->browserTimezoneSortFirst();

State & validation

Stored value

State is a single IANA identifier string — never the display label.

$record->timezone; // string|null — e.g. "Europe/Warsaw"

The picker shows city, country (Warsaw, Poland / Warszawa, Polska) plus a UTC offset badge (UTC+02:00). Generic names like “Poland Time” are not used.

Validation rules

Built-in validation ensures the submitted identifier is in the resolved timezone list.

Rule	Detail
`nullable`	Always (unless `required()`)
`in(...)`	Value must match a configured IANA identifier

Configuration API

All methods accept Closure unless noted.

Method	Type	Default	Description
`timezones(array\|Closure\|null $timezones)`	Setup	`null`	Whitelist of IANA identifiers
`exceptTimezones(array\|Closure $timezones)`	Setup	`[]`	Blacklist of IANA identifiers
`includeUtc(bool\|Closure $condition = true)`	Setup	`true`	Keep canonical `UTC` in the full IANA list
`defaultTimezone(string\|Closure\|null $timezone)`	Setup	`null`	Fallback IANA identifier
`browserTimezoneDefault(bool\|Closure $condition = true)`	Setup	`false`	Pre-select from browser settings
`browserTimezoneSortFirst(bool\|Closure $condition = true)`	Setup	`false`	Sort browser timezone to top of list
`showOffset(bool\|Closure $condition = true)`	Setup	`true`	Show UTC offset badge (e.g. `UTC+02:00`)
`locale(string\|Closure\|null $locale)`	Setup	`app()->getLocale()`	Language for city and country labels (`en` → Warsaw, Poland)
`searchable(bool\|Closure $condition = true)`	Setup	`true`	Show search input in dropdown
`prefixIcon(...)`	Setup	`Clock`	Custom leading icon
`variant(string\|Closure $variant)`	Setup	`'primary'`	Visual style: `primary`, `secondary`, `flat`, `soft`
`size(string\|ControlSize\|Closure $size)`	Setup	`'md'`	Control size: `sm`, `md`, `lg`
`rounding(string\|Closure\|null $rounding)`	Setup	config	Border radius token

`timezones()` / `exceptTimezones()`

Limit the list to specific regions or exclude problematic zones:

TimezoneField::make('timezone')
    ->timezones(['UTC', 'Europe/Warsaw', 'America/New_York'])
    ->exceptTimezones(['GMT']);

UTC stays in the default IANA list (servers, logs, APIs). It is optional, not required:

TimezoneField::make('timezone')->includeUtc(false);
TimezoneField::make('timezone')->exceptTimezones(['UTC']);

`browserTimezoneDefault()`

When enabled and state is empty, it attempts to detect the user’s timezone via Alpine/JS.

TimezoneField::make('timezone')->browserTimezoneDefault();

`locale()`

City and country labels follow app()->getLocale() by default (Warsaw, Poland / Warszawa, Polska). Pin a language per field, independently of the panel locale:

TimezoneField::make('timezone')->locale('pl');
TimezoneField::make('timezone')->locale(fn (): string => auth()->user()->locale);

Override the full display string in lang/{locale}/timezones.php (publish the package lang files). Keys use __ instead of /:

// lang/pl/vendor/filament-flex-fields/timezones.php
return [
    'Europe__Warsaw' => 'Warszawa, Polska',
    'America__New_York' => 'Nowy Jork, Stany Zjednoczone',
];

Stored state is still the IANA id (Europe/Warsaw), never the translated label.

Real-world examples

User profile settings

public static function form(Form $form): Form
{
    return $form->schema([
        TimezoneField::make('timezone')
            ->label('Your local time')
            ->browserTimezoneDefault()
            ->browserTimezoneSortFirst()
            ->required(),
    ]);
}

Event scheduler

TimezoneField::make('event_timezone')
    ->label('Event Location Timezone')
    ->searchable()
    ->showOffset();

Playground

/admin/flex-fields-playground/timezone-field See Playground for setup.

Component	When to use instead
CountryField	For picking a country instead of a specific timezone
FlexDateTimePicker	For picking a date/time with optional timezone support
SelectField	For a generic dropdown if IANA identifiers aren’t needed

CSS classes (reference)

Class	Role
`fff-timezone-field`	Root wrapper
`fff-timezone-field--{sm\|md\|lg}`	Size modifier
`fff-timezone-field__trigger`	Picker button
`fff-timezone-field__offset`	UTC offset badge
`fff-timezone-field__menu`	Dropdown panel
`fff-timezone-field__search`	Search input

Performance

Mechanism	What it does
Virtual Scroll	Efficiently renders long lists of timezones (~400+ zones)
SSR Label	Renders the selected timezone label server-side for zero layout flash
Shared IANA registry	Default full catalog is queued once per request (`TimezoneRegistry` / `#fff-timezone-registry-data`), not embedded in every field’s Alpine `@js` payload — same pattern as `CountryRegistry`
Teleport	Uses `x-teleport="body"` to avoid overflow clipping in modals

Payload vs SSR trade-offs

Mode	HTML / Alpine payload	SSR trigger
Default full IANA list	Compact shared registry template (once per page); field `@js` stays lean (`timezonePool` + optional filter key + `selectedTimezoneSeed`)	Selected value: seed row only. Empty + `browserTimezoneDefault()`: blocking boot reads the shared registry (not a per-field full catalog attribute) so the city label never swaps to Intl generics
Explicit `timezones([...])` whitelist	Inline `@js` options for that subset only (no shared registry)	Same SSR seed / boot catalog for the whitelist
`exceptTimezones([...])` on the full list	Shared registry + filter key of resolved ids	Same as default full list

Prefer timezones([...]) when a form only needs a handful of zones so the shared full catalog is never queued. Prefer the default registry path when you need the full IANA list — one catalog for every TimezoneField on the page beats N copies inside x-data.

Ops notes

Timezone search shares the Select-family Livewire search rate limit (filament-flex-fields.select.search_rate_limit_per_minute). Keys use the authenticated user id or Request::ip() — configure Laravel TrustedProxies when the app sits behind a reverse proxy so client IPs are not taken from spoofable forwarded headers.

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

Standard timezone picker

Browser-aware detection

State & validation

Stored value

Validation rules

Configuration API

`timezones()` / `exceptTimezones()`

`browserTimezoneDefault()`

`locale()`

Real-world examples

User profile settings

Event scheduler

Playground

CSS classes (reference)

Performance

Payload vs SSR trade-offs

Ops notes

​Summary

​Basic usage

​Standard timezone picker

​Browser-aware detection

​State & validation

​Stored value

​Validation rules

​Configuration API

​timezones() / exceptTimezones()

​browserTimezoneDefault()

​locale()

​Real-world examples

​User profile settings

​Event scheduler

​Playground

​Related components

​CSS classes (reference)

​Performance

​Payload vs SSR trade-offs

​Ops notes

Summary

Basic usage

Standard timezone picker

Browser-aware detection

State & validation

Stored value

Validation rules

Configuration API

`timezones()` / `exceptTimezones()`

`browserTimezoneDefault()`

`locale()`

Real-world examples

User profile settings

Event scheduler

Playground

Related components

CSS classes (reference)

Performance

Payload vs SSR trade-offs

Ops notes