Allow configuring default grid breakpoint #19019

angus-mcritchie · 2026-01-20T00:05:30Z

Summary

This PR adds the ability to configure the default grid breakpoint used when passing integers to grid methods like columns(2), columnSpan(3), columnStart(2), columnOrder(1), and grid(3).

Previously, the breakpoint was hardcoded to 'lg'. Now users can:

Configure via config/filament.php:
```
'default_grid_breakpoint' => '2xl',
```

Set programmatically (e.g., in a service provider):

use Filament\Support\Facades\FilamentGrid;

FilamentGrid::defaultBreakpoint('xl');

Changes

Added GridManager class to manage the default breakpoint
Added FilamentGrid facade for easy access
Updated all grid-related methods to use the configurable breakpoint
Added config option with documentation
Added tests for both config and programmatic approaches
Updated layouts documentation

Why?

Some applications need consistent grid behavior across different breakpoints. For example, an app optimized for large displays may want '2xl' as the default instead of 'lg'.

This is fully backward compatible - the default remains 'lg'.

Copilot

Pull request overview

This PR adds the ability to configure the default grid breakpoint used when passing integers to grid methods like columns(2), columnSpan(3), columnStart(2), columnOrder(1), and grid(3). Additionally, it includes an unrelated feature that adds a formComponent() method to SelectFilter.

Changes:

Introduced configurable default grid breakpoint via config file and programmatic API
Added GridManager class and FilamentGrid facade to manage breakpoint configuration
Updated all grid-related methods across traits to use the configurable breakpoint
Added formComponent() method to SelectFilter for custom component classes
Added comprehensive tests and documentation

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/support/src/Grid/GridManager.php	New class to manage default grid breakpoint configuration
packages/support/src/Facades/FilamentGrid.php	New facade for accessing GridManager functionality
packages/support/src/SupportServiceProvider.php	Registers GridManager and updates macros to use configurable breakpoint
packages/support/config/filament.php	Adds `default_grid_breakpoint` configuration option
packages/support/src/Concerns/CanSpanColumns.php	Updates to use configurable breakpoint instead of hardcoded 'lg'
packages/support/src/Concerns/CanOrderColumns.php	Updates to use configurable breakpoint instead of hardcoded 'lg'
packages/schemas/src/Concerns/HasColumns.php	Updates to use configurable breakpoint instead of hardcoded 'lg'
packages/schemas/src/Components/Concerns/HasContainerGridLayout.php	Updates to use configurable breakpoint instead of hardcoded 'lg'
packages/tables/src/Filters/SelectFilter.php	Adds `formComponent()` method and property for custom select components
packages/tables/src/Filters/Filter.php	Adds PHPDoc comment for existing `formComponent` property
tests/src/Forms/GridTest.php	Adds tests for configurable breakpoint functionality
tests/src/Tables/Filters/SelectFilterTest.php	Adds test for `formComponent()` method
packages/schemas/docs/02-layouts.md	Documents the new breakpoint configuration feature
packages/tables/docs/03-filters/02-select.md	Documents the new `formComponent()` method for SelectFilter
packages/tables/docs/03-filters/01-overview.md	Documents the new `formComponent()` method for Filter

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-20T00:10:21Z

packages/support/src/Grid/GridManager.php

+        $this->defaultBreakpoint = $breakpoint;
+    }
+
+    public function getDefaultBreakpoint(): string
+    {
+        return $this->evaluate($this->defaultBreakpoint) ?? config('filament.default_grid_breakpoint', 'lg');
+    }


The defaultBreakpoint() method and getDefaultBreakpoint() do not validate that the provided breakpoint is one of the valid Tailwind breakpoints ('sm', 'md', 'lg', 'xl', '2xl'). Invalid breakpoints could cause unexpected behavior or silent failures in the grid system. Consider adding validation to ensure only valid breakpoints are accepted.

Suggested change

$this->defaultBreakpoint = $breakpoint;

}

public function getDefaultBreakpoint(): string

{

return $this->evaluate($this->defaultBreakpoint) ?? config('filament.default_grid_breakpoint', 'lg');

}

if (is_string($breakpoint) && ! $this->isValidBreakpoint($breakpoint)) {

// Ignore invalid breakpoint values and fall back to the configured default.

$this->defaultBreakpoint = null;

return;

}

$this->defaultBreakpoint = $breakpoint;

}

public function getDefaultBreakpoint(): string

{

$evaluatedBreakpoint = $this->evaluate($this->defaultBreakpoint);

if (is_string($evaluatedBreakpoint) && $this->isValidBreakpoint($evaluatedBreakpoint)) {

return $evaluatedBreakpoint;

}

$default = config('filament.default_grid_breakpoint', 'lg');

return $this->isValidBreakpoint($default) ? $default : 'lg';

}

protected function isValidBreakpoint(string $breakpoint): bool

{

return in_array($breakpoint, ['sm', 'md', 'lg', 'xl', '2xl'], true);

}

Copilot · 2026-01-20T00:10:22Z

tests/src/Forms/GridTest.php

+test('can configure default grid breakpoint via config', function (): void {
+    config()->set('filament.default_grid_breakpoint', '2xl');
+
+    $schema = Schema::make(Livewire::make())
+        ->columns($columnsAt2xl = rand(1, 12));
+
+    expect($schema)
+        ->getColumns('2xl')->toBe($columnsAt2xl);
+});
+
+test('can configure default grid breakpoint via `FilamentGrid::defaultBreakpoint()` method', function (): void {
+    FilamentGrid::defaultBreakpoint('xl');
+
+    $component = (new Component)
+        ->container(Schema::make(Livewire::make()))
+        ->columnSpan($spanAtXl = rand(1, 12));
+
+    expect($component)
+        ->getColumnSpan('xl')->toBe($spanAtXl);
+});


These tests modify global state (config and GridManager) but don't clean up after themselves. Since GridManager is registered as a scoped service, changes made in one test could potentially affect subsequent tests. Consider adding cleanup logic (e.g., in an afterEach hook or using Pest's defer function) to reset the default breakpoint to 'lg' after each test to prevent test interference.

Copilot · 2026-01-20T00:10:22Z

packages/tables/src/Filters/SelectFilter.php

+    /**
+     * @param  class-string<Select>  $component
+     */
+    public function formComponent(string $component): static
+    {
+        $this->formComponent = $component;
+
+        return $this;
+    }


The formComponent() method doesn't have a PHPDoc annotation to document its parameter type. For consistency with the Filter class (lines 11-13 of Filter.php) and better IDE support, consider adding a PHPDoc comment with the @param class-string<Select> $component annotation above this method.

Copilot · 2026-01-20T00:10:22Z

packages/tables/src/Filters/SelectFilter.php

+    /**
+     * @var class-string<Select>
+     */
+    protected string $formComponent = Select::class;


This PR appears to contain two unrelated features: grid breakpoint configuration (mentioned in the title/description) and the formComponent() functionality for SelectFilter. These should be in separate pull requests to maintain clear version history and easier code review. The formComponent() feature appears to be unrelated to the grid breakpoint configuration that is the stated purpose of this PR.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <[email protected]>

Copilot AI review requested due to automatic review settings January 20, 2026 00:05

github-project-automation bot added this to Roadmap Jan 20, 2026

github-project-automation bot moved this to Todo in Roadmap Jan 20, 2026

Copilot started reviewing on behalf of angus-mcritchie January 20, 2026 00:07 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

angus-mcritchie and others added 4 commits January 20, 2026 11:27

Add GridManager and facade for configurable default grid breakpoint

11a1004

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <[email protected]>

Use configurable grid breakpoint in support package concerns

0c81028

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <[email protected]>

Use configurable grid breakpoint in schemas package

32cce32

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <[email protected]>

Add tests and documentation for configurable grid breakpoint

a6c1d2f

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <[email protected]>

angus-mcritchie force-pushed the configurable-default-grid-breakpoint branch from a1e8584 to a6c1d2f Compare January 20, 2026 00:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Allow configuring default grid breakpoint #19019

Allow configuring default grid breakpoint #19019

Uh oh!

angus-mcritchie commented Jan 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

-        $this->defaultBreakpoint = $breakpoint;
-    }
-    public function getDefaultBreakpoint(): string
-    {
-        return $this->evaluate($this->defaultBreakpoint) ?? config('filament.default_grid_breakpoint', 'lg');
-    }
+        if (is_string($breakpoint) && ! $this->isValidBreakpoint($breakpoint)) {
+            // Ignore invalid breakpoint values and fall back to the configured default.
+            $this->defaultBreakpoint = null;
+            return;
+        }
+        $this->defaultBreakpoint = $breakpoint;
+    }
+    public function getDefaultBreakpoint(): string
+    {
+        $evaluatedBreakpoint = $this->evaluate($this->defaultBreakpoint);
+        if (is_string($evaluatedBreakpoint) && $this->isValidBreakpoint($evaluatedBreakpoint)) {
+            return $evaluatedBreakpoint;
+        }
+        $default = config('filament.default_grid_breakpoint', 'lg');
+        return $this->isValidBreakpoint($default) ? $default : 'lg';
+    }
+    protected function isValidBreakpoint(string $breakpoint): bool
+    {
+        return in_array($breakpoint, ['sm', 'md', 'lg', 'xl', '2xl'], true);
+    }

Uh oh!

Allow configuring default grid breakpoint #19019

Are you sure you want to change the base?

Allow configuring default grid breakpoint #19019

Uh oh!

Conversation

angus-mcritchie commented Jan 20, 2026

Summary

Changes

Why?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant