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

# Stats overview widgets

> [!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/widgets/stats-overview.md).

## Introduction

Filament comes with a "stats overview" widget template, which you can use to display a number of different stats in a single widget, without needing to write a custom view.

Start by creating a widget with the command:

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

This command will create a new `StatsOverview.php` file. Open it, and return `Stat` instances from the `getStats()` method:

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

namespace App\Filament\Widgets;

use Filament\Widgets\StatsOverviewWidget as BaseWidget;
use Filament\Widgets\StatsOverviewWidget\Stat;

class StatsOverview extends BaseWidget
{
    protected function getStats(): array
    {
        return [
            Stat::make('Unique views', '192.1k'),
            Stat::make('Bounce rate', '21%'),
            Stat::make('Average time on page', '3:12'),
        ];
    }
}
```

Now, check out your widget in the dashboard.

Loading preview

![Stats overview](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/widgets/stats-overview/simple.jpg)

## Adding a description and icon to a stat

You may add a `description()` to provide additional information, along with a `descriptionIcon()`:

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

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up'),
        Stat::make('Bounce rate', '21%')
            ->description('7% decrease')
            ->descriptionIcon('heroicon-m-arrow-trending-down'),
        Stat::make('Average time on page', '3:12')
            ->description('3% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up'),
    ];
}
```

The `descriptionIcon()` method also accepts a second parameter to put the icon before the description instead of after it:

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

Stat::make('Unique views', '192.1k')
    ->description('32k increase')
    ->descriptionIcon('heroicon-m-arrow-trending-up', IconPosition::Before)
```

Loading preview

![Stats overview with descriptions](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/widgets/stats-overview/description.jpg)

## Changing the color of the stat

You may also give stats a [color](https://filament-34a8cf01.mintlify.site/4.x/styling/colors.md):

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

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->color('success'),
        Stat::make('Bounce rate', '21%')
            ->description('7% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-down')
            ->color('danger'),
        Stat::make('Average time on page', '3:12')
            ->description('3% increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->color('success'),
    ];
}
```

Loading preview

![Stats overview with colors](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/widgets/stats-overview/color.jpg)

## Adding extra HTML attributes to a stat

You may also pass extra HTML attributes to stats using `extraAttributes()`:

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

protected function getStats(): array
{
    return [
        Stat::make('Processed', '192.1k')
            ->color('success')
            ->extraAttributes([
                'class' => 'cursor-pointer',
                'wire:click' => "\$dispatch('setStatusFilter', { filter: 'processed' })",
            ]),
        // ...
    ];
}
```

In this example, we are deliberately escaping the `$` in `$dispatch()` since this needs to be passed directly to the HTML, it is not a PHP variable.

## Setting a placeholder for a stat

Sometimes a stat's value may not be available — for example, when a dashboard has nothing to show for a specific period. You can use `placeholder()` to define what should be displayed instead when the value is blank:

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

Stat::make('Unique views', $uniqueViews)
    ->placeholder('-')
```

A value is considered blank according to Laravel's `blank()` helper. For example, `null` and empty strings are blank, while `0` and `'0'` are not.

### Setting a default placeholder globally

If you'd like every stat in your app to fall back to the same placeholder by default, you can use the static `configureUsing()` method in a service provider's `boot()` method:

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

Stat::configureUsing(function (Stat $component): void {
    $component->placeholder('-');
});
```

Individual stats can still override this by calling `placeholder()` themselves.

## Adding a chart to a stat

You may also add or chain a `chart()` to each stat to provide historical data. The `chart()` method accepts an array of data points to plot:

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

protected function getStats(): array
{
    return [
        Stat::make('Unique views', '192.1k')
            ->description('32k increase')
            ->descriptionIcon('heroicon-m-arrow-trending-up')
            ->chart([7, 2, 10, 3, 15, 4, 17])
            ->color('success'),
        // ...
    ];
}
```

Loading preview

![Stats overview with charts](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/widgets/stats-overview/chart.jpg)

## Styling stat charts in a theme

To style stat charts from a [custom theme](https://filament-34a8cf01.mintlify.site/4.x/styling/overview.md), set these CSS custom properties on `.fi-wi-stats-overview-stat` or a parent element:

```css theme={"theme":"gruvbox-dark-hard"}
.fi-wi-stats-overview-stat {
    --stat-chart-border-width: 1;
    --stat-chart-line-tension: 0;
    --stat-chart-fill: none;
}
```

* `--stat-chart-border-width`: The line thickness.
* `--stat-chart-line-tension`: The curvature, from `0` for straight segments to `1`.
* `--stat-chart-fill`: The fill target: `start`, `end`, `origin`, or `stack`. Use `none` to disable the fill.

Use unitless numbers and the supported keywords, not CSS lengths. You may set different values for light and dark mode.

The chart takes its colors from the [color of the stat](#changing-the-color-of-the-stat). To change them in a theme, style the `.fi-wi-stats-overview-stat-chart-bg-color` and `.fi-wi-stats-overview-stat-chart-border-color` elements with an ordinary `color` declaration:

```css theme={"theme":"gruvbox-dark-hard"}
.fi-wi-stats-overview-stat {
    & .fi-wi-stats-overview-stat-chart-border-color {
        @apply text-gray-400 dark:text-gray-500;
    }
}
```

> [!NOTE]
>
> These properties only affect the charts inside stats. [Chart widgets](https://filament-34a8cf01.mintlify.site/4.x/widgets/charts.md#styling-charts-in-a-theme) are styled with their own set, prefixed `--chart-`.

## Live updating stats (polling)

By default, stats overview widgets refresh their data every 5 seconds.

To customize this, you may override the `$pollingInterval` property on the class to a new interval:

```php theme={"theme":"gruvbox-dark-hard"}
protected ?string $pollingInterval = '10s';
```

Alternatively, you may disable polling altogether:

```php theme={"theme":"gruvbox-dark-hard"}
protected ?string $pollingInterval = null;
```

## Disabling lazy loading

By default, widgets are lazy-loaded. This means that they will only be loaded when they are visible on the page.

To disable this behavior, you may override the `$isLazy` property on the widget class:

```php theme={"theme":"gruvbox-dark-hard"}
protected static bool $isLazy = false;
```

## Adding a heading and description

You may also add heading and description text above the widget by overriding the `$heading` and `$description` properties:

```php theme={"theme":"gruvbox-dark-hard"}
protected ?string $heading = 'Analytics';

protected ?string $description = 'An overview of some analytics.';
```

If you need to dynamically generate the heading or description text, you can instead override the `getHeading()` and `getDescription()` methods:

```php theme={"theme":"gruvbox-dark-hard"}
protected function getHeading(): ?string
{
    return 'Analytics';
}

protected function getDescription(): ?string
{
    return 'An overview of some analytics.';
}
```

Loading preview

![Stats overview with heading and description](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/widgets/stats-overview/heading.jpg)

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