Charts

Getting started

Filament comes with many "chart" widget template, which you can use to display real-time, interactive charts.

Start by creating a widget with the command:

php artisan make:filament-widget BlogPostsChart --chart

There are several chart classes available, but we'll use the LineChartWidget class for this example.

The getHeading() method is used to return a heading that describes the chart.

The getData() method is used to return an array of datasets and labels. Each dataset is a labelled array of points to plot on the chart, and each label is a string. This structure is identical with the Chart.js library, which Filament uses to render charts. You may use the Chart.js documentation to fully understand the possibilities to return from getData(), based on the chart type.

<?php

namespace App\Filament\Widgets;

use Filament\Widgets\LineChartWidget;

class BlogPostsChart extends LineChartWidget
{
    protected function getHeading(): string
    {
        return 'Blog posts';
    }

    protected function getData(): array
    {
        return [
            'datasets' => [
                [
                    'label' => 'Blog posts created',
                    'data' => [0, 10, 5, 2, 21, 32, 45, 74, 65, 45, 77, 89],
                ],
            ],
            'labels' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        ];
    }
}

Now, check out your widget in the dashboard.

Available chart types

Below is a list of available chart widget classes which you may extend, and their corresponding Chart.js documentation page, for inspiration what to return from getData():

• Filament\Widgets\BarChartWidget - Chart.js documentation
• Filament\Widgets\BubbleChartWidget - Chart.js documentation
• Filament\Widgets\DoughnutChartWidget - Chart.js documentation
• Filament\Widgets\LineChartWidget - Chart.js documentation
• Filament\Widgets\PieChartWidget - Chart.js documentation
• Filament\Widgets\PolarAreaChartWidget - Chart.js documentation
• Filament\Widgets\RadarChartWidget - Chart.js documentation
• Filament\Widgets\ScatterChartWidget - Chart.js documentation

Generating chart data from an Eloquent model

To generate chart data from an Eloquent model, Filament recommends that you install the flowframe/laravel-trend package. You can view the documentation on the Flowframe website.

Here is an example of generating chart data from a model using the laravel-trend package:

use Flowframe\Trend\Trend;
use Flowframe\Trend\TrendValue;

protected function getData(): array
{
    $data = Trend::model(BlogPost::class)
        ->between(
            start: now()->startOfYear(),
            end: now()->endOfYear(),
        )
        ->perMonth()
        ->count();

    return [
        'datasets' => [
            [
                'label' => 'Blog posts',
                'data' => $data->map(fn (TrendValue $value) => $value->aggregate),
            ],
        ],
        'labels' => $data->map(fn (TrendValue $value) => $value->date),
    ];
}

Filtering chart data

You can set up chart filters to change the data shown on chart. Commonly, this is used to change the time period that chart data is rendered for.

To set a default filter value, set the $filter property:

public ?string $filter = 'today';

Then, define the getFilters() method to return an array of values and labels for your filter:

protected function getFilters(): ?array
{
    return [
        'today' => 'Today',
        'week' => 'Last week',
        'month' => 'Last month',
        'year' => 'This year',
    ];
}

You can use the active filter value within your getData() method:

protected function getData(): array
{
    $activeFilter = $this->filter;
    
    // ...
}

Live updating (polling)

By default, chart widgets refresh their data every 5 seconds.

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

protected static ?string $pollingInterval = '10s';

Alternatively, you may disable polling altogether:

protected static ?string $pollingInterval = null;

Setting a maximum chart height

You may place a maximum height on the chart to ensure that it doesn't get too big, using the $maxHeight property:

protected static ?string $maxHeight = '300px';

Setting chart configuration options

You may specify an $options variable on the chart class to control the many configuration options that the Chart.js library provides. For instance, you could turn off the legend for LineChartWidget class:

protected static ?array $options = [
    'plugins' => [
        'legend' => [
            'display' => false,
        ],
    ],
];