# Dashboards and widgets

A widget is a card computed on the server for a date range. Widgets sit
on dashboards, or above a resource's list.

```php
final class RevenueStat extends VectorWidget
{
    public function __construct(private readonly SqlLink $db) {}

    public function type(): string { return self::STAT; }
    public function cacheSeconds(): int { return 60; }

    public function calculate(WidgetRequest $request): WidgetResult
    {
        // one query for $request->from .. $request->to
        return WidgetResult::stat($current, $previous, 'money:EUR');
    }
}
```

## Widget types

| Type | Shows |
|---|---|
| `stat` | One figure, compared with the previous period. |
| `trend` | A series over time. |
| `partition` | A breakdown into slices, such as orders by status. |
| `progress` | A figure against a target. |
| `table` | A few rows, optionally linking to the full list. |

A value's format is a number, `money:EUR`, `percent` or `duration`.

## Shaping a widget

| Method | Effect |
|---|---|
| `ranges()` | The ranges offered, as key => label, the first the default; `7d`, `30d`, `90d` and `1y` by default, and an empty array for none. |
| `width()` | 3, 4, 6 or 12 columns of the grid. |
| `name()`, `label()`, `icon()` | The URL segment (by default the class name without `Widget`, in kebab-case: `RevenueWidget` is `revenue`) and how it is shown. |
| `canView()` | Who sees it, on top of the dashboard's or resource's own visibility. |
| `cacheSeconds()` | Above zero, memoizes the result in a bounded per-worker cache, keyed by widget, range and the account it was computed for. |
| `cacheShared()` | Shares one cached result between all admins, for figures that are the same for everyone. |

## Dashboards

```php
#[Dashboard]
final class MainDashboard extends VectorDashboard
{
    public function widgets(): array { return [RevenueStat::class, OrdersTrend::class]; }
}
```

A dashboard's name is its class name without `Dashboard`, in kebab-case
(`MainDashboard` is `main`), unless `name()` says otherwise. The
dashboard named `main` — or, without one, the first — is the admin's
home page; the others appear in the navigation drawer under their own
labels. `canView()` hides a whole dashboard from a user.

## Resource widgets

A resource's `widgets()` appear above its list. A widget runs its own
query: when the resource's `scope()` narrows what a user may see, narrow
the widget's query the same way, and leave `cacheShared()` false so one
admin is never shown another's figures.

## See also

- {doc}`resources` — badges, the other at-a-glance count.
- {doc}`customizing-the-ui` — a renderer of your own for a widget type.