Toggle buttons

Introduction

The toggle buttons input provides a group of buttons for selecting a single value, or multiple values, from a list of predefined options:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])

As well as allowing a static array, the options() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

By default, the field stores one selected option. Selecting that option again clears the field to null.

With required(), a single-select field uses radio buttons styled as buttons. The field can start empty, but once you select an option, you can only replace it with another option, not clear it by selecting it again. You can navigate between options using the arrow keys.

Use multiple() to store more than one option. In multiple-select fields, required() prevents submitting an empty value but still allows you to deselect every option while editing.

Changing the color of option buttons

You can change the color of the option buttons using the colors() method. Each key in the array should correspond to an option value:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])
    ->colors([
        'draft' => 'info',
        'scheduled' => 'warning',
        'published' => 'success',
    ])

If you are using an enum for the options, you can use the HasColor interface to define colors instead.

As well as allowing a static array, the colors() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Adding icons to option buttons

You can add icon to the option buttons using the icons() method. Each key in the array should correspond to an option value, and the value may be any valid icon:

use Filament\Forms\Components\ToggleButtons;
use Filament\Support\Icons\Heroicon;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])
    ->icons([
        'draft' => Heroicon::OutlinedPencil,
        'scheduled' => Heroicon::OutlinedClock,
        'published' => Heroicon::OutlinedCheckCircle,
    ])

As well as allowing a static array, the icons() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

If you are using an enum for the options, you can use the HasIcon interface to define icons instead.

If you want to display only icons, you can use hiddenButtonLabels() to hide the option labels.

Adding tooltips to option buttons

You can add different tooltips to each option button using the tooltips() method.

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->tooltips([
        'draft' => 'Set as a draft before publishing.',
        'scheduled' => 'Schedule publishing on a specific date.',
        'published' => 'Publish now',
    ])

As well as allowing a static array, the tooltips() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Changing the button size

By default, toggle buttons use the medium size. You can change the size using the size() method:

use Filament\Forms\Components\ToggleButtons;
use Filament\Support\Enums\Size;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->size(Size::Small)

The available sizes are Size::ExtraSmall, Size::Small, Size::Medium, Size::Large, and Size::ExtraLarge. You can also pass their backed values ('xs', 'sm', 'md', 'lg', and 'xl'). Any other string is applied as a custom CSS class. Passing null restores the default medium size. The button size is also applied when using grouped().

As well as allowing a static value, the size() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Boolean options

If you want a simple boolean toggle button group, with "Yes" and "No" options, you can use the boolean() method:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()

The options will have colors and icons set up automatically, but you can override these with colors() or icons().

To customize the "Yes" label, you can use the trueLabel argument on the boolean() method:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean(trueLabel: 'Absolutely!')

To customize the "No" label, you can use the falseLabel argument on the boolean() method:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean(falseLabel: 'Not at all!')

Positioning the options inline with each other

You may wish to display the buttons inline() with each other:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline()

Optionally, you may pass a boolean value to control if the buttons should be inline or not:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline(FeatureFlag::active())

As well as allowing a static value, the inline() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Grouping option buttons

You may wish to group option buttons together so they are more compact, using the grouped() method. This also makes them appear horizontally inline with each other:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->grouped()

Optionally, you may pass a boolean value to control if the buttons should be grouped or not:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->grouped(FeatureFlag::active())

As well as allowing a static value, the grouped() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Filling the container's width

By default, the buttons only take up as much horizontal space as they need. You may use the fullWidth() method to allow buttons to stretch and fill the available width of their container. This can be used with the default (stacked) configuration, or alongside both inline() and grouped() methods:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline()
    ->fullWidth()

Optionally, you may pass a boolean value to control if the buttons should fill the container width or not:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline()
    ->fullWidth(FeatureFlag::active())

As well as allowing a static value, the fullWidth() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Selecting multiple buttons

The multiple() method on the ToggleButtons component allows you to select multiple values from the list of options:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('technologies')
    ->multiple()
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])

These options are returned in JSON format. If you're saving them using Eloquent, you should be sure to add an array cast to the model property:

use Illuminate\Database\Eloquent\Model;

class App extends Model
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    { 
        return [
            'technologies' => 'array',
        ];
    }

    // ...
}

Optionally, you may pass a boolean value to control if the buttons should allow multiple selections or not:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('technologies')
    ->multiple(FeatureFlag::active())
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])

As well as allowing a static value, the multiple() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Splitting options into columns

You may split options into columns by using the columns() method:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)

As well as allowing a static value, the columns() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

This method accepts the same options as the columns() method of the grid. This allows you to responsively customize the number of columns at various breakpoints.

Setting the grid direction

By default, when you arrange buttons into columns, they will be listed in order vertically. If you'd like to list them horizontally, you may use the gridDirection(GridDirection::Row) method:

use Filament\Forms\Components\ToggleButtons;
use Filament\Support\Enums\GridDirection;

ToggleButtons::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
    ->gridDirection(GridDirection::Row)

As well as allowing a static value, the gridDirection() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Disabling specific options

You can disable specific options using the disableOptionWhen() method. It accepts a closure, in which you can check if the option with a specific $value should be disabled:

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')

You can inject various utilities into the function as parameters.

If you want to retrieve the options that have not been disabled, e.g. for validation purposes, you can do so using getEnabledOptions():

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')
    ->in(fn (ToggleButtons $component): array => array_keys($component->getEnabledOptions()))

For more information about the in() function, please see the Validation documentation.