> ## Documentation Index
> Fetch the complete documentation index at: https://filament-34a8cf01.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> [!WARNING]
>
> You are currently viewing the documentation for Filament 2.x, which is a previous version of Filament.
>
> Looking for the current stable version? Visit the [5.x documentation](https://filament-34a8cf01.mintlify.site/5.x).

Filament allows you to build dynamic dashboards, comprised of "widget" cards, very easily.

Widgets are pure [Livewire](https://laravel-livewire.com) components, so may use any features of that package.

Widgets may also be used on [resource pages](https://filament-34a8cf01.mintlify.site/2.x/admin/resources/widgets.md) or other [custom pages](https://filament-34a8cf01.mintlify.site/2.x/admin/pages/widgets.md).

## Available widgets

Filament ships with a few pre-built widgets, as well as the ability to create [custom widgets](#custom-widgets):

* [Stats](https://filament-34a8cf01.mintlify.site/2.x/admin/dashboard/stats.md) widgets display any data, often numeric data, within cards in a row.
* [Chart](https://filament-34a8cf01.mintlify.site/2.x/admin/dashboard/charts.md) widgets display numeric data in a visual chart.
* [Table](https://filament-34a8cf01.mintlify.site/2.x/admin/dashboard/tables.md) widgets render data in a table, which supports sorting, searching, filtering, actions, and everything else included within the [table builder](../../tables).

You may also [create your own custom widgets](#custom-widgets).

## Sorting widgets

Each widget class contains a `$sort` property that may be used to change its order on the page, relative to other widgets:

```php theme={"theme":"gruvbox-dark-hard"}
protected static ?int $sort = 2;
```

## Customizing widget width

You may customize the width of a widget using the `$columnSpan` property. You may use a number between 1 and 12 to indicate how many columns the widget should span, or `full` to make it occupy the full width of the page:

```php theme={"theme":"gruvbox-dark-hard"}
protected int | string | array $columnSpan = 'full';
```

### Responsive widget widths

You may wish to change the widget width based on the responsive [breakpoint](https://tailwindcss.com/docs/responsive-design#overview) of the browser. You can do this using an array that contains the number of columns that the widget should occupy at each breakpoint:

```php theme={"theme":"gruvbox-dark-hard"}
protected int | string | array $columnSpan = [
    'md' => 2,
    'xl' => 3,
];
```

This is especially useful when using a [responsive widgets grid](#responsive-widgets-grid).

## Customizing the widgets grid

You may change how many grid columns are used to display widgets.

Firstly, you must [replace the original Dashboard page](#customizing-the-dashboard-page).

Now, in your new `app/Filament/Pages/Dashboard.php` file, you may override the `getColumns()` method to return a number of grid columns to use:

```php theme={"theme":"gruvbox-dark-hard"}
protected function getColumns(): int | array
{
    return 3;
}
```

### Responsive widgets grid

You may wish to change the number of widget grid columns based on the responsive [breakpoint](https://tailwindcss.com/docs/responsive-design#overview) of the browser. You can do this using an array that contains the number of columns that should be used at each breakpoint:

```php theme={"theme":"gruvbox-dark-hard"}
protected function getColumns(): int | array
{
    return [
        'md' => 4,
        'xl' => 5,
    ];
}
```

This pairs well with [responsive widget widths](#responsive-widget-widths).

## Conditionally hiding widgets

You may override the static `canView()` method on widgets to conditionally hide them:

```php theme={"theme":"gruvbox-dark-hard"}
public static function canView(): bool
{
    return auth()->user()->isAdmin();
}
```

## Disabling the default widgets

By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets.register` property of the [configuration](https://filament-34a8cf01.mintlify.site/2.x/admin/installation.md#publishing-configuration) file:

```php theme={"theme":"gruvbox-dark-hard"}
'widgets' => [
    // ...
    'register' => [],
],
```

## Custom widgets

To get started building a `BlogPostsOverview` widget:

```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-widget BlogPostsOverview
```

This command will create two files - a widget class in the `/Widgets` directory of the Filament directory, and a view in the `/widgets` directory of the Filament views directory.

## Customizing the dashboard page

If you want to customize the dashboard class, for example to [change the number of widget columns](#customizing-widget-width), create a new file at `app/Filament/Pages/Dashboard.php`:

```php theme={"theme":"gruvbox-dark-hard"}
<?php

namespace App\Filament\Pages;

use Filament\Pages\Dashboard as BasePage;

class Dashboard extends BasePage
{
    // ...
}
```

Finally, remove the original `Dashboard` class from the [configuration file](https://filament-34a8cf01.mintlify.site/2.x/admin/installation.md#publishing-configuration):

```php theme={"theme":"gruvbox-dark-hard"}
'pages' => [
    // ...
    'register' => [],
],
```

[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/2.x/packages/admin/docs/04-dashboard/01-getting-started.md)

## Sponsored by

[Your logo here](https://github.com/sponsors/danharrin)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.