> ## 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.

# Performance choices

> Bounded prefetch, large option lists, virtualization, pagination and smaller image previews in FLEX Fields.

## Interaction comes before speculative loading

FLEX distinguishes work needed for an interaction from lower-priority preparation. Loading concurrency and optional prefetch are bounded, rather than creating an unlimited set of background requests.

Resolved resource plans use bounded caches. Lifecycle handling focuses on changed page regions where possible, avoiding repeated work over every unchanged field after a local update. Factory registration tracks implementation identities rather than silently wrapping the same factory again.

These optimizations concern resource and initialization work. They do not make an unbounded SQL query or a full-resolution preview cheap.

## Configure large datasets deliberately

**Virtualization limits rendered rows. Pagination limits fetched results.** Use both when your dataset calls for them:

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

$departmentOptions = [];

for ($number = 1; $number <= 500; $number++) {
    $departmentOptions['department-'.$number] = 'Department '.$number;
}

SelectField::make('department')
    ->options($departmentOptions)
    ->virtualizeThreshold(40)
    ->virtualRowHeight(40)
    ->virtualWindowSize(30);
```

This demonstration crosses the threshold and uses string identifiers suitable for a text attribute. It still supplies all 500 options. For large database or remote catalogs, use [Select's paginated provider](https://flex-fields.bjanczak.com/docs/selectfield.md) with scoped search instead of fetching everything first.

## Use the right image for a preview

Configure a named image conversion, then select it for previews. Selecting the preview alone does not create the conversion:

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

FlexImageUpload::make('photo')
    ->imagesOnly()
    ->previewConversion('thumb');
```

The `thumb` conversion must exist in your [native image configuration](https://flex-fields.bjanczak.com/docs/media-os-images.md) or [Spatie model configuration](https://flex-fields.bjanczak.com/docs/media-os-spatie.md). Local preview generation and persisted preview selection are separate settings; see [image previews](https://flex-fields.bjanczak.com/docs/file-upload-images-and-sources.md).

If processing is queued, run the configured worker. Native and Spatie conversions retain the original, and a missing or pending conversion follows the chosen preview/fallback behavior.

## Continue reading

[Asset Manager overview](https://flex-fields.bjanczak.com/docs/asset-loading.md) · [Resource sharing](https://flex-fields.bjanczak.com/docs/assets/sharing.md) · [Activation & cleanup](https://flex-fields.bjanczak.com/docs/assets/lifecycle.md) · [Performance](https://flex-fields.bjanczak.com/docs/assets/performance.md) · [Publish & diagnose](https://flex-fields.bjanczak.com/docs/assets/deployment.md)


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