Toggle buttons

You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament.Looking for the current stable version? Visit the 5.x documentation.

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'
    ])

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.

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,
    ])

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',
    ])

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().

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())

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())

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())

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',
    ])

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)

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)

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')

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.

Introduction

Guides

Resources

Tables

Schemas

Forms

Infolists

Actions

Notifications

Widgets

Configuration

Navigation

Users

Styling

Advanced

Testing

Plugins

Components

Deployment

Upgrading

Introduction

Changing the color of option buttons

Adding icons to option buttons

Adding tooltips to option buttons

Changing the button size

Boolean options

Positioning the options inline with each other

Grouping option buttons

Filling the container’s width

Selecting multiple buttons

Splitting options into columns

Setting the grid direction

Disabling specific options

​Introduction

​Changing the color of option buttons

​Adding icons to option buttons

​Adding tooltips to option buttons

​Changing the button size

​Boolean options

​Positioning the options inline with each other

​Grouping option buttons

​Filling the container’s width

​Selecting multiple buttons

​Splitting options into columns

​Setting the grid direction

​Disabling specific options

Introduction

Changing the color of option buttons

Adding icons to option buttons

Adding tooltips to option buttons

Changing the button size

Boolean options

Positioning the options inline with each other

Grouping option buttons

Filling the container’s width

Selecting multiple buttons

Splitting options into columns

Setting the grid direction

Disabling specific options