> ## 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.

# Using widgets on resource pages

> [!WARNING]
>
> You are currently viewing the documentation for Filament 4.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/resources/widgets.md).

## Introduction

Filament allows you to display widgets inside pages, below the header and above the footer.

Loading preview

![A resource page with header widgets](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/panels/resources/widgets.jpg)

You can use an existing [dashboard widget](../widgets), or create one specifically for the resource.

## Creating a resource widget

To get started building a resource widget:

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

This command will create two files - a widget class in the `app/Filament/Resources/Customers/Widgets` directory, and a view in the `resources/views/filament/resources/customers/widgets` directory.

You must register the new widget in your resource's `getWidgets()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use App\Filament\Resources\Customers\Widgets\CustomerOverview;

public static function getWidgets(): array
{
    return [
        CustomerOverview::class,
    ];
}
```

If you'd like to learn how to build and customize widgets, check out the [Dashboard](../widgets) documentation section.

## Displaying a widget on a resource page

To display a widget on a resource page, use the `getHeaderWidgets()` or `getFooterWidgets()` methods for that page:

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

namespace App\Filament\Resources\Customers\Pages;

use App\Filament\Resources\Customers\CustomerResource;
use App\Filament\Resources\Customers\Widgets\CustomerOverview;
use Filament\Resources\Pages\ListRecords;

class ListCustomers extends ListRecords
{
    protected static string $resource = CustomerResource::class;

    protected function getHeaderWidgets(): array
    {
        return [
            CustomerOverview::class,
        ];
    }
}
```

`getHeaderWidgets()` returns an array of widgets to display above the page content, whereas `getFooterWidgets()` are displayed below.

If you'd like to customize the number of grid columns used to arrange widgets, check out the [Pages documentation](https://filament-34a8cf01.mintlify.site/4.x/navigation/custom-pages.md#customizing-the-widgets-grid).

## Accessing the current record in the widget

If you're using a widget on an [Edit](https://filament-34a8cf01.mintlify.site/4.x/resources/editing-records.md) or [View](https://filament-34a8cf01.mintlify.site/4.x/resources/viewing-records.md) page, you may access the current record by defining a `$record` property on the widget class:

```php theme={"theme":"gruvbox-dark-hard"}
use Illuminate\Database\Eloquent\Model;

public ?Model $record = null;
```

> [!WARNING]
>
> Filament leaves widget model properties, including `$record` and `$parentRecord`, to Livewire's native restoration. It does not reapply global scopes, the resource query, or a policy for those records. A request to the widget does not reauthorize the parent page. The widget's `canView()` method controls access to the widget, not its records. Query and authorize records before using them, including any tenant or ownership restrictions. See [Eloquent model restoration in Livewire](https://filament-34a8cf01.mintlify.site/4.x/advanced/security.md#understanding-eloquent-model-restoration-in-livewire) for more information.

## Accessing page table data in the widget

If you're using a widget on a [List](https://filament-34a8cf01.mintlify.site/4.x/resources/listing-records.md) page, you may access the table data by first adding the `ExposesTableToWidgets` trait to the page class:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Pages\Concerns\ExposesTableToWidgets;
use Filament\Resources\Pages\ListRecords;

class ListProducts extends ListRecords
{
    use ExposesTableToWidgets;

    // ...
}
```

Now, on the widget class, you must add the `InteractsWithPageTable` trait, and return the name of the page class from the `getTablePage()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use App\Filament\Resources\Products\Pages\ListProducts;
use Filament\Widgets\Concerns\InteractsWithPageTable;
use Filament\Widgets\Widget;

class ProductStats extends Widget
{
    use InteractsWithPageTable;

    protected function getTablePage(): string
    {
        return ListProducts::class;
    }

    // ...
}
```

In the widget class, you can now access the Eloquent query builder instance for the table data using the `$this->getPageTableQuery()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Total Products', $this->getPageTableQuery()->count()),
```

Alternatively, you can access a collection of the records on the current page using the `$this->getPageTableRecords()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Total Products', $this->getPageTableRecords()->count()),
```

> [!WARNING]
>
> `InteractsWithPageTable` uses the page's table query, not each record's `view()` policy. Add query restrictions for records that must not be included in the widget's data. For nested resources, parent binding and ancestor resource access checks do not replace parent-record policy checks. This trait also does not protect other uses of model properties on your widget. See [Eloquent model restoration in Livewire](https://filament-34a8cf01.mintlify.site/4.x/advanced/security.md#understanding-eloquent-model-restoration-in-livewire) for the binding rules and your authorization responsibilities.

### Accessing the total table records count

If you need the total count of all records for the table query without executing an additional count query, you can use the `$tableRecordsCount` property:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Widgets\StatsOverviewWidget\Stat;

Stat::make('Total Products', $this->tableRecordsCount),
```

## Passing properties to widgets on resource pages

When registering a widget on a resource page, you can use the `make()` method to pass an array of [Livewire properties](https://livewire.laravel.com/docs/properties) to it:

```php theme={"theme":"gruvbox-dark-hard"}
use App\Filament\Resources\Customers\Widgets\CustomerOverview;

protected function getHeaderWidgets(): array
{
    return [
        CustomerOverview::make([
            'status' => 'active',
        ]),
    ];
}
```

This array of properties gets mapped to [public Livewire properties](https://livewire.laravel.com/docs/properties) on the widget class:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Widgets\Widget;

class CustomerOverview extends Widget
{
    public string $status;

    // ...
}
```

Now, you can access the `status` in the widget class using `$this->status`.

[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/docs/03-resources/11-widgets.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.