Download the PHP package asharif88/filament-plotly without Composer

Filament Plotly.js Widget

Inspired by Leandro Ferreira’s Apex Charts plugin & Elemind's Echarts plugin this plugin delivers plotly.js integration for Filament.

Table of Contents

• Installation
• Usage
  • Setting a widget title
  • Setting a widget subheading
  • Setting a chart id
  • Making a widget collapsible
  • Setting a widget height
  • Setting a widget footer
  • Header & Footer Actions
  • Hiding header content
  • Filtering chart data
  • Live updating (polling)
  • Defer loading
  • Loading indicator
  • Chart overlay
  • Post-init JS hook
  • Dark / light theme sync
  • Plotly event listeners
  • Streaming support
  • Streaming layout patch
• Changelog
• Contributing
• Credits
• License

Installation

You can install the package via composer:

Register the plugin for the Filament Panels you want to use:

Usage

Start by creating a widget with the command:

The plugin uses the Plotly.react function to render charts. This function takes in the chart data, layout and config as parameters.

You need to implement the getChartData() method to return an array with data, layout and config keys:

Alternatively, you can set the data, layout and config separately by implementing the following methods:

Setting a widget title

You may set a widget title:

Optionally, you can use the getHeading() method.

Setting a widget subheading

You may set a widget subheading:

Optionally, you can use the getSubheading() method.

Adding custom content

You can add custom content before chart within the widget container using the getbeforeContent() method.

Setting a chart id

You may set a chart id:

Making a widget collapsible

You may set a widget to be collapsible:

You can also use the isCollapsible() method:

Setting a widget height

By default, the widget height is set to 300px. You may set a custom height:

Optionally, you can use the getContentHeight() method.

Setting a widget footer

You may set a widget footer:

You can also use the getFooter() method:

Custom view:

Html string:

Header & Footer Actions

You can register Filament actions to appear in the widget header or footer. Override getHeaderActions() / getFooterActions() on your widget to return an array of Filament\Actions\Action (or ActionGroup) instances. These actions are rendered by Filament's actions component and respect alignment settings.

Example — simple header actions:

Example — footer actions:

Notes:

• You may return ActionGroup instances if you need grouped or dropdown actions.
• Header actions are rendered next to any filter controls defined on the widget.
• Footer actions render above the footer content returned by getFooter().

Hiding header content

You can hide header content by NOT providing these

• $heading
• getHeading()
• $subheading
• getSubheading()
• getOptions()

Filtering chart data

You can set up chart filters to change the data shown on chart. Commonly, this is used to change the time period that chart data is rendered for.

Filter schema

You may use components from the Schemas to create custom filters. You need to use HasFiltersSchema trait and implement the filtersSchema() method to define the filter form schema:

The data from the custom filter is available in the $this->filters array. You can use the active filter values within your getChartData() method:

Single select

To set a default filter value, set the $filter property:

Then, define the getFilters() method to return an array of values and labels for your filter:

You can use the active filter value within your getOptions() method:

Live updating (polling)

By default, chart widgets refresh their data every 5 seconds.

To customize this, you may override the $pollingInterval property on the class to a new interval:

Alternatively, you may disable polling altogether:

Defer loading

This can be helpful when you have slow queries and you don't want to hold up the entire page load:

Loading indicator

You can change the loading indicator:

You can also use the getLoadingIndicator() method:

Chart overlay

Use getChartOverlay() to render HTML inside the chart container — directly on top of the Plotly canvas. This is the right place for progress bars, custom annotation panels, and loader overlays, because the content sits naturally inside the chart div without requiring document.getElementById or absolute-positioning tricks.

The overlay is rendered inside a wire:ignore container, so it is set once on mount and then controlled by JavaScript. It will not be re-rendered by Livewire on subsequent updates.

Post-init JS hook

Override getOnChartReadyScript() to run plain JavaScript the moment the Plotly chart is fully initialised. Inside the script, el refers to the chart DOM element.

Dark / light theme sync

Use the HasChartTheme concern to keep Plotly's visual theme in sync with Filament's dark/light mode automatically. The Alpine component watches the dark class on <html> via a MutationObserver and calls Plotly.relayout() whenever the mode changes — no getFooter() workaround needed.

The layout properties returned by each method are merged into the live chart layout via Plotly.relayout(). Return any valid Plotly layout keys.

Plotly event listeners

Override getPlotlyEventListeners() to map Plotly JS events to public methods on your widget. When a mapped event fires, two things happen:

1. The mapped method is called on this widget with a serialised payload.
2. A window-level Alpine event plotly:{event} is dispatched so that sibling Livewire components (a table, a slide-over) can also react without coupling to the chart widget.

Store the record's primary key in customdata when building trace data — that's the standard Plotly mechanism for carrying arbitrary metadata per point:

To react from a separate Livewire component (e.g. a ListOrders resource page), listen for the broadcasted window event:

Supported events and payload shapes

DOM nodes, full trace objects, and axis definitions are stripped before serialisation — only safe, JSON-friendly values reach Livewire.

Streaming support

The HasStreamingSupport concern replaces the traditional getFooter() SSE boilerplate with a small set of override methods. The library owns the EventSource lifecycle, the progress overlay, and component cleanup — your widget only declares what is domain-specific.

SSE message protocol

Your server-side stream must emit JSON messages in this format:

Basic example

Returning null from getStreamUrl() disables streaming entirely — useful when required state (e.g. a selected source) has not been set yet.

Full example with theme and click events

The following shows HasStreamingSupport, HasChartTheme, and getPlotlyEventListeners() working together, which is the recommended pattern for a production streaming widget:

Streaming layout patch

Override getStreamingLayoutPatch() to declare layout properties that must be force-merged into the layout on every stream reset, regardless of what el.layout currently holds.

When to use this vs HasChartTheme: If you use HasChartTheme, theme properties are tracked in el.layout and are automatically preserved across stream resets — you do not need getStreamingLayoutPatch() for theme sync. Use getStreamingLayoutPatch() when you need to inject layout properties that are not managed by HasChartTheme, or when you cannot use that trait.

Dark mode

The dark mode is supported and enabled by default for the container.

Publishing views

Optionally, you can publish the views using

Publishing translations

Optionally, you can publish the translations using:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Ahmad SHARIF
• All Contributors

License

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