Getting Started

Minimal Setup

Installation:

composer require matheusmarnt/livecharts
php artisan livecharts:install

This publishes config, assets, and optionally chart stubs.

First Chart:

use Matheusmarnt\LiveCharts\Facades\LiveCharts;

$chart = LiveCharts::line()
    ->title('Monthly Revenue')
    ->labels(['Jan', 'Feb', 'Mar'])
    ->dataset('2026', [100, 200, 150])
    ->colors(['#3B82F6']);

Render in Blade:

@liveChartsScripts
<livewire:livecharts :chart="$chart" />

Key First Use Case

Create a reactive dashboard where chart data updates dynamically without JavaScript. Example:

// In a Livewire component
public $revenueData = [100, 200, 150];

public function render()
{
    $chart = LiveCharts::line()
        ->title('Revenue')
        ->labels(['Jan', 'Feb', 'Mar'])
        ->dataset('2026', $this->revenueData);

    return view('livewire.dashboard', compact('chart'));
}

Implementation Patterns

1. Fluent Builder Workflow

Chain methods for declarative chart configuration:

LiveCharts::bar()
    ->title('Sales')
    ->labels(['Q1', 'Q2'])
    ->dataset('North', [400, 300])
    ->dataset('South', [200, 150])
    ->stacked()
    ->height(400);

Reuse charts via class-based builders:

// app/Charts/RevenueChart.php
class RevenueChart extends Chart {
    public function __construct() {
        $this->title('Revenue')
             ->labels(['Jan', 'Feb'])
             ->dataset('2026', [100, 200]);
    }
}

2. Livewire Integration

Bind to Livewire properties:

// Livewire component
public $chartData = [100, 200];

public function updatedChartData() {
    $this->chart = LiveCharts::line()
        ->dataset('Revenue', $this->chartData);
}

Polling for real-time updates:

$chart->poll(5000); // Refresh every 5s

<livewire:livecharts :chart="$chart" wire:poll="refresh" />

3. Event Handling

Map chart events to Livewire:

$chart->onDataPointClick('chart-clicked');

// Livewire component
#[On('chart-clicked')]
public function handleClick(array $data) {
    // $data = ['seriesIndex' => 0, 'value' => 150, ...]
}

4. Multi-Engine Support

Switch engines globally (config) or per chart:

LiveCharts::line()->engine('chartjs')->labels(['Jan']);

Register custom engines:

LiveCharts::registerEngine('highcharts', HighchartsAdapter::class);

5. Theming & Dark Mode

Theme-aware colors:

->titleColor(dark: TwColor::Amber300, light: TwColor::Amber600)

Auto-detect dark mode (no Livewire roundtrip):
```
->theme('auto');
```

6. Broadcasting

Push updates via Laravel Echo:

$chart->broadcastOn('private-charts.user1')->broadcastAs('chart.updated');

Gotchas and Tips

Pitfalls

Asset Loading:
- Issue: @liveChartsScripts must appear before @livewireScripts in your layout.
- Fix: Place it right after <body> or in <head> if using @extends.
- Debug: Check browser console for livecharts.js 404 errors.
Polling Conflicts:
- Issue: Multiple wire:poll on the same component can cause race conditions.
- Fix: Use unique poll keys or disable polling via wire:poll.ignore="refresh".
Color Roundtrip:
- Issue: Custom colors may not render as expected in dark mode.
- Fix: Use TwColor enum for theme-aware colors:
```
->colors([TwColor::Blue500, TwColor::Red400])
```
Engine-Specific Quirks:
- ApexCharts: Supports all 18 chart types but may need ->options(['...']) for advanced configs.
- Chart.js: Requires explicit plugin registration for treemap, sankey, etc.:
```
LiveCharts::treemap()->engine('chartjs')->plugins(['treemap']);
```
Stub Customization:
- Issue: Default make:chart stubs may not match your project’s PSR-12 style.
- Fix: Override stubs by publishing them first:
```
php artisan vendor:publish --tag=livecharts-stubs --force
```
  Then edit stubs/livecharts/chart.stub.

Debugging Tips

Preview All Charts:
```
php artisan livecharts:preview
```
Opens a gallery of every chart type for visual debugging.

Log Chart Payload: Add this to your Livewire component to inspect the serialized chart:

public function mount() {
    \Log::info('Chart payload:', $this->chart->toArray());
}

Check Engine Compatibility:
- Run php artisan livecharts:install --force to ensure assets are up to date.
- Verify engine support with:
```
LiveCharts::availableEnginesForType('line'); // ['apexcharts', 'chartjs']
```
Dark Mode Issues:
- Ensure your layout has <html class="dark"> or prefers-color-scheme: dark in CSS.
- Test with:
```
->theme('dark')->titleColor(TwColor::Slate500);
```

Extension Points

Custom Engines: Implement Matheusmarnt\LiveCharts\Contracts\EngineAdapter and register it:
```
LiveCharts::registerEngine('my-engine', MyEngineAdapter::class);
```

Chart Modifiers: Extend the Chart class to add domain-specific methods:

class FinancialChart extends Chart {
    public function addCandlestickSeries(string $label, array $data) {
        $this->dataset($label, $data)->type('candlestick');
        return $this;
    }
}

Asset Customization: Override asset paths in config/livecharts.php:

'assets' => [
    'mode' => 'local', // 'cdn', 'both'
    'path' => 'custom/path/to/livecharts',
],

Translation Overrides: Publish translations and extend them:
```
php artisan vendor:publish --tag=livecharts-translations
```
Edit resources/lang/en/livecharts.php.

Livecharts Laravel Package