Stats overview widgets

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:

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

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.

Adding a description and icon to a stat

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

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:

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)

Changing the color of the stat

You may also give stats a color:

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'),
    ];
}

Adding extra HTML attributes to a stat

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

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:

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:

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:

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'),
        // ...
    ];
}

Styling stat charts in a theme

To style stat charts from a custom theme, set these CSS custom properties on .fi-wi-stats-overview-stat or a parent element:

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

.fi-wi-stats-overview-stat {
    & .fi-wi-stats-overview-stat-chart-border-color {
        @apply text-gray-400 dark:text-gray-500;
    }
}

These properties only affect the charts inside stats. Chart widgets 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:

protected ?string $pollingInterval = '10s';

Alternatively, you may disable polling altogether:

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:

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:

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:

protected function getHeading(): ?string
{
    return 'Analytics';
}

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

Introduction

Guides

Resources

Tables

Schemas

Forms

Infolists

Actions

Notifications

Widgets

Configuration

Navigation

Users

Styling

Advanced

Testing

Plugins

Components

Deployment

Upgrading

Stats overview widgets

Introduction

Adding a description and icon to a stat

Changing the color of the stat

Adding extra HTML attributes to a stat

Setting a placeholder for a stat

Setting a default placeholder globally

Adding a chart to a stat

Styling stat charts in a theme

Live updating stats (polling)

Disabling lazy loading

Adding a heading and description

​Introduction

​Adding a description and icon to a stat

​Changing the color of the stat

​Adding extra HTML attributes to a stat

​Setting a placeholder for a stat

​Setting a default placeholder globally

​Adding a chart to a stat

​Styling stat charts in a theme

​Live updating stats (polling)

​Disabling lazy loading

​Adding a heading and description

Introduction

Adding a description and icon to a stat

Changing the color of the stat

Adding extra HTML attributes to a stat

Setting a placeholder for a stat

Setting a default placeholder globally

Adding a chart to a stat

Styling stat charts in a theme

Live updating stats (polling)

Disabling lazy loading

Adding a heading and description