README

Chart.wire are simple charts for use with Laravel Livewire.

• Requirements
• Installation
• Usage
• Changelog
• Contributing
• Security
• License

Requirements ^

This package requires the following packages/libraries:

• Alpine.js
• Chart.js
• Laravel Livewire

Installation ^

You can install the package via composer:

composer require opensaucesystems/chartwire

Usage ^

Chart.wire supports out of the box the following types of charts

• Line Chart
• Bar Chart
• Doughnut Chart
• Pie Chart
• Area Chart
• Sparkline Chart

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

• Line Chart uses LineChartModel
• Bar Chart uses BarChartModel
• Doughnut Chart uses DoughnutChartModel
• Pie Chart uses PieChartModel
• Area Chart uses AreaChartModel
• Sparkline Chart uses SparklineChartModel

For example, to render a line chart, we create an instance of LineChartModel and pass it to the Livewire Line Chart component:

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 0.6)',
    'pointBackground' => 'rgba(54, 162, 235, 0.6)',
]);

$lineChartModel = (new \Opensaucesystems\Chartwire\Models\LineChartModel())
    ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors)
    ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors)
    ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors)
    ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors)
    ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors)
    ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors)
    ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors);

<livewire:line-chartwire :line-chart-model="$lineChartModel" />

Chart Model Methods ^

Common methods

These methods are common to all chart models

Legend methods

The following chart types support these methods:

• Line Chart
• Bar Chart
• Doughnut Chart
• Pie Chart
• Area Chart

Axis methods

The following chart types support these methods:

• Line Chart
• Bar Chart
• Doughnut Chart
• Pie Chart
• Area Chart

Title methods

The following chart types support these methods:

• Line Chart
• Bar Chart
• Doughnut Chart
• Pie Chart
• Area Chart

Event methods

The following chart types support these methods:

• Line Chart
• Bar Chart
• Doughnut Chart
• Pie Chart
• Area Chart

When an event of type mouseup or click is triggered on the chart, then Livewire will emit an event with the name of the argument passed into this method. It will also pass the label and value that was clicked.

$lineChartModel = (new \Opensaucesystems\Chartwire\Models\LineChartModel())
    ->withOnClickEventName('onMyLineChartClicked');

Now you may register this event in another components $listeners property:

class ShowData extends Component
{
    public $label;
    public $value;

    protected $listeners = ['onMyLineChartClicked' => 'handleMyLineChartClicked'];

    public function handleMyLineChartClicked(array $data)
    {
        $this->label = $data['label'];
        $this->value = $data['value'];
    }
}

Stacked methods

The following chart types support these methods:

• Line Chart
• Bar Chart
• Area Chart

Sparkline charts ^

Sparkline charts are just a normal Line Chart with the default options hiding the legend, title, axes, tooltips etc.

To set the height and width of the Sparline Chart just use CSS.

This examples use TailwindCSS:

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 0.6)',
])

$sparklineChartModel = (new \Opensaucesystems\Chartwire\Models\SparklineChartModel())
        ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors)
        ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors)
        ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors)
        ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors)
        ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors)
        ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors)
        ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors);

<div class="h-10 w-20">
    <livewire:sparkline-chartwire :sparkline-chart-model="$sparklineChartModel" />
</div>

Colors ^

Each dataset requires a ColorValue object.

The ColorValue instance requires a border color. The background and pointBackground is optional.

The color can be simple a hexadecimal, RGB, or their color names.

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'border' => 'rgba(54, 162, 235, 0.6)',
])

Since Chart.js supports a CanvasGradient object, the ColorValue supports a LinearGradientValue object that is converted into a JS CanvasGradient object.

use Opensaucesystems\Chartwire\Values\ColorStopValue;
use Opensaucesystems\Chartwire\Values\LinearGradientValue;

$backgroundColorStops = [
    new ColorStopValue(['color' => 'rgba(54, 162, 235, 0.6)', 'offset' => 0]),
    new ColorStopValue(['color' => 'rgba(54, 162, 235, 0)', 'offset' => 1]),
];
$borderColorStops = [
    new ColorStopValue(['color' => '#80b6f4', 'offset' => 0]),
    new ColorStopValue(['color' => '#f49080', 'offset' => 1]),
];

$backgroundGradient = new LinearGradientValue([
    'x1' => 0,
    'y1' => 100,
    'x2' => 0,
    'y2' => 370,
    'colorStops' => $backgroundColorStops,
])
$borderGradient = new LinearGradientValue([
    'x1' => 500,
    'y1' => 0,
    'x2' => 100,
    'y2' => 0,
    'colorStops' => $borderColorStops,
]);

Multiple Datasets ^

You can also add multiple datasets to a chart that will allow you to group data.

Stacked

Stacked charts allows you to see that data is made up of a number of smaller pieces.

$colors2010 = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 1)',
]);
$colors2020 = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(37, 194, 160, 0.6)',
    'border' => 'rgba(37, 194, 160, 1)',
]);

$barChartModel = (new \Opensaucesystems\Chartwire\Models\BarChartModel())
    ->addDataToDataset('Populations 2010', 1339724852, 'China', $colors2010)
    ->addDataToDataset('Populations 2010', 1182105564, 'India', $colors2010)
    ->addDataToDataset('Populations 2010', 309349689, 'United States', $colors2010)
    ->addDataToDataset('Populations 2010', 237641326, 'Indonesia', $colors2010)
    ->addDataToDataset('Populations 2010', 173510000, 'Pakistan', $colors2010)
    ->addDataToDataset('Populations 2010', 193252604, 'Brazil', $colors2010)
    ->addDataToDataset('Populations 2010', 158258917, 'Nigeria', $colors2010)
    ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors2020)
    ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors2020)
    ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors2020)
    ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors2020)
    ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors2020)
    ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors2020)
    ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors2020);

<livewire:bar-chartwire :bar-chart-model="$barChartModel" />

Troubleshooting ^

Chart components must be placed inside a container with fixed height. This is because the chart will use all the given vertical space. A fixed height is needed to render properly.

<div style="height: 32rem;">
    <livewire:livewire-column-chart .../>
</div>

>Note: if a fixed height is not given, the chart will grow vertically infinitely. That's not what we want, right?

Testing ^

composer test

Changelog ^

Please see CHANGELOG for more information what has changed recently.

Contributing ^

Please see CONTRIBUTING for details.

Security ^

If you discover any security related issues, please email ashley@opensauce.systems instead of using the issue tracker.

Credits and Influences ^

• Laravel
• Laravel Livewire
• Tailwind CSS
• AlpineJS
• livewire-charts by asantibanez
• All Contributors

License ^

The MIT License (MIT). Please see License File for more information.