janczakb/filament-flex-fields

Filament Flex Fields is an all-in-one Filament form fields / form components plugin for Filament v5 and Laravel admin panels: 79 custom components (64 form fields, 8 layout & schema pieces, 7 table columns), a unified --fff-* design system, first-class Spatie Media Library and disk/S3 uploads (Media Ingress), and an optional JSON custom-field layer without EAV tables.

If you need a drop-in select, phone, map, signature, survey grid, rich editor, or Spatie upload that looks and behaves like one product — this package is built for that, so you do not install a separate plugin for each field type.

Filament Flex Forms is a separate commercial product: Studio, public fill & embed, submissions, Insights, and integrations — built on these same Flex Fields components.

Buy Flex Forms · Docs · GitHub

Filament v5 form components in one plugin

Both modes share the same component library, design tokens, and lazy asset loading.

Filament select with virtualization & async search

SelectField extends Filament’s built-in Select with a headless combobox: virtualized scrolling for thousands of options, async Livewire search with pagination and rate limits, rich option rows (avatars, badges, descriptions), multi-select chips, create-option / smart suggest, grid layouts, and a mobile bottom sheet instead of a cramped desktop menu. UserSelect reuses the same Alpine entry; Icon picker shares the combobox engine; Tags, Phone, Country, and related pickers share the teleported select-menu stack — shared CSS/JS loads once per page. Full native Select API remains available.

→ SelectField docs

Filament Spatie Media Library uploads (or plain disk / S3)

Use FlexSpatieMediaLibraryFileUpload or Media Ingress (disk | spatie) for files, images, voice notes, signatures, and rich-editor attachments — including S3, Spatie conversions, signed URLs, and virus-scan hooks — without a separate upload-only plugin. Spatie packages are optional (composer suggest).

→ Media Ingress · File & image upload

Filament custom fields in a JSON column (no EAV)

Add HasFlexFields, store values in one JSON column, define schemas in PHP config / Field groups admin, and render with FlexFieldFormBuilder / FlexFieldStudio. Conditions, formulas, tenant packs, and RBAC — same components as standalone forms.

→ Docs index — JSON flex fields · config: config/filament-flex-fields.php

Instead of installing many Filament field plugins

One design system, one lazy asset pipeline, one Playground — not a patchwork of unrelated CSS/JS.

Why Flex Fields?

Who it's for

Teams building Filament v5 backends that need more than stock inputs — CRM custom attributes, CMS editors, SaaS onboarding, marketplaces with configurable product fields, ops tools with barcodes and maps, or any admin UI that should feel like one product.

At a glance

Standout capabilities

SelectField & family — headless combobox with virtualized scrolling for thousands of options, async / Livewire search, rich rows (avatars, badges, descriptions), multi-select chips, create-option flows, grid layouts, and a mobile bottom sheet. UserSelect reuses the same Select entry; IconPickerField shares the combobox engine + teleported menu; Tags, Phone, Country, Timezone, Currency, Address, Map, and Social Links share the select-menu overlay stack — CSS/JS chunks load once per page, not once per field instance.

Media Ingress — one upload path for files, images, voice notes, signatures, and rich-editor attachments. Choose disk (including S3) or Spatie Media Library with full registerMediaConversions() support, virus scanning, private signed URLs, and multi-tenant disk rules. See Media Ingress.

Rich interactions — signature pads, barcode/QR camera scanning, Mapbox maps & address autocomplete, international phones, multi-currency money, weekly schedules, NPS/CSAT, animated todos, bubble multi-select, dual listboxes, and a YouTube/Vimeo/HTML5 video player.

JSON custom fields — define schemas in config or Field groups admin; store values in one JSON column via HasFlexFields. Conditions, formulas, tenant packs, and RBAC through FlexFieldFormBuilder / FlexFieldStudio.

Lazy assets (no duplicate CSS/JS) — each field queues only what it needs; request-scoped queues + SPA injector ensure the same stylesheet or hashed chunk is fetched once even if five SelectFields (or Select + Tags + Phone) appear on one form. Heavy libraries live in shared esbuild chunks (select-menu, combobox-engine, phone-lib, …). Pre-built resources/dist/ means no Node.js or Vite in your Laravel project.

1. Lean core — core.css: design tokens and shared hint chrome only.
2. Conditional critical preload — teleported menus and hold-confirm only when needed.
3. Per-component queues — Blade @include(…load-stylesheet) enqueues CSS + Alpine chunks; FlexFieldStylesheetQueue / FlexFieldAlpineQueue dedupe within the request (5× ChoiceCards → 1× CSS).
4. Batch markers + injector — emit-assets outputs data-fff-asset-batch spans; flex-field-asset-injector.js injects missing <link> / modulepreload, dedupes by href, and caches in-flight fetches across Livewire morph / Filament navigation (modal FOUC prevention).
5. Lazy Alpine mount — heavy fields can defer init until visible (x-intersect).
6. loadedOnRequest() — unused Filament-registered CSS never auto-loads via @filamentStyles.

See Performance-first assets for the Select-family share map, classes, and bundle metrics.

Playground & docs — preview components in your panel; every field documented with methods, validation, and examples at flex-fields.bjanczak.com.

Table of contents

• Filament v5 form components in one plugin
• Why Flex Fields?
• Quick start
• Custom Components (79)
• Use cases
• Screenshots
• Requirements
• Installation
• Setup
• Quick usage
• Playground
• Documentation
• FAQ
• Upgrading
• Performance-first assets
• License

Quick start

First-time install:

composer require janczakb/filament-flex-fields
php artisan filament:assets

Register the plugin on your Filament panel:

use Bjanczak\FilamentFlexFields\FilamentFlexFieldsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugin(FilamentFlexFieldsPlugin::make());
}

Then drop any component into a form — e.g. SelectField::make('status')->searchable() or MatrixChoiceField::make('priorities'). Full install options: Installation. Already installed? See Upgrading.

Fresh install: Select (virtualized combobox), schema conditions, FormBuilder, and playground demos work out of the box — no migrations required for core fields. Optional: php artisan fff:v3:upgrade refreshes the asset registry marker.

Custom Components (79)

Every item below is a custom class shipped by this package — own Blade views, CSS, and configuration API. This list does not include native Filament fields (TextInput, TagsInput, Repeater, etc.) used only as passthrough inside FlexFieldFormBuilder.

Full API for each component: https://flex-fields.bjanczak.com/docs/index.

Flagship highlights

Text & input (13)

Number & range (7)

Choice & selection (18)

Date & time (11)

Media, color & location (13)

Media Ingress — one pipeline for disk or Spatie Media Library (S3-ready), virus scanning hooks, signed URLs, image conversions, retention, and FormBuilder wiring. Migration notes: Media Ingress migration.

Rating & surveys (2)

Layout & display — schemas (8)

TranslatableTabs is a legacy alias of TranslatableFields (not counted separately). Ready-made recipes: Form layout patterns.

Table columns (7)

Actions (not in the 79)

Total: 79 custom components — 64 form fields (including 3 Spatie variants) + 8 layout/schema + 7 table columns.

Use cases

Screenshots

Requirements

Optional integrations (see composer.json → suggest):

Installation

Already ran Quick start? Jump to Setup. For version bumps, see Upgrading. Below: Packagist install, monorepo path repo, and optional Composer automation.

Composer (Packagist)

composer require janczakb/filament-flex-fields
php artisan filament:assets

Composer (path repository — monorepo)

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/filament-flex-fields"
        }
    ],
    "require": {
        "janczakb/filament-flex-fields": "@dev"
    }
}

composer require janczakb/filament-flex-fields:@dev
php artisan filament:assets

Auto-discovered via composer.json → extra.laravel.providers.

TrustedProxies (enterprise / reverse proxy)

Select, Tags, and IconPicker Livewire search endpoints share SelectSearchRateLimiter. Keys prefer the authenticated user id; guests fall back to Request::ip().

Behind Cloudflare, AWS ALB, or another reverse proxy, configure Laravel TrustedProxies (or TrustProxies middleware) so client IPs are derived correctly. Do not read X-Forwarded-For manually in application code — a misconfigured trust list would let clients spoof identities and bypass or poison rate limits.

See also SelectField search rate-limit notes.

Asset sync on every Composer run — optional but recommended; see Automate asset sync in Upgrading.

"scripts": {
    "post-autoload-dump": [
        "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
        "@php artisan package:discover --ansi",
        "@php artisan filament:assets --ansi"
    ]
}

Setup

1. Register the plugin

use Bjanczak\FilamentFlexFields\FilamentFlexFieldsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugin(FilamentFlexFieldsPlugin::make());
}

2. Publish configuration (optional)

php artisan vendor:publish --tag=filament-flex-fields-config

3. Publish translations (optional)

Built-in locales ship with the package (en, pl). Publish them only when you need to customize strings in your app:

php artisan vendor:publish --tag=filament-flex-fields-translations

Files are copied to:

lang/vendor/filament-flex-fields/
├── en/
│   ├── default.php
│   ├── countries.php
│   ├── currencies.php
│   └── timezones.php
└── pl/
    ├── default.php
    ├── countries.php
    └── timezones.php

Why lang/vendor/? Laravel resolves package translation overrides only from lang/vendor/{namespace}/ (see FileLoader::loadNamespaceOverrides). A flat path such as lang/filament-flex-fields/ is not picked up for __('filament-flex-fields::...') unless you add custom loader logic. The vendor segment here is Laravel’s convention for published package lang files — it is not Composer’s vendor/ directory.

Translation files

Timezone names resolve in this order:

1. timezones.php override (Europe/Warsaw → key Europe__Warsaw)
2. PHP Intl for the active locale (requires ext-intl)
3. Humanized IANA identifier (America/New_York → New York)

The field renders {name} (UTC±HH:MM) — only the name uses the chain above; offset is computed at runtime. You usually do not need to publish timezones.php unless you want custom wording.

Example override:

// lang/vendor/filament-flex-fields/pl/timezones.php
return [
    'Europe__Warsaw' => 'Warszawa',
];

Without publishing, the package uses its bundled translations automatically.

Adding a new locale

1. Copy the structure from vendor/janczakb/filament-flex-fields/resources/lang/en/.
2. Create lang/vendor/filament-flex-fields/{locale}/ with the files you need (default.php is usually enough to start).
3. Add timezones.php only for manual timezone wording overrides.
4. Set app.locale / Filament panel locale to your new locale.

You do not need to register anything else — filament-flex-fields::… lines resolve automatically.

Updating translations after a plugin upgrade

You usually do not need to re-publish translations when you update the package.

Laravel loads translations in two layers:

1. Built-in files from the package (resources/lang inside the plugin)
2. Your overrides from lang/vendor/filament-flex-fields/ merged on top with array_replace_recursive

That means:

• New keys added in a new plugin version appear automatically, even if your published default.php is older and does not contain them yet.
• Keys you customized in lang/vendor/... keep your wording.
• Keys you never published/overrode always follow the latest built-in package text.
• Timezone list labels follow PHP Intl by default, so new IANA zones work without updating lang files.

Recommended workflow

Re-run vendor:publish --tag=filament-flex-fields-translations only when you want a fresh file template. Avoid --force unless you intend to overwrite your edits.

4. Mapbox geocoding (MapPicker & AddressAutocomplete)

Set MAPBOX_ACCESS_TOKEN in .env. By default use_server_proxy is true — geocoding requests go through authenticated Laravel routes so the token never ships to the browser for search/reverse geocode:

MAPBOX_ACCESS_TOKEN=pk.…
FLEX_FIELDS_MAPBOX_SERVER_PROXY=true
FLEX_FIELDS_MAPBOX_CACHE_TTL=3600
FLEX_FIELDS_MAPBOX_RATE_LIMIT=60

Proxy routes use web + auth middleware by default (config/filament-flex-fields.php → mapbox.proxy_middleware). Disable the proxy only when you intentionally expose a public Mapbox token client-side.

Field API highlights: searchTypes(), language(), minSearchLength(), searchDebounce(), streetAddressesOnly(). See MapPickerField and AddressAutocompleteField.

5. Flex field audit trail (enabled by default)

# Enabled by default — set false to disable
FLEX_FIELDS_AUDIT_ENABLED=true
FLEX_FIELDS_AUDIT_COLUMN=flex_field_audit

HasFlexFields records value changes (user, timestamp, field key, old/new snapshot) in the configured JSON column.

6. Flex fields on a model (optional)

use Bjanczak\FilamentFlexFields\Concerns\HasFlexFields;

class Product extends Model
{
    use HasFlexFields;

    protected $casts = [
        'flex_field_values' => 'array',
    ];
}

Define schemas in config/filament-flex-fields.php or FlexFieldSchemaRegistry, then build with FlexFieldFormBuilder.

Quick usage

Standalone form components

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\ChoiceCards;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\MatrixChoiceField;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\PhoneField;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\TitleSlugField;

ChoiceCards::make('plan')
    ->options(['basic' => 'Basic', 'pro' => 'Pro'])
    ->required();

MatrixChoiceField::make('priorities')
    ->mode('checkbox')
    ->rows(['dark_mode' => 'Dark mode', 'csv_export' => 'CSV export'])
    ->matrixColumns(['low' => 'Low', 'medium' => 'Medium', 'high' => 'High'])
    ->disableCellWhen('csv_export', 'high', 'dark_mode', 'high');

PhoneField::make('phone')->defaultCountry('PL');

TitleSlugField::make('title', 'slug')
    ->permalinkPreview()
    ->slugUnique();

Full API for every option: https://flex-fields.bjanczak.com/docs/index.

Schema / display components

use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ItemCardGroup;
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ProgressCircle;

ProgressCircle::make()
    ->value(72)
    ->displayValue('72%')
    ->variant('semicircle');

ItemCardGroup::make([
    // Polished card-based settings rows…
]);

Playground

A dev UI page previews every custom component.

FLEX_FIELDS_PLAYGROUND=false

Example slugs: matrix-choice, choice-cards, tags-field, title-slug-field, phone-field, file-upload, item-card-group, progress-circle.

Documentation

FAQ

What is the best Filament form fields plugin for Filament v5? For teams that want one kit instead of many single-purpose packages: Flex Fields ships 79 components with a shared design system, virtualized Select + async search, Spatie Media Library / disk / S3 uploads, optional JSON custom fields, surveys, maps, signatures, and a Playground — documented per component.

Is Flex Fields an alternative to installing many Filament field plugins? Yes. One package covers select/combobox, Spatie & disk uploads, phone, maps, signature, NPS/matrix surveys, layouts, and table columns — with one --fff-* design system and lazy CSS/JS.

Does it support Filament Spatie Media Library file uploads? Yes — FlexSpatieMediaLibraryFileUpload plus the Media Ingress Spatie path for voice notes and related media. Spatie is optional via composer suggest.

Can I store Filament custom fields as JSON (no EAV tables)? Yes — HasFlexFields stores values in a JSON column; schemas live in config or Field groups. Same field components as standalone forms.

How is SelectField different from Filament’s built-in Select? Same public Select API, plus virtualized lists, async/paginated Livewire search, rich option rows, create-option flows, and a mobile bottom sheet. See SelectField.

Is Flex Fields free / open source? It is source-available and dual-licensed — not OSI “open source.” Free under Permitted Free Use for typical internal admin panels; commercial license for product SaaS / redistribution. See License.

Why choose Flex Fields over multiple Filament field plugins? One design system, one asset pipeline, one Playground, and 79 components that work together — standalone or as dynamic JSON attributes. You avoid conflicting CSS, duplicate JS, and inconsistent field APIs.

Do I need Node.js to use this package? No. Pre-built CSS/JS are committed to resources/dist/.

How does asset loading work? Each component queues only its CSS/JS. Request-scoped queues (FlexFieldStylesheetQueue, FlexFieldAlpineQueue) and the SPA injector ensure the same file is fetched once per page — even with many SelectFields or Select + Tags + Phone together. Shared stacks (select-menu, combobox-engine, …) are esbuild chunks. See Performance-first assets.

Do Select-based fields duplicate CSS/JS? No. Overlay menu CSS/JS and combobox chunks are shared across the select family; each field adds only a thin entry + private styles. Details in Select-family: what is shared.

Can I use components without the JSON flex-field system? Yes. Import any component directly into Filament forms — the JSON column and HasFlexFields trait are optional.

How many components are included? 79 custom UI classes with own views and CSS — listed in Custom Components (79).

Does SelectField support large lists and async search? Yes. SelectField virtualizes from ~100 options, supports Livewire async / paginated search, rich option rows, multi-select, create-option flows, and a mobile bottom sheet. See SelectField docs.

Does it work with Filament v4? No — this package targets Filament v5 only.

Is Spatie required? No. Sluggable, Translatable, and Media Library integrations are optional composer suggest packages.

Where is the Matrix Choice / survey grid? MatrixChoiceField — radio or checkbox mode, per-row validation, reactive disableCellWhen() / disableRowWhen(). See https://flex-fields.bjanczak.com/docs/matrixchoicefield.

Upgrading

When a new version is released, update the package and sync Filament assets into public/. You do not need Node.js, npm, or npm run build in your Laravel app — the plugin ships pre-built CSS/JS in resources/dist/.

Standard upgrade (Packagist)

composer update janczakb/filament-flex-fields
php artisan filament:assets

That is the full required workflow for most apps.

php artisan filament:assets syncs both Filament CSS/JS/Alpine bundles and bundled static media (MP3, emoji images, etc.) into public/filament-flex-fields-assets/. Fields resolve those files through FlexFieldAssets::assetUrl() with automatic cache busting.

Path repository (monorepo / local package)

composer update janczakb/filament-flex-fields
php artisan filament:assets

Automate asset sync (recommended)

Add this to your host app composer.json so filament:assets runs after every composer install / composer update:

"scripts": {
    "post-autoload-dump": [
        "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
        "@php artisan package:discover --ansi",
        "@php artisan filament:assets --ansi"
    ]
}

What you usually do not need on upgrade

After upgrading in the browser

Hard-refresh the Filament panel (Cmd+Shift+R / Ctrl+Shift+R) once if a field looks unstyled after deploy.

Version-specific notes

Read CHANGELOG.md for breaking changes, new config keys, and migration steps.

Performance-first assets

This is the technical reference for Lazy assets & shared chunks above.

No duplicate CSS/JS on a page

Select-family: what is shared

UserSelect extends SelectField and reuses the same select-field.js entry. DualListboxField is not on the select-menu stack — it only shares virtualization helpers.

CSS delivery pipeline

Dependency order is declared in FlexFieldAssets::STYLESHEET_DEPENDENCIES and resolved depth-first in stylesheetsFor() (e.g. schedule-field → timezone-field → flex-time-segments; tags-field → select-field → teleported-menu).

JavaScript delivery pipeline

Bundle inventory

Pre-built assets ship in resources/dist/. The table below lists sample bundle sizes (raw + gzip KB). Full metrics are in resources/dist/bundle-metrics.json. JS = entry + preloaded chunks from alpine-manifest.json; CSS + deps = declared stylesheet dependencies.

Sample bundles (10 of 69 production CSS files). Full per-file metrics — every component, shared chunk, and gzip size — live in resources/dist/bundle-metrics.json (regenerated on npm run build). JS = entry + preloaded chunks from alpine-manifest.json; CSS + deps = declared stylesheet dependencies.

License

Flex Fields is source-available and dual-licensed. In most real-world cases you can use it for free under Permitted Free Use in LICENSE (v1.1) — no purchase required. A commercial license is only needed when you go beyond that (typical examples: your own commercial SaaS/product where Flex Fields is a material dependency, or redistributing Flex Fields as a kit).

What free use (Permitted Free Use) allows

Quick counsel

Free §1.7(b) does not apply if the client resells, licenses, or commercially distributes the product to third parties — then the distributing party needs a commercial license.

When a commercial license is typically required

• Full license text: LICENSE (v1.1)
• Commercial plans, Custom / OEM, and purchase: COMMERCIAL.md
• Third-party attributions: CREDITS.md

Questions: open a GitHub issue or email barek122@gmail.com.