laravel-dashboard-development

Laravel Dashboard Development

spatie/laravel-dashboard is a package for building real-time dashboards displayed on wall-mounted screens. It uses Livewire 4, Tailwind CSS 4 (via browser CDN), and CSS Grid for layout.

Creating a Custom Tile

1. Livewire Component

Create a Livewire component extending BaseTileComponent:

namespace App\Livewire;

use Livewire\Component;
use Spatie\Dashboard\Components\BaseTileComponent;
use Spatie\Dashboard\Models\Tile;

class WeatherTile extends BaseTileComponent
{
    public function render()
    {
        return view('livewire.weather-tile', [
            'weather' => Tile::firstOrCreateForName('weather')->getData('current'),
        ]);
    }
}

Key points:

• $position is inherited from BaseTileComponent — do not add it or override mount()
• #[Defer] is inherited — skeleton loading works automatically via placeholder()
• No mount() method needed unless you have additional initialization

2. Blade View

Wrap your tile content in the <x-dashboard-tile> component, always passing :position:

<x-dashboard-tile :position="$position">
    <h1 class="text-2xl font-bold text-default">Weather</h1>
    <p class="text-dimmed">{{ $weather['temperature'] ?? '--' }}°C</p>
</x-dashboard-tile>

3. Register the Component

Register with Livewire in a service provider:

use Livewire\Livewire;

Livewire::component('weather-tile', \App\Livewire\WeatherTile::class);

Storing & Retrieving Data

Use the Tile model to persist data between requests:

use Spatie\Dashboard\Models\Tile;

// Store data
Tile::firstOrCreateForName('weather')->putData('current', [
    'temperature' => 22,
    'description' => 'Sunny',
]);

// Retrieve data
$data = Tile::firstOrCreateForName('weather')->getData('current');

Fetching External Data

Create an Artisan command to fetch data from APIs:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Spatie\Dashboard\Models\Tile;

class FetchWeatherCommand extends Command
{
    protected $signature = 'dashboard:fetch-weather';

    protected $description = 'Fetch weather data for the dashboard';

    public function handle(): void
    {
        $weather = Http::get('https://api.example.com/weather')->json();

        Tile::firstOrCreateForName('weather')->putData('current', $weather);

        $this->comment('Weather data fetched.');
    }
}

Schedule it in your application's console kernel or routes/console.php:

Schedule::command('dashboard:fetch-weather')->everyFiveMinutes();

Dashboard Setup

Route

Route::get('/dashboard', function () {
    return view('dashboard');
});

Dashboard View

<x-dashboard>
    <livewire:weather-tile position="a1" />
    <livewire:calendar-tile position="b1:b2" />
    <livewire:stats-tile position="a2" />
</x-dashboard>

The <x-dashboard> component provides the full HTML page with Tailwind CSS 4 and theming.

Grid Positioning

Tiles use Excel-like notation where columns = letters and rows = numbers:

• a1 — column A, row 1 (single cell)
• a1:b2 — spans from column A row 1 to column B row 2 (2x2 area)
• a1:c1 — spans columns A through C in row 1

The grid auto-sizes based on the positions you use.

Tile Props

The <x-dashboard-tile> component accepts these props:

Theming

Color Utilities

The dashboard provides Tailwind color utilities that adapt to light/dark mode:

These work with any Tailwind utility (text-*, bg-*, border-*, etc.).

Theme Configuration

In config/dashboard.php:

return [
    'theme' => 'light', // light, dark, device, auto
    'auto_theme_location' => [
        'lat' => 51.260197,
        'lng' => 4.402771,
    ],
];

• light / dark — fixed mode
• device — follows OS preference
• auto — light when sun is up, dark when sun is down (uses lat/lng)

Custom Assets

Register additional scripts or stylesheets via the Dashboard service:

use Spatie\Dashboard\Dashboard;

app(Dashboard::class)->script('https://cdn.example.com/chart.js');
app(Dashboard::class)->stylesheet('https://cdn.example.com/extra.css');
app(Dashboard::class)->inlineScript('console.log("loaded")');
app(Dashboard::class)->inlineStylesheet('.custom { color: red; }');

Grid Template Utilities

The dashboard includes Tailwind theme utilities for grid layouts inside tiles:

• grid-cols-1-1, grid-cols-1-auto, grid-cols-auto-1, grid-cols-auto-auto, etc.
• grid-rows-1-1, grid-rows-1-auto, grid-rows-auto-1, grid-rows-auto-auto, etc.

Do / Don't

• Do extend BaseTileComponent, not Livewire\Component directly
• Do always pass :position="$position" to <x-dashboard-tile>
• Do use the Tile model for data persistence
• Do use text-default, text-dimmed, etc. for theme-aware colors
• Don't add a $position property or mount() just for position — it's inherited
• Don't add #[Defer] to your tile — it's inherited from BaseTileComponent
• Don't use env() calls outside config files
• Don't store large datasets in tiles — keep data lean for fast rendering