Getting Started

First Steps

Installation
```
composer require symfony/ux-chartjs "^2.35"
npm install chart.js
```
Ensure symfony/ux-chartjs is registered in config/packages/symfony_ux_chartjs.yaml (auto-configured by default).

Basic Setup

Enable the bundle in config/bundles.php:

return [
    Symfony\UX\Chartjs\ChartjsBundle::class => ['all' => true],
];

Import the Twig component in your template:

{% import '@SymfonyUxChartjs/chartjs.html.twig' as chartjs %}

First Chart Create a simple bar chart in a Twig template:

{{ chartjs#bar({
    labels: ['Jan', 'Feb', 'Mar'],
    datasets: [{
        label: 'Sales',
        data: [12, 19, 3],
        backgroundColor: 'rgba(54, 162, 235, 0.5)'
    }]
}) }}

Implementation Patterns

Common Workflows

Dynamic Data Binding Fetch data from a controller and pass it to Twig:

// Controller
public function salesChart(Request $request): Response
{
    $data = $this->salesService->getMonthlyData();
    return $this->render('chart.html.twig', ['data' => $data]);
}

{{ chartjs#bar({
    labels: data.labels,
    datasets: data.datasets
}) }}

Reusable Components Create a base template for charts:

{# templates/components/chart.html.twig #}
<div class="chart-container">
    {{ chartjs#{{ chartType }}({
        labels: chartData.labels,
        datasets: chartData.datasets,
        options: chartOptions
    }) }}
</div>

Interactive Features Use Chart.js plugins (e.g., zoom, annotations) via options:

{{ chartjs#line({
    datasets: [...],
    options: {
        plugins: {
            zoom: { zoom: { wheel: { enabled: true } } }
        }
    }
}) }}

AJAX Updates with Symfony UX 3.x Leverage Symfony UX 3.x for dynamic updates (e.g., Stimulus controllers):

// Using Stimulus (symfony/ux-stimulus)
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    updateChart() {
        fetch('/api/sales')
            .then(response => response.json())
            .then(data => {
                this.chart.update('data', data);
            });
    }
}

Ensure compatibility with Symfony UX 3.x by checking the official docs.

Server-Side Rendering (SSR) For frameworks like Symfony UX Turbo, ensure charts are reinitialized after hydration:

import { Turbo } from '@hotwired/turbo';

Turbo.session.on('turbo:load', () => {
    // Re-render charts after Turbo navigation
    initCharts();
});

Gotchas and Tips

Pitfalls

Twig Component Caching
- Ensure cache:clear is run after adding new chart types (e.g., pie, doughnut).
- Debug missing components with:
```
php bin/console debug:container symfony_ux_chartjs.twig
```

Data Format Strictness

Chart.js expects arrays for labels and data. Validate PHP arrays in Twig:

{% if data.labels is iterable %}
    {{ chartjs#bar({ labels: data.labels, datasets: data.datasets }) }}
{% else %}
    <p>Invalid data format</p>
{% endif %}

CSS Conflicts

Chart.js may override Bootstrap/your CSS. Scope styles:

.chart-container {
    position: relative;
    height: 400px;
    width: 100%;
}
.chart-container canvas {
    max-width: 100% !important;
}

Symfony UX 3.x Compatibility
- Ensure all Symfony UX packages (e.g., symfony/ux-stimulus, symfony/ux-turbo) are updated to v3.x to avoid compatibility issues.
- Check for deprecations in Symfony UX 3.x that might affect chart initialization or updates.

Plugin Compatibility

Some Chart.js plugins (e.g., chartjs-plugin-datalabels) require manual npm installation:
```
npm install chartjs-plugin-datalabels
```

{{ chartjs#bar({
    datasets: [...],
    plugins: [chartjs_plugin_datalabels]
}) }}

Debugging Tips

Console Errors: Check browser console for Chart is not defined (missing chartjs.js or incorrect Twig import).
Data Validation: Use {{ dump(data) }} to verify passed arrays/objects.
Symfony UX 3.x Debugging: Use symfony/ux-check to validate your setup:
```
composer require symfony/ux-check
php bin/console ux:check
```
Chart.js Docs: Reference Chart.js docs for advanced options (e.g., animation, responsive).

Extension Points

Custom Chart Types Extend the bundle by creating a new Twig extension:

// src/Twig/ChartExtension.php
use Symfony\UX\Chartjs\Twig\ChartComponent;

class ChartExtension extends \Twig\Extension\AbstractExtension {
    public function getTwigFunctions() {
        return [
            new \Twig\TwigFunction('custom_chart', [$this, 'renderCustomChart']),
        ];
    }

    public function renderCustomChart(array $data) {
        return (new ChartComponent())->render('custom', $data);
    }
}

Stimulus Integration with Symfony UX 3.x Use Symfony UX Stimulus for dynamic updates:

import { Controller } from '@hotwired/stimulus';
import { Chart } from 'chart.js';

export default class extends Controller {
    static values = { data: Object };
    connect() {
        this.chart = new Chart(this.element, {
            type: 'bar',
            data: this.dataValue,
            options: {}
        });
    }
    updateChart() {
        this.chart.data = this.dataValue;
        this.chart.update();
    }
}

Server-Side Rendering (SSR) with Turbo For frameworks like Symfony UX Turbo, ensure charts are reinitialized after hydration:

import { Turbo } from '@hotwired/turbo';

Turbo.session.on('turbo:load', () => {
    // Re-render charts after Turbo navigation
    document.querySelectorAll('[data-controller="chart"]').forEach(el => {
        el.connect();
    });
});

Symfony UX 3.x Migration
- Update symfony/ux-chartjs to v2.35+ and ensure all related UX packages are on v3.x.
- Review the Symfony UX 3.x migration guide for breaking changes.

Ux Chartjs Laravel Package