Larapex Livewire Laravel Package

Getting Started

This is a thin, low-traffic wrapper (4 stars, no dependents) around ApexCharts for Livewire. Treat the README and src/ as the source of truth over any docs you find elsewhere, and pin the version in composer.json since the package isn't widely battle-tested. v2.0.0 is a major bump from v0.0.2 that introduces Light/Dark theme support — expect breaking changes from any 0.0.x code you may have written against earlier. Read the changelog and src/ before upgrading an existing install.

1. Install / upgrade

composer require larawire-garage/larapex-livewire

If upgrading an existing project, review the diff between v0.0.2 and v2.0.0 for changed component signatures — a theme feature usually means new required or restructured options keys.

2. Publish config/views/assets — run php artisan vendor:publish --provider="LarawireGarage\\LarapexLivewire\\LarapexLivewireServiceProvider" and inspect the tags. The theme feature almost certainly adds a config entry (default theme, dark-mode detection strategy). Publish config/larapex-livewire.php first and read what keys v2.0.0 exposes.

3. First use case — the fastest win is still a "sales over time" line chart from an Eloquent query inside a Livewire component. Define series/options, render the package's Blade tag, then toggle your app's dark mode and confirm the chart repaints correctly. That theme toggle is the fastest way to validate the v2.0.0 feature and surface asset/config issues at the same time.

Where to look first:

• README.md for the v2.0.0 theme API (likely a theme prop or config key)
• src/ for the component signatures — check whether theme is per-chart, global config, or auto-detected
• resources/js (if present) to see which ApexCharts version is bundled — theme handling shapes changed across ApexCharts majors
• config/larapex-livewire.php (after publishing) for theme defaults

Implementation Patterns

Static Blade component usage — pass pre-computed series and options to the chart tag. Build $series in the Livewire render() or a computed property so it re-evaluates per request.

<livewire:apex-chart
    type="line"
    :series="$series"
    :options="$options"
    theme="auto"
/>

Theme handling (v2.0.0) — the new Light/Dark support is the headline feature. Two patterns worth knowing:

• Auto-detect — if the package reads prefers-color-scheme or a dark class on <html>, just set the theme to auto and let it follow your app. Verify in src/ whether detection is CSS-class-based (Tailwind dark:) or media-query-based; if it's the wrong one for your app, you'll need to override.
• Explicit control — when you want the chart theme to match a user preference (e.g. a settings toggle), bind a public property and pass it through. Treat the theme value as part of the chart config, not an afterthought.

public string $theme = 'light'; // 'light' | 'dark' | 'auto'

public function toggleTheme(): void
{
    $this->theme = $this->theme === 'dark' ? 'light' : 'dark';
}

Matching chart theme to app theme. ApexCharts theme.mode must agree with your layout's background/border colors. If your app toggles dark mode via Alpine, either (a) pass theme down to the component so Livewire re-renders, or (b) dispatch a browser event and let a tiny Alpine.data block call chart.updateOptions({ theme: { mode } }). Do not mix the two — pick one source of truth.

Reactive data via wire:model / wire:poll — bind filters to public properties and let Livewire re-render. If the wrapper doesn't push updates to ApexCharts on the JS side, hook Livewire.on('chartUpdated', ...) and call chart.updateSeries(newSeries). Note: a theme change and a data change may both trigger re-renders — batch them if a single toggle causes a full chart teardown.

Multi-series / mixed charts — each series as ['name' => ..., 'data' => [...]]; per-series type for mixed, options.chart.type as fallback.

Config in PHP, not JS — keep ApexCharts options including theme, toolbar, legend, yaxis, dataLabels in a PHP array. Escape callbacks (formatter) via raw JS where supported, or a small Alpine.data block.

Real-time updates — pair with Echo in getListeners(); mutate series and dispatch('chartUpdated'). Update series in place; a full re-render on every event will fight the theme feature and cause flicker.

Livewire integration tips

• One data source, one chart per component.
• Use wire:ignore only if updating purely via JS; otherwise let Livewire manage re-renders.
• wire:key keyed on the chart config including theme — a type or theme change should force a clean remount.

Gotchas and Tips

Theme + SPA navigation. The classic ApexCharts wrapper failure mode — chart renders then vanishes after wire:navigate — is worse with v2.0.0 because the theme initializer may also need to re-run. Ensure the ApexCharts script loads once in your layout and the component re-initializes on livewire:navigated. If the wrapper doesn't handle it, add a listener that re-runs init and re-applies the theme.

Theme detection mismatch. If the package auto-detects dark mode via prefers-color-scheme but your app uses a manual toggle (Tailwind dark class), the chart will show the wrong theme. Check src/ for how detection works and either pass an explicit theme or override the config. If it's class-based, ensure the class is on the element the package actually queries (usually <html>, not <body>).

Breaking changes between v0.0.2 and v2.0.0. A two-major jump in a 0.0.x package almost always includes renamed props, changed options merging, or a new config file. Diff the published config and the component signature against what you had. If upgrading, grep your app for the chart tag and update theme/options keys before trusting green tests.

Re-render destroys the instance. A theme toggle that triggers a Livewire re-render replaces the DOM node, leaving ApexCharts with a stale reference — blank canvas. Duplicate SVGs in DevTools signal this. Call chart.destroy() before re-init, or better, update the theme in place via updateOptions.

JSON serialization pitfalls. Cast Eloquent collections to plain arrays (->toArray()) and cast numerics. Stringly-typed y-values silently flatten lines.

Numbers as strings. MySQL returns strings; ApexCharts tolerates it but yaxis.min and tooltip formatting misbehave. Cast to (float).

Timestamps and categories. Either xaxis.type = 'datetime' with epoch milliseconds or categories with formatted labels — never mix. ApexCharts wants ms, not toDateTimeString.

CDN vs bundled version. Check which ApexCharts version the wrapper loads. Recent ApexCharts majors changed theme, legend.position, and dark-mode option shapes — a stale CDN URL against a v2.0.0 wrapper that expects a newer ApexCharts will produce "theme ignored" bugs. Pin both.

Alpine.js conflicts. If the wrapper uses x-data (likely for theme toggling in v2.0.0), don't add x-data to the same node — nest it.

Debugging. When blank: (1) element in DOM with non-zero height? ApexCharts needs explicit height; (2) series non-empty in network response; (3) console — ApexCharts is not defined (asset) vs Chart not found (lifecycle); (4) theme toggle shows no change — check the applied theme.mode in DevTools against your layout; (5) ->toJson() the PHP array in render to confirm shape.

Extension points. If the wrapper's theme handling doesn't fit, publish and copy the Blade view into resources/views/vendor/larawire-garage/ and override. For anything ApexCharts supports that the wrapper doesn't expose, drop to a plain <div> plus inline JS in the Livewire component — the wrapper buys little beyond init code, and v2.0.0's theme plumbing is easy to replicate.

Maturity caveat. Still 4 stars, 0 dependents, and a big version jump. Pin a version, add a smoke test asserting the rendered HTML contains the chart container, and a second test that toggles theme and asserts no console error. Be prepared to fork for bugfixes rather than waiting on upstream.