Skip to content

Dashboard

Overview of the admin dashboard components, caching, access requirements, and customization options.

The dashboard is the first screen after login. It shows store health at a glance: revenue trends, key metrics, recent orders and top products. Until the store is configured, an onboarding guide takes the place of these widgets.

Shopper admin dashboard with stat cards, revenue chart, top products, and recent orders

Components

The dashboard is composed of five Livewire components, each with a focused responsibility. The four data widgets cache their data independently (see Caching).

The revenue chart, the top selling products and the recent orders require the browse_orders permission: the dashboard does not render them for a user without it.

RevenueChart

Displays monthly revenue as a bar chart for the last 12 months, the current month included. Each bar is the sum of price_amount on paid orders in the selected currency, converted from cents for display (zero-decimal currencies such as XAF or JPY are shown as stored). Data is grouped by month in a single aggregated query and cached with flexible TTL (fresh for 5 minutes, stale up to 30 minutes). The component extends ApexChartWidget from the leandrocfe/filament-apex-charts package.

The chart supports a currency filter. It starts on the store default currency, and a dropdown lists the currencies enabled in your store settings to switch between them. The Y-axis and tooltip are formatted using Intl.NumberFormat with the application locale, followed by the currency symbol.

The revenue query supports MySQL, PostgreSQL, and SQLite with database-specific date expressions.

StatCards

Shows four summary cards comparing the current month to the previous month:

CardMetricScope
RevenueSum of price_amount on paid orders created this monthStore default currency
ProductsTotal product count, monthly new products for trendAll types
OrdersTotal count of paid orders, monthly count for trendAll currencies
CustomersTotal count of users with the customer role (the customers scope, role name from config('shopper.admin.roles.user'), user by default), monthly new customers for trendAll

Each card shows the percentage change versus the previous month, with a green or red trend indicator (gray at 0% when nothing changed, 100% when the previous month had nothing). Cards link to their respective admin sections.

A card is shown only to users who can browse its section: browse_orders for Revenue and Orders, browse_products for Products, browse_customers for Customers.

RecentOrders

A table of the 7 most recent orders, whatever their payment status, excluding orders with Cancelled or Archived status. Each row shows the order number, first product with thumbnail (plus the count of other items), total amount, order status badge, and links to the order detail page.

TopSellingProducts

Ranks the top 6 products by total quantity sold across all paid orders, with no date range. Variant sales are aggregated back to the parent product. Each row shows the product thumbnail, name, total units sold, and the average rating and count of its approved reviews.

SetupGuide

An interactive checklist that guides new stores through the essential configuration steps. It takes the place of the dashboard widgets until it is completed or dismissed, and detects each step's completion by querying the database. A step is listed only for users who have its permission:

Shopper setup guide with progress bar and expandable steps
StepCompleted whenPermission
Add your first productAt least one product existsadd_products
Create a collectionAt least one collection existsadd_collections
Set up shipping zonesAt least one enabled shipping zone existsaccess_setting
Set up payment methodsAt least one enabled payment method existsaccess_setting
Configure taxesAt least one tax zone existsaccess_setting

When all steps are complete, the guide saves a setup_guide_done setting and dispatches a setup-guide-completed event to hide itself. This check runs when the dashboard loads, for a user with the access_setting permission. The guide does not reappear on subsequent visits. A user with access_setting can also dismiss it early with the dismiss button.

Caching

The four data widgets cache their data independently with Laravel's Cache::flexible(). During the fresh TTL the cached value is served as is. Between the fresh and the stale TTL, the cached value is still served and Laravel recomputes it after the response is sent. Past the stale TTL, the next request recomputes it. The setup guide is not cached. The cache keys and TTLs are:

ComponentCache keyFresh TTLStale TTL
RevenueChartdashboard:revenue:{currency}5 min30 min
StatCardsdashboard:stat-cards:{locale}5 min30 min
RecentOrdersdashboard.orders:recent-ids1 min5 min
TopSellingProductsdashboard.products:top-selling5 min30 min

RecentOrders caches only the order IDs: the orders themselves are loaded fresh on each render.

To clear the dashboard cache manually (for example after a data import), flush the keys:

use Illuminate\Support\Facades\Cache;

Cache::forget('dashboard:revenue:'.shopper_currency());
Cache::forget('dashboard:stat-cards:'.app()->getLocale());
Cache::forget('dashboard.orders:recent-ids');
Cache::forget('dashboard.products:top-selling');

The revenue chart keeps one entry per currency shown in its filter, and the stat cards one entry per admin locale: forget the key of each currency and locale your team uses.

Access Requirements

The dashboard middleware (Shopper\Http\Middleware\Dashboard) checks two conditions before rendering the page. The user must have the administrator or manager role (role names from config('shopper.admin.roles.admin') and config('shopper.admin.roles.manager')), or the access_dashboard permission. The store must have the email and street_address settings configured (these are set during the initial store setup).

The middleware runs on every authenticated page of the admin panel, not only the dashboard: your custom routes (config('shopper.routes.custom_file')) and add-on routes included. Only the initialization and forbidden pages skip it. If the user lacks permission, Shopper redirects to its forbidden page. If the settings are missing, it redirects to the store initialization page.

Customizing the Dashboard

Replacing the Entire Page

The dashboard page is registered in the components configuration. Publish the dashboard component config to swap it with your own implementation:

php artisan shopper:component:publish dashboard

This creates config/shopper/components/dashboard.php:

use Shopper\Livewire\Components;
use Shopper\Livewire\Pages;

return [
    'pages' => [
        'dashboard' => Pages\Dashboard::class,
    ],
    'components' => [
        'locale-switcher' => Components\LocaleSwitcher::class,
    ],
];

Replace the page class with your own component:

'pages' => [
    'dashboard' => App\Livewire\Pages\Dashboard::class,
],

Your component only needs to render a view with the app layout. The simplest override:

namespace App\Livewire\Pages;

use Illuminate\Contracts\View\View;
use Livewire\Component;

final class Dashboard extends Component
{
    public function render(): View
    {
        return view('dashboard.index')
            ->layout('shopper::components.layouts.app', [
                'title' => 'Dashboard',
            ]);
    }
}

You can also extend Shopper\Livewire\Pages\AbstractPageComponent, which already sets this layout, and only pass the title with ->title().

Overriding Individual Components

To replace a single widget (for example, swap the revenue chart for a custom report), map its Livewire alias to your own component in the components key of config/shopper/components/dashboard.php. Shopper registers the entries of this file after its built-in widgets, so your class wins:

'components' => [
    'locale-switcher' => Components\LocaleSwitcher::class,
    'dashboard.revenue-chart' => App\Livewire\Dashboard\SalesReport::class,
],

The widget aliases are setup-guide, dashboard.stat-cards, dashboard.revenue-chart, dashboard.top-selling-products and dashboard.recent-orders.

To change the layout or remove a widget, override the dashboard Blade view.

Shopper has no publish tag for its views. Copy vendor/shopper/framework/resources/views/livewire/pages/dashboard.blade.php to resources/views/vendor/shopper/livewire/pages/dashboard.blade.php: Laravel loads your copy instead of the package view. The view shows the setup guide until it is completed or dismissed, then renders each widget with a Livewire tag that you can replace (simplified below: the file also holds the grid markup and the two dashboard render hooks):

@if ($this->showSetupGuide)
    <livewire:shopper-setup-guide />
@else
    <livewire:shopper-dashboard.stat-cards />
    @can('browse_orders')
        <livewire:shopper-dashboard.revenue-chart />
        <livewire:shopper-dashboard.top-selling-products />
        <livewire:shopper-dashboard.recent-orders />
    @endcan
@endif

Replace any tag with your own Livewire component or plain Blade content. The copy no longer follows updates of the package view, so compare it with the original after each Shopper upgrade.

Adding Content via Render Hooks

If you only want to inject content above or below the dashboard without replacing the page or publishing views, use the layout render hooks:

use Shopper\Facades\Shopper;
use Shopper\View\LayoutRenderHook;

Shopper::renderHook(
    LayoutRenderHook::DASHBOARD_START,
    fn (): string => view('dashboard.store-alert-banner')->render(),
);

Shopper::renderHook(
    LayoutRenderHook::DASHBOARD_END,
    fn (): string => view('dashboard.custom-reports')->render(),
);

Register these hooks in a service provider's boot method. See the Render Hooks documentation for the full list of available injection points.

Last updated on

Edit on GitHub