> ## Documentation Index
> Fetch the complete documentation index at: https://flex-fields.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Examples target Filament 5. Verify optional dependencies before configuring integrations.
> Upload transfer completion, permanent storage and record acceptance are separate milestones. Native and Spatie image conversions retain the original.

# Configure FLEX Fields appearance and behavior

> Configure FLEX Fields v4 defaults, panel density, theme tokens, control sizes, optional features and language editing.

Configure a field where you use it. Use panel settings for shared presentation and application configuration for reusable defaults. A small form and a detailed workflow can use the same components with different settings.

## Choose the right scope

| Scope | Where you configure it | Use it for |
| - | - | - |
| Application | `config/filament-flex-fields.php` | Defaults and service settings used across your application |
| Panel | `FilamentFlexFieldsPlugin::make()` | FLEX density, theme tokens and navigation settings |
| Field | The field's fluent PHP methods | Its size, variant, data source, limits and optional features |

Not every setting exists at all three levels. For example, a text input reads its configured size default when it is created; a later `size('sm')` on that field replaces that default. An upload's editor is enabled on the upload instance. Check the component reference for the setting you are changing.

## Set application defaults

[Publish configuration](https://flex-fields.bjanczak.com/docs/installation.md#optional-defaults-and-translations) if you need overrides. Update the existing `ui` section rather than replacing the entire file:

```php config/filament-flex-fields.php theme={"theme":{"light":"github-light","dark":"github-dark"}}
'ui' => [
    // Keep the other UI settings already present.
    'flex_text_input_size' => 'md',
    'flex_text_input_variant' => 'secondary',
],
```

A field can then choose a different presentation:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;

FlexTextInput::make('reference')
    ->size('sm')
    ->variant('primary');
```

Settings maps inherit newly added nested defaults. Explicit application values
(including `false` and `null`) take precedence. Lists replace the default list;
they are never appended. An explicitly empty array replaces that entire branch,
so omit a branch when you want its defaults. For example, setting
`'ui' => ['flex_text_input_size' => 'sm']` keeps the other UI defaults, while
`'ui' => []` explicitly clears that branch.

The file lists the settings the package actually reads, including icon defaults,
FormBuilder size/variant defaults, map assets, route prefixes and URL upload
limits. FormBuilder defaults apply when it builds fields from schemas; they do
not implicitly configure every direct `Field::make()` instance. Use each field's
fluent methods for explicit per-instance configuration. `ui.cell_height` was
unused and has been removed. `ui.video_auto_hide_controls` now supplies the video
control default; `autoHideControls(...)` on a field still takes precedence.

Schema defaults also inherit the configured variants and default country. An
explicit field `config` value wins over these application defaults, including
`auto_hide_controls => false`. Schema-generated NPS labels resolve in the current
language; custom labels stay unchanged, and an explicit empty or null endpoint
label suppresses that label.

After changing published configuration, rebuild the application configuration cache if your deployment uses it. See [configuration troubleshooting](https://flex-fields.bjanczak.com/docs/troubleshooting.md#a-setting-change-has-no-effect).

## Configure panel density and theme

Add these options to your existing panel provider:

```php Panel provider theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Enums\Density;
use Bjanczak\FilamentFlexFields\FilamentFlexFieldsPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // Keep your existing panel configuration.
        ->plugin(
            FilamentFlexFieldsPlugin::make()
                ->density(Density::Comfortable)
                ->theme([
                    'radius' => '12px',
                    'menu_radius' => '24px',
                ]),
        );
}
```

| Density | Intended use |
| - | - |
| `Density::Compact` / `'compact'` | Denser presentation |
| `Density::Comfortable` / `'comfortable'` | Default presentation |
| `Density::Spacious` / `'spacious'` | More spacious presentation |

Density and a field's `size()` are different settings. Density supplies the shared presentation setting; size chooses the supported dimensions of an individual control. A component may also have its own spacing and layout rules.

### Theme tokens

The `theme()` method accepts literal CSS values for FLEX tokens. These aliases are available:

| Token | What it sets |
| - | - |
| `primary` or `primary_color` | Field focus-border color |
| `radius` or `field_radius` | Shared field radius |
| `menu_radius` | Shared menu radius |
| `field_bg` | Field background |
| `field_border` | Field border |
| `field_focus_ring` | Focus-ring value |
| `field_focus_ring_width` | Focus-ring width |

Use units where CSS needs them, such as `'12px'`. Theme values are values, not stylesheets: do not pass declarations, markup or URLs. For more specific supported tokens, see [extension appearance](https://flex-fields.bjanczak.com/docs/extensions/appearance.md).

> [!NOTE]
>
> Setting `primary` here overrides a FLEX focus-border token. It does not change every Filament accent or recolor every control state. Keep your panel's normal Filament color and dark-mode configuration for the wider application.

### Defaults and explicit overrides

Application `ui.density` supplies the initial density; an explicit plugin `density()` replaces it. Application `ui.theme` supplies theme defaults; plugin `theme()` merges the supplied keys over those defaults. A field's explicit size or variant controls that field rather than changing every control on the page.

For service options such as disks, providers and queues, use the relevant [Media OS configuration](https://flex-fields.bjanczak.com/docs/media-os-configuration.md) or component guide. Their precedence is specific to that feature.

### Navigation settings

Add these methods to the same plugin instance when you want to adjust its navigation:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\FilamentFlexFieldsPlugin;

FilamentFlexFieldsPlugin::make()
    ->navigationGroup('Tools')
    ->navigationLabel('FLEX')
    ->navigationIcon('hugeicons-dashboard-square-01')
    ->navigationSort(91);
```

These settings organize FLEX's panel navigation. They do not change the resource models or field values. The application-wide `navigation.sort` config key supplies the default sort position.

## Compare sizes without changing the style

Text Input supports `sm`, `md` and `lg`. Its package defaults are `md` and `primary`, unless your application changes the defaults.

```php Small theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;

FlexTextInput::make('reference')
    ->size('sm')
    ->variant('primary');
```

```php Medium theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;

FlexTextInput::make('reference')
    ->size('md')
    ->variant('primary');
```

```php Large theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;

FlexTextInput::make('reference')
    ->size('lg')
    ->variant('primary');
```

## Choose a supported variant

Variant names belong to each component family:

| Component | Supported variants |
| - | - |
| [Text Input](https://flex-fields.bjanczak.com/docs/flextextinput.md) | `primary`, `secondary`, `soft`, `flat` |
| [Select](https://flex-fields.bjanczak.com/docs/selectfield.md) | `bordered`, `secondary`, `flat`, `faded`, `soft`, `underlined`, `item-card` |
| [File Upload](https://flex-fields.bjanczak.com/docs/flexfileupload-and-fleximageupload.md) | `primary`, `secondary`, `flat` |
| [Date and time](https://flex-fields.bjanczak.com/docs/date-time-configuration.md) | `primary`, `secondary`, `flat` |

For example, these fields use different presentation settings on the same form:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\SelectField;

$fields = [
    FlexTextInput::make('reference')
        ->size('sm')
        ->variant('primary'),

    SelectField::make('department')
        ->options([
            'design' => 'Design',
            'engineering' => 'Engineering',
            'operations' => 'Operations',
        ])
        ->size('md')
        ->variant('secondary'),
];
```

Here `department` is a text attribute storing one of the three string identifiers. Use valid record identifiers and a configured relationship if the selection represents a related model.

## Enable features on the field that needs them

```php Emoji input theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;

FlexTextInput::make('message')
    ->emojiPicker();
```

```php Image editor theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexImageUpload;

FlexImageUpload::make('photo')
    ->imagesOnly()
    ->imageEditor()
    ->imageEditorAspectRatios([null, '16:9', '4:3', '1:1']);
```

Enabling the image editor on one upload does not enable it on every upload. File information editing is a separate, opt-in feature: choose its fields and languages in the [metadata guide](https://flex-fields.bjanczak.com/docs/file-upload-metadata.md).

[Assets & performance](https://flex-fields.bjanczak.com/docs/asset-loading.md) explains how these choices affect loading. Browser-dependent features also have [requirements](https://flex-fields.bjanczak.com/docs/requirements.md#browser-and-device-features).

## Languages, dates and direction

These choices solve different problems:

| Choice | Meaning |
| - | - |
| Application translation language | Labels and messages from Laravel language files |
| Field locale | Formatting or calendar labels where that field supports it |
| Content locales | The languages your users can edit for a translated attribute |
| Default/fallback locale | Which language a configured workflow uses when text is missing |
| RTL direction | Reading and layout direction |
| Timezone | The meaning or presentation of time in the relevant workflow |

Bundled UI catalogs are available for English (`en`), Polish (`pl`), German
(`de`), French (`fr`), Spanish (`es`), Italian (`it`), Dutch (`nl`) and Brazilian
Portuguese (`pt_BR`). They live in `resources/lang/` inside the package. Publish
application overrides to `lang/vendor/filament-flex-fields/{locale}/` with
`php artisan vendor:publish --tag=filament-flex-fields-translations`.
Translation keys and Laravel replacement tokens are checked across every bundled
catalog. Application labels and option content remain application-owned.

Default labels, placeholders, validation presets and action text resolve when
read, using the current application language. This includes retained rich editor
tools and action schemas, upload metadata, Todo actions, schedule switches and
verification/card footer actions. The Phone and Currency menus refresh their
localized catalogs when their language changes while keeping stored codes intact.
Explicit custom labels remain unchanged; use a callback such as
`->label(fn () => __('app.customer_name'))` for an application label that should
also follow later locale changes. For the empty translation badge, `null` in
`translatable.empty_badge_label` uses the translated default; a custom string
keeps that exact text. Browser-owned widgets need their normal render/lifecycle
update after changing application language; changing a PHP locale does not
mutate an already loaded browser session by itself.

Select content languages explicitly with FLEX translation tabs:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextInput;
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\TranslatableFields;

TranslatableFields::make('Product title')
    ->locales([
        'en' => 'English',
        'pl' => 'Polski',
        'de' => 'Deutsch',
    ])
    ->directionByLocale()
    ->schema([
        FlexTextInput::make('title')->maxLength(150),
    ]);
```

JSON mode needs a matching `title` JSON column and array cast. [TranslatableFields](https://flex-fields.bjanczak.com/docs/translatablefields.md) describes locale configuration and optional Spatie storage. [Upload metadata](https://flex-fields.bjanczak.com/docs/file-upload-metadata.md) separately describes selected translated fields, default-language requirements and display fallback. A fallback does not create missing saved translations.

For dates, `locale()` and `timeZone()` have specific meanings; see [date/time configuration](https://flex-fields.bjanczak.com/docs/date-time-configuration.md). Do not assume that changing language converts stored timestamps.

## Reuse layouts and controls

Use [Item Card](https://flex-fields.bjanczak.com/docs/itemcard.md) to group related fields, [Segment Tabs](https://flex-fields.bjanczak.com/docs/segmenttabs.md) to separate tasks and [TranslatableFields](https://flex-fields.bjanczak.com/docs/translatablefields.md) for language editing. Keep each child field's data and configuration on the child.

For a reusable custom component, [compose real child controls](https://flex-fields.bjanczak.com/docs/extensions/child-php-api.md). Share their renderer and declared assets rather than copying their HTML, CSS and JavaScript.

> **[Save the right value](https://flex-fields.bjanczak.com/docs/data-and-validation.md)**
>
> Match columns, casts and validation to your fields.

> **[Understand resource loading](https://flex-fields.bjanczak.com/docs/asset-loading.md)**
>
> See how instances and optional features share assets.

## Monitoring events

FLEX uses [standard Laravel activity events](https://flex-fields.bjanczak.com/docs/sre-runbook.md#application-events-and-monitoring)
for search, uploads, retention and barcode notifications. Register application
listeners to collect metrics or write logs; there is no FLEX monitoring driver or
`enterprise` switch. Use queued listeners for slow external integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.