Grid

#Overview

Filament's grid system allows you to create responsive, multi-column layouts using any layout component.

#Responsively setting the number of grid columns

All layout components have a columns() method that you can use in a couple of different ways:

• You can pass an integer like columns(2). This integer is the number of columns used on the lg breakpoint and higher. All smaller devices will have just 1 column.
• You can pass an array, where the key is the breakpoint and the value is the number of columns. For example, columns(['md' => 2, 'xl' => 4]) will create a 2 column layout on medium devices, and a 4 column layout on extra large devices. The default breakpoint for smaller devices uses 1 column, unless you use a default array key.

Breakpoints (sm, md, lg, xl, 2xl) are defined by Tailwind, and can be found in the Tailwind documentation.

#Controlling how many columns a component should span

In addition to specifying how many columns a layout component should have, you may also specify how many columns a component should fill within the parent grid, using the columnSpan() method. This method accepts an integer or an array of breakpoints and column spans:

• columnSpan(2) will make the component fill up to 2 columns on all breakpoints.
• columnSpan(['md' => 2, 'xl' => 4]) will make the component fill up to 2 columns on medium devices, and up to 4 columns on extra large devices. The default breakpoint for smaller devices uses 1 column, unless you use a default array key.
• columnSpan('full') or columnSpanFull() or columnSpan(['default' => 'full']) will make the component fill the full width of the parent grid, regardless of how many columns it has.

#An example of a responsive grid layout

In this example, we have a form with a section layout component. Since all layout components support the columns() method, we can use it to create a responsive grid layout within the section itself.

We pass an array to columns() as we want to specify different numbers of columns for different breakpoints. On devices smaller than the sm Tailwind breakpoint, we want to have 1 column, which is default. On devices larger than the sm breakpoint, we want to have 3 columns. On devices larger than the xl breakpoint, we want to have 6 columns. On devices larger than the 2xl breakpoint, we want to have 8 columns.

Inside the section, we have a text input. Since text inputs are form components and all form components have a columnSpan() method, we can use it to specify how many columns the text input should fill. On devices smaller than the sm breakpoint, we want the text input to fill 1 column, which is default. On devices larger than the sm breakpoint, we want the text input to fill 2 columns. On devices larger than the xl breakpoint, we want the text input to fill 3 columns. On devices larger than the 2xl breakpoint, we want the text input to fill 4 columns.

use Filament\Forms\Components\Section;
use Filament\Forms\Components\TextInput;
 
Section::make()
    ->columns([
        'sm' => 3,
        'xl' => 6,
        '2xl' => 8,
    ])
    ->schema([
        TextInput::make('name')
            ->columnSpan([
                'sm' => 2,
                'xl' => 3,
                '2xl' => 4,
            ]),
        // ...
    ])
use Filament\Forms\Components\Section;
use Filament\Forms\Components\TextInput;

Section::make()
    ->columns([
        'sm' => 3,
        'xl' => 6,
        '2xl' => 8,
    ])
    ->schema([
        TextInput::make('name')
            ->columnSpan([
                'sm' => 2,
                'xl' => 3,
                '2xl' => 4,
            ]),
        // ...
    ])

#Grid component

All layout components support the columns() method, but you also have access to an additional Grid component. If you feel that your form schema would benefit from an explicit grid syntax with no extra styling, it may be useful to you. Instead of using the columns() method, you can pass your column configuration directly to Grid::make():

use Filament\Forms\Components\Grid;
 
Grid::make([
    'default' => 1,
    'sm' => 2,
    'md' => 3,
    'lg' => 4,
    'xl' => 6,
    '2xl' => 8,
])
    ->schema([
        // ...
    ])
use Filament\Forms\Components\Grid;

Grid::make([
    'default' => 1,
    'sm' => 2,
    'md' => 3,
    'lg' => 4,
    'xl' => 6,
    '2xl' => 8,
])
    ->schema([
        // ...
    ])

#Setting the starting column of a component in a grid

If you want to start a component in a grid at a specific column, you can use the columnStart() method. This method accepts an integer, or an array of breakpoints and which column the component should start at:

• columnStart(2) will make the component start at column 2 on all breakpoints.
• columnStart(['md' => 2, 'xl' => 4]) will make the component start at column 2 on medium devices, and at column 4 on extra large devices. The default breakpoint for smaller devices uses 1 column, unless you use a default array key.

use Filament\Forms\Components\Section;
 
Section::make()
    ->columns([
        'sm' => 3,
        'xl' => 6,
        '2xl' => 8,
    ])
    ->schema([
        TextInput::make('name')
            ->columnStart([
                'sm' => 2,
                'xl' => 3,
                '2xl' => 4,
            ]),
        // ...
    ])
use Filament\Forms\Components\Section;

Section::make()
    ->columns([
        'sm' => 3,
        'xl' => 6,
        '2xl' => 8,
    ])
    ->schema([
        TextInput::make('name')
            ->columnStart([
                'sm' => 2,
                'xl' => 3,
                '2xl' => 4,
            ]),
        // ...
    ])

In this example, the grid has 3 columns on small devices, 6 columns on extra large devices, and 8 columns on extra extra large devices. The text input will start at column 2 on small devices, column 3 on extra large devices, and column 4 on extra extra large devices. This is essentially producing a layout whereby the text input always starts halfway through the grid, regardless of how many columns the grid has.

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion