Download the PHP package happenv-com/filament-enhanced-charts without Composer

Apache ECharts for Filament

Apache ECharts integration for Filament: dashboard widgets and table columns driven by a fully typed, fluent PHP option model.

Key features

• Typed option model. The ECharts option tree is mirrored as fluent PHP builders — if you know an ECharts option, you know the method — and everything not (yet) modelled stays reachable through a ->raw() escape hatch on every node (The option model).
• 23 series types. Line, bar, pie, scatter, effectScatter, candlestick, boxplot, heatmap, radar, gauge, funnel, sankey, chord, sunburst, treemap, tree, graph, parallel, themeRiver, pictorialBar, map, lines, and fully custom renderItem series.
• Every coordinate system. Cartesian grids, polar, radar, geo/maps, calendar, singleAxis, parallel and matrix — plus datasets with transforms, visual maps, data zoom, toolbox, brush and graphic elements.
• Filament-native. Panel theming, automatic filters.
• Data straight from Eloquent. ChartData::fromPairs(), ChartData::fromTimeSeries() (laravel-trend compatible) and Dataset::fromModels() turn query results into chart data, and HasChartData builds a whole chart from data and a type (Feeding data from Eloquent).
• 64 languages. Month and day names, toolbox and aria strings follow the app locale in every language Filament ships (Translations).
• Charts in table cells. Sparklines, candlesticks and donut pies inside table cells via EnhancedChartColumn, or any custom per-record chart (Charts in table cells).
• Testable. Livewire assertions for the resolved chart options in your application's tests (Testing your application), and the package itself is covered by a Pest suite on every supported version combination.

Gallery

A taste of what the typed option model draws — every chart is a regular widget class, and follows your panel's light or dark mode automatically.

Requirements

Installation

Install the package via Composer:

Register the plugin on each Filament panel that should render charts:

After installing or upgrading, republish the compiled JavaScript assets:

Upgrading from filament-echarts 2.x? See UPGRADING.md.

Configuration

Publish the config file:

It lists the chart types the make:filament-enhanced-charts generator offers (see Generating a widget):

Optionally, publish the views and translations:

Usage

Generating a widget

The generator asks for the chart type, an optional resource and the panel, and writes a ready-to-edit widget from the matching stub:

Your first widget

A chart widget is a regular Filament widget: extend EnhancedChartWidget and return an Option from getOption(). That is the whole story.

Two entry points exist on Option:

• Option::make() — a blank slate.
• Option::cartesian() — a batteries-included preset for the common case: an axis-triggered tooltip and a top legend, ready for ->xAxis() + ->series().

When an x-axis is set and no y-axis is given, a ValueAxis is defaulted for you. Set ->yAxis(...) explicitly when you need something else (e.g. a CategoryAxis for a heatmap).

The option model

Everything under Happenv\FilamentEnhancedCharts\Option\* is a fluent builder that serializes to the exact ECharts option shape. This package deliberately does not re-document every chart type — the ECharts docs and examples gallery are the reference; the builders mirror them method-for-method.

Conventions that hold across the whole tree:

• ::make() + fluent setters. Every builder is created with ::make() and configured by chaining; setters return $this.
• One or many. Slots that ECharts accepts as "an object or an array of objects" are variadic: ->grid(...), ->xAxis(...), ->title(...), ->series(...), ->visualMap(...), … Pass one or several; the emitted JSON follows ECharts' single-vs-array convention automatically.
• Builders or arrays. Sub-config setters accept the matching builder or a plain array: ->itemStyle(ItemStyle::make()->borderRadius(4)) and ->itemStyle(['borderRadius' => 4]) are equivalent.
• Conditional building. All builders use Laravel's Conditionable: ->when($this->filter === 'year', fn (Option $o) => $o->dataZoom(...)).
• Per-point configuration. Wherever a data item can be more than a value, pass a DataPoint: DataPoint::make(1048)->name('Search')->itemStyle(ItemStyle::make()->color('#c23531')).

The raw() escape hatch

Every node (Option, each series, axis, component, DataPoint, …) accepts ->raw(array $options). Raw options are deep-merged over the typed output, raw wins — so you can reach any ECharts option the typed API doesn't model yet without abandoning the builders:

To skip the typed model entirely, return a raw tree from a blank Option:

Prefer the typed methods — raw() is the last resort, not the default.

Formatters and JS callbacks

Strings passed to formatter()-style methods are treated as literal ECharts templates and pass through unchanged. For a real client-side function, pass Filament's RawJs: it is serialized as a marker and revived into a genuine JS function in the browser.

RawJs works anywhere in the tree — renderItem on a CustomSeries, symbolSize callbacks, animationDelay functions, labelLayout, colors-by-callback, and so on. Inside these callbacks the echarts global is available, so gallery snippets using echarts.format.addCommas(...) or echarts.graphic.clipRectByRect(...) port verbatim.

Numbers

Anywhere a number is accepted you may pass a native \BcMath\Number instead of int|float|string; it is serialized as an exact numeric literal rather than a lossy float.

Feeding data from Eloquent

A series' data() and an axis' data() take any iterable, so a Collection works — but the shape matters:

• A positional list (a bare pluck or an array) → pass it straight to data(). Keys are dropped (the series/axis is positional), so a keyed Collection never mis-serializes to an object:

• A keyed map where the key is the label (pluck('total', 'channel'), a groupBy count) → use ChartData::fromPairs() to split it into labels + values:

• Tabular rows for multiple series → build a Dataset and let each series encode() its columns. Dataset::fromModels() projects a query result to just the chart columns (never the full attribute bag) — don't hand a Collection<Model> to data():

Time series

For "per day/week/month" aggregations, flowframe/laravel-trend is the recommended companion: it handles the per-driver date bucketing (Postgres/MySQL/MariaDB/ SQLite) and gap-fills empty periods with zeros. It is an optional suggest — install it only if you need time series:

Feed its result straight to ChartData::fromTimeSeries():

ChartData::fromTimeSeries() reads date/aggregate off each row with data_get(), so it is decoupled from the trend package — any Collection of rows carrying a label and a value column works (pass labelKey:/valueKey: for different column names).

Shortcut: a chart from just data + a type

When the chart is a single series of one of the common types, the HasChartData trait writes getOption() for you — declare the data and (optionally) the type, nothing else:

ChartType is a curated set — Line, Area, Bar, Pie — that maps cleanly onto the labels + values (or, for pie, the named DataPoint) shape. The trait builds a cartesian option (category x-axis + value y-axis) for the axis types and an axis-less option for pie. The moment you want more — a second series, custom styling, marks, a scatter's x/y pairs — implement getOption() directly with the typed builders; this trait is only the shallow-end shortcut.

Colors

Color setters (color(), backgroundColor(), borderColor(), shadowColor(), …) accept:

• any CSS color string ('#7c3aed', 'rgb(124, 58, 237)'),
• an ECharts gradient/pattern array,
• a Filament palette — Color::Amber resolves to its 500 shade, and Filament's oklch(...) values are converted to rgb() so ECharts can both paint them and derive hover shades:

Dark mode

Dark mode is automatic. Charts render transparent over the Filament card, and when the panel is in dark mode the package overlays a theme layer client-side — axis lines/labels, split lines, legend, title, tooltip, visual maps, parallel axes and outside series labels are all lightened for readability. The theme reapplies live when the user toggles light/dark. You write the option once; both modes just work.

Tip: skip forced backgroundColor and hardcoded text colors in your options — inherit the card and let the theme adapt.

Page scrolling

By default the mouse wheel scrolls the page, not the chart: inside data zoom stops wheel-zooming (drag-to-pan is kept) and any roam is downgraded to drag-pan. That way a dashboard full of charts never traps the user's scroll.

Opt a chart back into wheel-zoom (e.g. a full-bleed map) on the widget:

or per option, which wins over the widget default:

Widget configuration

The header disappears entirely when no heading, subheading or filters are set.

Deferred loading

Don't hold up the page for a slow query:

Loading indicator

Live updating (polling)

Widgets poll every 5 seconds by default. Change or disable it with an instance property:

Updates are diffed server-side — the chart only re-renders when the resolved options actually changed.

Filtering chart data

Single select

Return options from getFilters() and read the active value from $this->filter:

A select appears in the widget header and the chart updates live on change.

Filter schema

For a richer filter form, implement the package's HasFiltersSchema contract and use Filament's chart-widget filters trait; filter values arrive in $this->filters:

Implementing the contract is what makes the filter dropdown render — don't skip it.

Maps (GeoJSON)

A MapSeries or geo component needs its map registered client-side. Return name => url pairs from getMaps(); each is fetched and passed to echarts.registerMap() before first paint:

Charts in table cells

EnhancedChartColumn renders a small chart per row. Three presets cover the common cases; chart() takes over for anything else. Return null/empty data to render nothing for that row.

Cell charts ship with a sensible baseline (tooltip escaping the cell, no legend, tight margins) and are disposed cleanly as rows leave the DOM. ->renderer('svg') is available per column. Custom ->chart() closures can start from the same baseline via EnhancedChartColumn::cellOption() (optionally passing the tooltip trigger, e.g. 'axis').

Testing your application

The package registers a Livewire Testable mixin with chart assertions for your app's tests:

RawJs and BcMath\Number values appear in the resolved options as ['__js__' => '…'] markers — see UPGRADING.md.

Translations

Charts speak your app's locale. Month and day names on time axes and calendars, the toolbox, legend selector and the screen-reader (aria) description all follow app()->getLocale() — in every language Filament ships:

am ar az bg bn bs ca ckb cs da de el en es et eu fa fi fil fr he hi hr hu hy id it ja ka km ko ku lt lus lv mk mn ms my nb ne nl pl pt pt_BR ro ru sk sl sq sr_Cyrl sr_Latn sv sw tg th tr uk ur uz vi zh_CN zh_HK zh_TW

Each language is an ECharts locale object in resources/lang/{locale}/locale.php. Where ECharts has its own translation it is used as is (npm run locales regenerates those files); for the others the month and day names come from CLDR and the rest is translated in the package. A missing key falls back to English.

Publish the files to change a string or add a language:

Development

The package's JavaScript is built by bin/build.js into resources/dist, which is committed. After changing resources/js, rebuild and commit the result — CI refuses outdated assets:

Upgrading

Breaking changes and how to migrate are described in UPGRADING for every major version.

Changelog

See CHANGELOG and GitHub releases for what has changed recently.

Contributing

See CONTRIBUTING for details.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Happenv sp. z o.o.
• webard
• elemind
• Strongly inspired by Leandro Ferreira's Apex Charts plugin
• All contributors

License

The MIT License (MIT). See License File for more information.