livewire-charts

Livewire Charts

This package allows you to add interactive data charts to your apps using Livewire. With a fluent api and built-in Livewire components, you can add charts in your app in no time. You can also add interactions and behaviors to enrich your users' experience. Line, Multiline, Pie, Tree, among other types of charts are ready to use and customized.

Preview

Demo

https://github.com/asantibanez/livewire-charts-demo

Installation

You can install the package via composer:

composer require asantibanez/livewire-charts

Next, you must export the package public scripts. To do this run

php artisan livewire-charts:install

This command will export a vendor/livewire-charts folder under the public directory of your app which is used by the @livewireChartsScripts directive. More on this topic later.

Requirements

This package requires the following packages/libraries to work:

• Laravel Livewire v3 (https://livewire.laravel.com/)
• Apex Charts (https://apexcharts.com/)

Please follow each package/library instructions on how to set them properly in your project.

Note: At the moment, Apex Charts is only supported for drawing charts.

Usage

Livewire Charts supports out of the box the following types of charts

• Line/Multi Line Chart (LivewireLineChart component)
• Pie Chart (LivewirePieChart component)
• Column/Multi Line Chart (LivewireColumnChart component)
• Area Chart (LivewireAreaChart component)
• Radar Chart (LivewireRadarChart component)
• Tree Map Chart (LivewireTreeMapChart component)
• Radial Chart (LivewireRadialChart component)

Each one comes with its own "model" class that allows you to define the chart's data and render behavior.

• LivewireLineChart uses LineChartModel to set up data points, markers, events and other ui customizations.
• LivewirePieChart uses PieChartModel to set up data slices, events and other ui customizations.
• LivewireColumnChart uses ColumnChartModel to set up data columns, events and other ui customizations.
• LivewireAreaChart uses AreaChartModel to set up data points, events and other ui customizations.
• LivewireRadarChart uses RadarChartModel to set up data points, events and other ui customizations.
• LivewireTreeMapChart uses TreeMapChartModel to set up data blocks, events and other ui customizations.
• LivewireRadialChart uses RadialChartModel to set up data bars, events and other ui customizations.

For example, to render a column chart, we can create an instance of ColumnChartModel and add some data to it

$columnChartModel = 
    (new ColumnChartModel())
        ->setTitle('Expenses by Type')
        ->addColumn('Food', 100, '#f6ad55')
        ->addColumn('Shopping', 200, '#fc8181')
        ->addColumn('Travel', 300, '#90cdf4')
    ;

Note: Chart model methods are chainable

With $columnChartModel at hand, we pass it to our LivewireColumnChart component in our Blade template.

reactiveKey() }}" --}}
    :column-chart-model="$columnChartModel"
/>

Note: Optionally add "key" to enable props reactivity if needed

Next, include the @livewireChartsScripts directive next to your other app scripts

@livewireScripts
@livewireChartsScripts

And that's it! You have a beautiful rendered chart in seconds.

Note: You can use these charts inside other Livewire components too. Just render them in your Blade template and you are good to go.

LivewireCharts facade

Chart models can also be created using the LivewireCharts facade.

LivewireCharts::lineChartModel();
LivewireCharts::multiLineChartModel();
LivewireCharts::columnChartModel();
LivewireCharts::multiColumnChartModel();
LivewireCharts::pieChartModel();
LivewireCharts::areaChartModel();
LivewireCharts::radarChartModel();
LivewireCharts::treeMapChartModel();
LivewireCharts::radialChartModel();

Enabling Interactions

To enable click events, you must use the with[XXX]ClickEvent($eventName) method present in every model class and define a custom $eventName that will be fired with the corresponding data when a column/marker/slice is clicked.

$columnChartModel = 
    (new ColumnChartModel())
        ->setTitle('Expenses by Type')
        ->withOnColumnClickEventName('onColumnClick')
    ;

Here we define an onColumnClick event that will be fired when a column is clicked in our chart.

We can listen to the onClickEvent registering a listener in any other Livewire component.

#[On('onColumnClick')]
public function handleOnColumnClick($event)
{
   // Handle event
} 

"Reactive" Charts

You can use livewire-charts components as nested components in you Livewire components. Once rendered, charts will not automatically react to changes in the $model passed in. This is just how Livewire works.

However, to enable "reactivity" when data passed in changes, you can define a special $key to your components so they are fully re-rendered each time the chart data changes.

Each model class comes with a reactiveKey() method that returns a string based on its data. If any of the properties are changed, this key will update accordingly and re-render the chart again.

In the following example, a parent component houses both column chart and pie chart and defines a $model for each one. The parent component renders the charts as follows

reactiveKey() }}"
    :column-chart-model="$columnChartModel"
/>

reactiveKey() }}"
    :pie-chart-model="$pieChartModel"
/>

When the parent component changes their respective models, charts will automatically re-render itself.

Charts API

For each chart, a specific model class needs to be used. Here, it is detailed the api available for each type of chart.

All

LivewireLineChart

LivewireColumnChart

LivewirePieChart