webkernel/platform-forms

18-toggle-buttons

On this page

title: 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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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

required() prevents submitting an empty value, but does not prevent clearing the selection while editing. Use multiple() to store more than one option.

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 Webkernel\Platform\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.

<UtilityInjection set="formFields">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.</UtilityInjection>

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 Webkernel\Platform\Forms\Components\ToggleButtons;
use Webkernel\Platform\Support\Icons\Heroicon;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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

<UtilityInjection set="formFields">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.</UtilityInjection>

Changing the button size

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

use Webkernel\Platform\Forms\Components\ToggleButtons;
use Webkernel\Platform\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().

<UtilityInjection set="formFields">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.</UtilityInjection>

Boolean options

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

use Webkernel\Platform\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 Webkernel\Platform\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 Webkernel\Platform\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 Webkernel\Platform\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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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 Webkernel\Platform\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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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 Webkernel\Platform\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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

Selecting multiple buttons

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

use Webkernel\Platform\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 Webkernel\ORM\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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

Splitting options into columns

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

use Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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 Webkernel\Platform\Forms\Components\ToggleButtons;
use Webkernel\Platform\Support\Enums\GridDirection;

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

<UtilityInjection set="formFields">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.</UtilityInjection>

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 Webkernel\Platform\Forms\Components\ToggleButtons;

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

<UtilityInjection set="formFields" extras="Option value;;mixed;;$value;;The value of the option to disable.||Option label;;string | Webkernel\Utilities\Contracts\Htmlable;;$label;;The label of the option to disable.">You can inject various utilities into the function as parameters.</UtilityInjection>

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

use Webkernel\Platform\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.