NpsField - FLEX Fields

Summary

Single-select survey scale for Net Promoter Score (0–10), CSAT, satisfaction ratings, and textual Likert scales. Three visual variants share one API: pills (sliding segment control), segments (full-width bordered bar), and emojis (icon or image rings with labels).


Class	`Bjanczak\FilamentFlexFields\Filament\Forms\Components\NpsField`
State type	`string\|int\|null` — one option key, or `null` when unset
Model cast	`'nps_score' => 'integer'` · `'feedback_agreement' => 'string'`
FieldType	`FieldType::Nps` (`nps`) for saved field schemas
Playground	`nps-field` slug in Flex Fields playground
Default variant	`pills`
Default scale	`0` through `10` (numeric keys and labels)
Default state	`null` (no pre-selection)

Works with all standard Filament field APIs: required(), disabled(), hidden(), live(), afterStateUpdated(), validation rules, etc.

Variants at a glance

Variant	Value	Best for
Pills	`'pills'` (default)	Classic NPS 0–10, compact scales, sliding primary indicator
Segments	`'segments'`	Full-width 0–10 bar, experience ratings, Likert with many options
Emojis	`'emojis'`	Mood / satisfaction with icons or bundled emoji images

NpsField::make('nps')->variant('pills');     // default
NpsField::make('nps')->variant('segments');
NpsField::make('mood')->variant('emojis');

Basic usage

Standard NPS (0–10)

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

NpsField::make('nps_score')
    ->label('How likely are you to recommend us to a friend or colleague?')
    ->minLabel('Not at all likely')
    ->maxLabel('Extremely likely')
    ->required();

Filament resource form

use Filament\Schemas\Schema;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\NpsField;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        NpsField::make('nps_score')
            ->label('Recommendation score')
            ->minLabel('Unlikely')
            ->maxLabel('Very likely')
            ->colorCoded()
            ->columnSpanFull()
            ->required(),
    ]);
}

Color-coded NPS (Detractor / Passive / Promoter)

NpsField::make('nps_score')
    ->label('Recommendation')
    ->minLabel('Detractor')
    ->maxLabel('Promoter')
    ->colorCoded();

Score	Tone	Selected color
0–6	Detractor	Red (`danger`)
7–8	Passive	Yellow (`warning`)
9–10	Promoter	Green (`success`)

State & validation

Stored value

State is the option key from options() — not the display label.

// Default 0–10 scale
$record->nps_score; // int|null — e.g. 9

// Likert scale with string keys
$record->agreement; // string|null — e.g. 'sa'

Default: empty initial state

The field defaults to null. Nothing is selected until the user picks an option. All variants support this.

NpsField::make('nps_score')
    ->label('Optional feedback')
    // default is null — no ->default() needed

Set the initial value for a new form. Editing reads the saved model value:

NpsField::make('nps_score')
    ->default(8);

Validation rules (built-in)

Rule	When
`nullable`	Always (unless `required()`)
Enabled option membership	Value must match a configured, enabled option key
Value shape	Rejects booleans, arrays, fractional scores and unknown keys
`required`	When `->required()`

NpsField::make('nps_score')
    ->options(array_combine(range(1, 5), range(1, 5)))
    ->required();

// Custom rules stack on top
NpsField::make('nps_score')
    ->rules(['integer', 'min:1']);

Optional fields — deselect on second click

When the field is not required(), clicking the already selected option clears the value back to null. Required fields always keep one selection.

NpsField::make('nps_score')
    ->label('Optional NPS')
    ->minLabel('Low')
    ->maxLabel('High');
// User can click 7, then click 7 again to clear

Custom scales

5-point CSAT (1–5)

NpsField::make('csat')
    ->label('Overall satisfaction')
    ->options(array_combine(range(1, 5), range(1, 5)))
    ->minLabel('Very dissatisfied')
    ->maxLabel('Very satisfied')
    ->required();

3-point quick rating

NpsField::make('quick_rating')
    ->options([
        1 => 'Bad',
        2 => 'Okay',
        3 => 'Good',
    ])
    ->size('sm');

Textual Likert scale (string keys)

NpsField::make('agreement')
    ->label('I find this product easy to use')
    ->variant('segments')
    ->options([
        'sd' => 'Strongly Disagree',
        'd' => 'Disagree',
        'n' => 'Neutral',
        'a' => 'Agree',
        'sa' => 'Strongly Agree',
    ])
    ->required();

Dynamic options with a closure

NpsField::make('priority')
    ->options(fn (): array => [
        'low' => __('Low'),
        'medium' => __('Medium'),
        'high' => __('High'),
    ]);

Variant: Pills (default)

Sliding pill indicator on a gray track — same visual language as SegmentControl. Best for numeric scales and compact layouts.

NpsField::make('nps_score')
    ->variant('pills')
    ->minLabel('Not likely')
    ->maxLabel('Very likely');

Sizes

NpsField::make('nps_score')->size('sm'); // default: md
NpsField::make('nps_score')->size('lg');

See Control size (sm, md, lg).

Rounding

NpsField::make('nps_score')
    ->rounding('full'); // 'default', 'native', 'md', 'lg', 'xl', 'full'

Per-field rounding() overrides the global default from config/filament-flex-fields.php (ui.field_rounding).

Variant: Segments

Full-width bordered bar with vertical dividers between options. Ideal for 0–10 NPS and multi-option Likert rows.

NpsField::make('experience')
    ->label('How would you rate your experience?')
    ->variant('segments')
    ->size('md')
    ->rounding('full')
    ->required();

Segments with sizes and rounding

NpsField::make('experience_sm')
    ->variant('segments')
    ->size('sm')
    ->rounding('full');

NpsField::make('experience_lg')
    ->variant('segments')
    ->size('lg')
    ->rounding('md');

Variant: Emojis

Circular rings with a visual inside each option and a text label below. Three ways to supply visuals (priority order):

icons() — registered Blade icon names (Hugeicons and other installed sets)
emojiImages() — custom image URLs
Bundled webp — for numeric keys 0–4 when neither of the above is set

Bundled emoji images (5-point mood scale)

NpsField::make('mood')
    ->label('How are you feeling today?')
    ->variant('emojis')
    ->options([
        0 => 'Awful',
        1 => 'Poor',
        2 => 'Neutral',
        3 => 'Good',
        4 => 'Excellent',
    ])
    ->required();

All five emoji images ship with the package and are published by php artisan filament:assets. Their URLs are resolved automatically from the current asset release and respect your filament.assets_path setting. You do not need to configure image paths.

Custom Hugeicons

use Bjanczak\FilamentFlexFields\Support\FlexIcon;

NpsField::make('mood')
    ->variant('emojis')
    ->options([
        0 => 'Awful',
        1 => 'Poor',
        2 => 'Neutral',
        3 => 'Good',
        4 => 'Excellent',
    ])
    ->icons([
        0 => FlexIcon::CircleXmark,
        1 => FlexIcon::Hand,
        2 => FlexIcon::FaceSmile,
        3 => FlexIcon::Heart,
        4 => FlexIcon::Star,
    ]);

Heroicon example:

NpsField::make('mood')
    ->variant('emojis')
    ->options([0 => 'Bad', 1 => 'Good'])
    ->icons([
        0 => 'heroicon-o-face-frown',
        1 => 'heroicon-o-face-smile',
    ]);

When icons() is set for a key, it overrides bundled webp for that key.

Custom image URLs

NpsField::make('mood')
    ->variant('emojis')
    ->options([
        0 => 'Awful',
        1 => 'Poor',
        2 => 'Neutral',
        3 => 'Good',
        4 => 'Excellent',
    ])
    ->emojiImages([
        0 => asset('images/survey/awful.svg'),
        1 => asset('images/survey/poor.svg'),
        2 => asset('images/survey/neutral.svg'),
        3 => asset('images/survey/good.svg'),
        4 => asset('images/survey/excellent.svg'),
    ]);

Emoji sizes

NpsField::make('mood')->variant('emojis')->size('sm');
NpsField::make('mood')->variant('emojis')->size('lg');

Color coding & custom colors

Built-in NPS color coding

NpsField::make('nps_score')
    ->colorCoded()
    ->variant('pills'); // works on all variants

Custom per-option background colors

Map Filament semantic names, hex, or rgb to option keys:

NpsField::make('risk')
    ->options(array_combine(range(1, 5), range(1, 5)))
    ->colors([
        'danger' => [1, 2],
        'warning' => [3],
        'success' => [4, 5],
    ]);

With hex:

NpsField::make('heat')
    ->options(['cold' => 'Cold', 'warm' => 'Warm', 'hot' => 'Hot'])
    ->colors([
        '#3b82f6' => 'cold',
        '#f59e0b' => 'warm',
        '#ef4444' => 'hot',
    ]);

Custom selected text colors

NpsField::make('nps_score')
    ->options(array_combine(range(0, 10), range(0, 10)))
    ->colors(['danger' => range(0, 6), 'success' => range(9, 10)])
    ->textColors([
        '#ffffff' => [...range(0, 6), ...range(9, 10)],
    ]);

With colorCoded() enabled, the built-in NPS palette takes priority. Leave it disabled when using your own colors() and textColors() mappings. Built-in tones apply only to exact scores from 0 through 10; textual scales remain neutral.

Disabled options

Disable individual keys without disabling the whole field. These keys are also rejected during server-side form validation, including direct submissions:

NpsField::make('nps_score')
    ->disabledOptions([0, 1])
    ->helperText('Scores 0 and 1 are not available for this survey.');

Dynamic:

NpsField::make('nps_score')
    ->disabledOptions(fn (): array => auth()->user()?->isDemo() ? range(0, 5) : []);

Combine with field-level disabled():

NpsField::make('nps_score')
    ->disabled()
    ->default(8);

Edge labels

Show helper text under the left and right ends of the scale:

NpsField::make('nps_score')
    ->minLabel('Not at all likely')
    ->maxLabel('Extremely likely');

Only the extremes are labeled — option labels come from options() values.

Complete configuration API

All methods accept Closure unless noted.

Method	Type	Default	Description
`variant(string\|Closure $variant)`	Setup	`'pills'`	Visual variant: `pills`, `segments`, `emojis`
`options(array\|Closure $options)`	Setup	`0`–`10`	Option keys => display labels
`minLabel(string\|Closure\|null $label)`	Setup	`null`	Left extreme caption
`maxLabel(string\|Closure\|null $label)`	Setup	`null`	Right extreme caption
`colorCoded(bool\|Closure $condition = true)`	Setup	`false`	NPS detractor/passive/promoter colors
`colors(array\|Closure\|null $colors)`	Setup	`[]`	Custom selected background colors per key
`textColors(array\|Closure\|null $textColors)`	Setup	`[]`	Custom selected text colors per key
`icons(array\|Closure $icons)`	Setup	`[]`	Emoji variant: key => Filament icon string
`emojiImages(array\|Closure\|null $images)`	Setup	`null`	Emoji variant: key => image URL
`disabledOptions(array\|Closure $keys)`	Setup	`[]`	Keys that cannot be selected
`size(string\|ControlSize\|Closure $size)`	Setup	`'md'`	Control size: `sm`, `md`, `lg`
`rounding(string\|Closure\|null $rounding)`	Setup	config	Border radius token
`default(mixed $state)`	Setup	`null`	Initial state (Filament API)
`required(bool\|Closure $condition = true)`	Setup	optional	Require a selection; disables deselect
`disabled(bool\|Closure $condition = true)`	Setup	—	Disable entire field (Filament API)

Public helper methods

Method	Returns	Description
`getOptions()`	`array<string\|int, string\|int>`	Resolved options
`getOptionKeys()`	`list<string\|int>`	All configured keys
`getEnabledOptionKeys()`	`list<string\|int>`	Configured keys accepted by validation
`getVariant()`	`string`	Current variant
`isColorCoded()`	`bool`	Whether color coding is active
`getOptionIcon(mixed $value)`	`?string`	Icon string for emoji variant key
`getEmojiImage(mixed $value)`	`?string`	Image URL for emoji variant key
`getOptionTone(mixed $value)`	`?string`	`detractor`, `passive`, `promoter`, or `null`
`isDetractor(mixed $key)`	`bool`	NPS 0–6
`isPassive(mixed $key)`	`bool`	NPS 7–8
`isPromoter(mixed $key)`	`bool`	NPS 9–10
`isOptionDisabled(string\|int $key)`	`bool`	Whether key is disabled

Real-world examples

Resource examples use Filament\Schemas\Schema and Filament\Schemas\Components\Section. The textarea example uses Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTextareaField. Reactive callbacks use Filament\Schemas\Components\Utilities\Get and Set.

Post-purchase survey (CreateRecord)

use Filament\Resources\Pages\CreateRecord;

protected function mutateFormDataBeforeCreate(array $data): array
{
    $data['survey_completed_at'] = now();

    return $data;
}

public static function form(Schema $schema): Schema
{
    return $schema->components([
        Section::make('Feedback')->schema([
            NpsField::make('nps_score')
                ->label('How likely are you to recommend us?')
                ->colorCoded()
                ->minLabel('Not likely')
                ->maxLabel('Very likely')
                ->required(),

            NpsField::make('csat')
                ->label('Overall satisfaction')
                ->options(array_combine(range(1, 5), range(1, 5)))
                ->variant('segments')
                ->minLabel('Poor')
                ->maxLabel('Excellent'),

            NpsField::make('mood')
                ->label('How did we make you feel?')
                ->variant('emojis')
                ->options([
                    0 => 'Awful',
                    1 => 'Poor',
                    2 => 'Neutral',
                    3 => 'Good',
                    4 => 'Excellent',
                ]),
        ]),
    ]);
}

Wizard step — optional NPS

Wizard\Step::make('Feedback')->schema([
    NpsField::make('nps_score')
        ->label('Recommendation score (optional)')
        ->helperText('Click your score again to clear.')
        ->columnSpanFull(),
]),

Live reactive form

NpsField::make('nps_score')
    ->live()
    ->afterStateUpdated(function (?int $state, Set $set): void {
        if ($state !== null && $state <= 6) {
            $set('follow_up_reason', null);
        }
    }),

FlexTextareaField::make('follow_up_reason')
    ->visible(fn (Get $get): bool => filled($get('nps_score')) && (int) $get('nps_score') <= 6)
    ->required();

Infolist / table display (manual)

NpsField is a form component. Display stored values in tables with TextColumn or a custom column:

TextColumn::make('nps_score')
    ->label('NPS')
    ->formatStateUsing(fn (?int $state): string => $state === null ? '—' : (string) $state)
    ->color(fn (?int $state): ?string => match (true) {
        $state === null => null,
        $state <= 6 => 'danger',
        $state <= 8 => 'warning',
        default => 'success',
    });

Database & Eloquent

Migration

Schema::create('survey_responses', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->unsignedTinyInteger('nps_score')->nullable();
    $table->unsignedTinyInteger('csat')->nullable();
    $table->string('agreement', 2)->nullable(); // Likert keys: sd, d, n, a, sa
    $table->timestamps();
});

Model

class SurveyResponse extends Model
{
    protected $fillable = ['user_id', 'nps_score', 'csat', 'agreement'];

    protected function casts(): array
    {
        return [
            'nps_score' => 'integer',
            'csat' => 'integer',
        ];
    }

    public function isPromoter(): bool
    {
        return $this->nps_score !== null && $this->nps_score >= 9;
    }
}

Assets & deployment

Asset type	Location after publish	How
CSS / JS / Alpine	Filament public paths	`php artisan filament:assets`
Emoji webp (bundled)	Versioned asset release, under your configured Filament asset path	Same command

Bundled emoji URLs include the asset release identifier, so updated images receive new URLs without manual cache busting. Publication updates the ready-to-use assets; no frontend build is required in your application. URLs provided through emojiImages() remain exactly as configured. On upgrade, run php artisan filament:assets, or include it in your deployment workflow. See Updating FLEX Fields.

Accessibility

Root element uses role="radiogroup" with aria-label from the field label.
Each option is one accessible radio button with aria-checked; there are no duplicate hidden radios.
Tab enters the selected option, or the first enabled option when empty. Arrow keys move selection, while Home and End select the first and last enabled options.
Enter and Space activate the focused option. Horizontal arrow direction follows RTL layouts.
Focus visible outline on keyboard navigation.
Disabled options expose aria-disabled="true" and are skipped by keyboard navigation.
Reduced-motion preferences disable the sliding and hover transitions.
On narrow screens, long pill scales scroll inside the field; keyboard selection keeps the active choice visible.

Performance

Mechanism	What it does
Lazy CSS	Loads `segment-control` + `nps-field` bundles only when the field renders
Lazy JavaScript	The field runtime activates through the shared FLEX asset manager
SSR pre-selection	`data-segment-selected` on pills prevents layout flash before Alpine hydrates

The NPS field reuses shared segment-control styles through its declared asset dependency. Shared styles are loaded once. Inactive tabs and closed modals wait for activation; each mounted field owns and releases its own interaction resources. Option nodes are collected once. Resize updates share one pending animation frame; segments and emoji variants do not allocate an indicator resize observer.

Playground

/admin/flex-fields/nps-field See Playground for setup.

Component	When to use instead
SegmentControl	Generic single-select segments without survey semantics
RatingField	Star/icon ratings with fractional display
MatrixChoiceField	Grid of radio/checkbox choices
ChoiceCards	Large card-style single or multi select

CSS classes (reference)

Class	Role
`fff-nps-field`	Root wrapper
`fff-nps-field--variant-pills`	Pills variant
`fff-nps-field--variant-segments`	Segments variant
`fff-nps-field--variant-emojis`	Emojis variant
`fff-nps-field--color-coded`	NPS color coding active
`fff-nps-field--{sm\|md\|lg}`	Size variant
`fff-nps-field__track`	Options container
`fff-nps-field__segment`	Segment variant option
`fff-nps-field__emoji-ring`	Emoji variant circle
`fff-nps-field__extremes`	min/max label row

Pills variant reuses fff-segment-control, fff-segment-track, fff-segment-indicator, and fff-segment-item from SegmentControl.

​Summary

​Variants at a glance

​Basic usage

​Standard NPS (0–10)

​Filament resource form

​Color-coded NPS (Detractor / Passive / Promoter)

​State & validation

​Stored value

​Default: empty initial state

​Validation rules (built-in)

​Optional fields — deselect on second click

​Custom scales

​5-point CSAT (1–5)

​3-point quick rating

​Textual Likert scale (string keys)

​Dynamic options with a closure

​Variant: Pills (default)

​Sizes

​Rounding

​Variant: Segments

​Segments with sizes and rounding

​Variant: Emojis

​Bundled emoji images (5-point mood scale)

​Custom Hugeicons

​Custom image URLs

​Emoji sizes

​Color coding & custom colors

​Built-in NPS color coding

​Custom per-option background colors

​Custom selected text colors

​Disabled options

​Edge labels

​Complete configuration API

​Public helper methods

​Real-world examples

​Post-purchase survey (CreateRecord)

​Wizard step — optional NPS

​Live reactive form

​Infolist / table display (manual)

​Database & Eloquent

​Migration

​Model

​Assets & deployment

​Accessibility

​Performance

​Playground

​Related components

​CSS classes (reference)