ContextQMD
Back to Filament

Grouping actions

packages/actions/docs/03-grouping-actions.md

5.6.25.9 KB
Original Source

import AutoScreenshot from "@components/AutoScreenshot.astro" import UtilityInjection from "@components/UtilityInjection.astro"

Introduction

You may group actions together into a dropdown menu by using an ActionGroup object. Groups may contain many actions, or other groups:

php
use Filament\Actions\Action;
use Filament\Actions\ActionGroup;

ActionGroup::make([
    Action::make('view'),
    Action::make('edit'),
    Action::make('delete'),
])
<AutoScreenshot name="actions/group/simple" alt="Action group" version="5.x" />

This page is about customizing the look of the group's trigger button and dropdown.

Customizing the group trigger style

The button which opens the dropdown may be customized in the same way as a normal action. All the methods available for trigger buttons may be used to customize the group trigger button:

php
use Filament\Actions\ActionGroup;
use Filament\Support\Enums\Size;

ActionGroup::make([
    // Array of actions
])
    ->label('More actions')
    ->icon('heroicon-m-ellipsis-vertical')
    ->size(Size::Small)
    ->color('primary')
    ->button()
<AutoScreenshot name="actions/group/customized" alt="Action group with custom trigger style" version="5.x" /> <AutoScreenshot name="tables/actions/group-button" alt="Table with button action group" version="5.x" />

Adding a tooltip to the group trigger button

You may add a tooltip to the group trigger button using the tooltip() method:

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    // Array of actions
])
    ->tooltip('Actions')
<AutoScreenshot name="tables/actions/group-tooltip" alt="Table with action group tooltip" version="5.x" />

Using a grouped button design

Instead of a dropdown, an action group can render itself as a group of buttons. This design works with and without button labels. To use this feature, use the buttonGroup() method:

php
use Filament\Actions\Action;
use Filament\Actions\ActionGroup;
use Filament\Support\Icons\Heroicon;

ActionGroup::make([
    Action::make('edit')
        ->color('gray')
        ->icon(Heroicon::PencilSquare)
        ->hiddenLabel(),
    Action::make('delete')
        ->color('gray')
        ->icon(Heroicon::Trash)
        ->hiddenLabel(),
])
    ->buttonGroup()
<AutoScreenshot name="actions/group/button-group" alt="Action group using the button group design" version="5.x" />

Setting the placement of the dropdown

The dropdown may be positioned relative to the trigger button by using the dropdownPlacement() method:

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    // Array of actions
])
    ->dropdownPlacement('top-start')

<UtilityInjection set="actionGroups" version="5.x">The dropdownPlacement() method also accepts a function to dynamically calculate the value. You can inject various utilities into the function as parameters.</UtilityInjection>

<AutoScreenshot name="actions/group/placement" alt="Action group with top placement style" version="5.x" />

Alternatively, you may let the dropdown position be automatically determined based on the available space using the dropdownAutoPlacement() method:

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    // Array of actions
])
    ->dropdownAutoPlacement()

Adding dividers between actions

You may add dividers between groups of actions by using nested ActionGroup objects:

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    ActionGroup::make([
        // Array of actions
    ])->dropdown(false),
    // Array of actions
])

The dropdown(false) method puts the actions inside the parent dropdown, instead of a new nested dropdown.

<UtilityInjection set="actionGroups" version="5.x">The dropdown() method also accepts a function to dynamically calculate the value. You can inject various utilities into the function as parameters.</UtilityInjection>

<AutoScreenshot name="actions/group/nested" alt="Action groups nested with dividers" version="5.x" />

Setting the width of the dropdown

The dropdown may be set to a width by using the dropdownWidth() method. Options correspond to Tailwind's max-width scale. The options are ExtraSmall, Small, Medium, Large, ExtraLarge, TwoExtraLarge, ThreeExtraLarge, FourExtraLarge, FiveExtraLarge, SixExtraLarge and SevenExtraLarge:

php
use Filament\Actions\ActionGroup;
use Filament\Support\Enums\Width;

ActionGroup::make([
    // Array of actions
])
    ->dropdownWidth(Width::ExtraSmall)
<AutoScreenshot name="actions/group/dropdown-width" alt="Action group with custom dropdown width" version="5.x" />

<UtilityInjection set="actionGroups" version="5.x">The dropdownWidth() method also accepts a function to dynamically calculate the value. You can inject various utilities into the function as parameters.</UtilityInjection>

Controlling the dropdown offset

You may control the offset of the dropdown using the dropdownOffset() method, by default the offset is set to 8.

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    // Array of actions
])
    ->dropdownOffset(16)

<UtilityInjection set="actionGroups" version="5.x">The dropdownOffset() method also accepts a function to dynamically calculate the value. You can inject various utilities into the function as parameters.</UtilityInjection>

Controlling the maximum height of the dropdown

The dropdown content can have a maximum height using the maxHeight() method, so that it scrolls. You can pass a CSS length:

php
use Filament\Actions\ActionGroup;

ActionGroup::make([
    // Array of actions
])
    ->maxHeight('400px')

<UtilityInjection set="actionGroups" version="5.x">The maxHeight() method also accepts a function to dynamically calculate the value. You can inject various utilities into the function as parameters.</UtilityInjection>