Above a list

Resource::listWidgets() returns widgets for the top of the list page. Users see the widgets they may view.

use Anvil\Data\Model;
use Anvil\Widget\StatWidget;

public function listWidgets(): array
{
    return [
        // All records the user may see.
        StatWidget::make('Running projects')->icon('play-circle')->span(4)
            ->value(fn (): int => $this->query()->where('status', 'running')->countAllResults()),
        // Only the records of the current search and filters.
        StatWidget::make('Listed projects')->icon('funnel')->span(4)
            ->fromList(static fn (Model $records): int => $records->countAllResults()),
    ];
}

• value() is computed once, when the list page is opened. Query through $this->query() so the tenant and scopeQuery() apply.
• fromList() receives a fresh query of the list: tenant, scopeQuery(), search and filters applied, no sorting or paging. Whenever the list changes (search, filter, page, delete), the answer of the list contains the widgets again as an htmx out-of-band swap (hx-swap-oob) of the grid #list-widgets-<resource slug>, so the figures stay in sync.
• Only answers with at least one widget that follows the list update the grid; then all widgets of the grid are rendered again.
• Related lists on detail pages show no widgets.
• ChartWidget and TableWidget can be used above a list, too, but do not follow it.

Above a list the widgets are shown in their order and widths; users do not arrange them. See also Widgets above the list in the tables chapter.