> [!PRO] > This component is only available in the Pro version of Flux. # Chart Flux's Chart component is a lightweight, zero-dependency tool for building charts in your Livewire applications. It is designed to be simple but extremely flexible, so that you can assemble and style your charts exactly as you need them. ```blade ``` ## Data structure Flux charts expect a structured array of data, typically provided via `wire:model` or passed as a `value` prop. Each data point should be an associative array with named fields: ```php '2026-01-01', 'visitors' => 267], ['date' => '2026-01-02', 'visitors' => 259], ['date' => '2026-01-03', 'visitors' => 269], // ... ]; } ``` If you've stored this data as a public property, you can use `wire:model` to bind the data to the chart: ```php ``` Otherwise, you can pass data in any form directly into the `:value` prop: ```php ``` For things like simple line charts with no axes, you can pass a single array of values as well: ```php ``` ## Examples ### Line chart To create a line chart, you can include the `` component in the `` component: ```blade ``` As you can see above, you can also render circular points on top of the line using the `` component. ### Area chart Similar to a line chart but with a filled area beneath the line. Great for showing cumulative values or emphasizing volume. ```blade ``` ### Multiple lines You can plot multiple lines in the same chart by including multiple `` components. This helps compare different data series against each other. ```blade
``` You might have noticed that the above example includes a `` component. This is used to constrain the chart SVG within the chart component so that you can render siblings like legends or summaries above or below it. ### Bar chart To create a bar chart, you can include the `` component in the `` component: ```blade ``` ```blade ``` ### Horizontal charts Add the `horizontal` prop to place the index on the Y axis and values on the X axis. Horizontal orientation works with bars, groups, stacks, lines, areas, points, cursors, and tooltips. When adding axes, put the category or time field on the Y axis and use the X axis for the numeric scale: ```blade ``` ### Grouped bar chart To create a grouped bar chart, you can wrap multiple `` components inside a single `` component: ```blade
``` ### Stacked bar chart To create a stacked bar chart, you can wrap multiple `` components inside a single `` component: ```blade
``` ### Pie chart To create a pie chart, include a single `` component in the `` component. Every row of data becomes a slice: `field` sets its size and `label-field` names it. A pie always draws a full circle, starting at 12 o'clock and moving clockwise. Hovering a slice shows the chart's tooltip. For a pie, a single `` row with a `label-field` reads best, and `` adds a dot in the hovered slice's color: ```blade ``` Pie data is one row per slice: ```php public array $data = [ ['id' => 'subscriptions', 'label' => 'Subscriptions', 'value' => 52], ['id' => 'services', 'label' => 'Services', 'value' => 28], ['id' => 'training', 'label' => 'Training', 'value' => 20], ]; ``` Rows whose value is `0`, `null`, or missing are left out of the circle. Negative or non-numeric values are left out as well, and log a warning in the console once. A pie can't share a chart with bars, lines, areas, points, axes, or a cursor, and a chart may only contain one ``. Invalid combinations log a warning and render nothing. ### Donut chart Add an `inner-radius` to turn a pie into a donut. It accepts a percentage of the outer radius or a pixel value. Use `radius` to round the corners of each slice: ```blade ``` Anything you place inside `` next to the SVG can fill the center of a donut. Position it absolutely and let pointer events pass through so the slices stay hoverable: ```blade
$128k Revenue
``` ### Slice colors Flux gives each slice a color from a built-in palette. Colors are tied to a slice's identity (its `id`, or its `label-field` value when there is no `id`), so reordering rows or removing one doesn't recolor the slices that remain. To pick a color yourself, add a `color` key to the row. Any of Flux's named colors work: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, and `rose`. ```php public array $data = [ ['id' => 'subscriptions', 'label' => 'Subscriptions', 'value' => 52, 'color' => 'blue'], ['id' => 'services', 'label' => 'Services', 'value' => 28, 'color' => 'emerald'], ['id' => 'training', 'label' => 'Training', 'value' => 20, 'color' => 'amber'], ]; ``` Legends are composed by hand, like every other Flux chart. The built-in palette isn't exposed to Blade, so when you show a legend, give each row an explicit `color` and mirror it in the legend indicators: ```blade
52%
28%
20%
``` Slices are separated by a stroke in the chart's surface color: white, or `zinc-900` in dark mode. If your chart sits on a different surface, like the card above, match it with a stroke class: ```blade ``` ### Hover styles Pie slices don't change appearance on hover by default. While a slice is hovered, it receives a `data-active` attribute and every other slice receives `data-inactive`. Use Tailwind's data attribute variants to choose a treatment that fits your chart: ```blade {{-- Dim the other slices... --}} {{-- Add a stronger border to the active slice... --}} {{-- Scale the active slice... --}} ``` The attributes are removed when the pointer leaves the pie. You can use either attribute independently or combine both in the same treatment. ### Live summary Flux charts support live summaries, which are updated as the user hovers over the chart. To enable this feature, you can include the `` component in the `` component: ```blade
Today
Yesterday
``` ### Sparkline A compact, single-line chart used in tables or dashboards for quick visual insights. Ideal for stock prices, memory usage, or other small-scale trends. ```blade ``` You might have noticed the `gutter` attribute on the `` component. This is because by default, the chart will be rendered with a padding of `8px` on all sides. This is to prevent overflowing contents of the chart (like tick labels or stroke lines) from being cut off at the edges of the container. For simple charts like a sparkline, you don't want that extra padding, so you can set the `gutter` to `0` to remove it. [Read more about the `gutter` prop ->](#chart-padding) ### Dashboard stat A small card displaying a key metric with an embedded chart in the background. Useful for KPIs like revenue, active users, or system health. ```blade Revenue $12,345 ``` ## Chart padding By default, the chart will be rendered with a padding of `8px` on all sides. This is to prevent overflowing contents of the chart (like tick labels or stroke lines) from being cut off at the edges of the container. You can control this by setting the `gutter` attribute on the `` component: Here's an example of adding the following padding to the chart: ```html ``` The `gutter` attribute accepts between one and four values, which correspond to the top, right, bottom, and left padding respectively. Similar to the padding property shorthand in CSS. The example above will result in the following padding: - **Top:** 12px - **Right:** 0px - **Bottom:** 12px - **Left:** 8px ## Axis scale You can configure the scale of an axis and its ticks by setting the `scale` attribute on the `` component: ```html ``` There are three available types of scales: - `categorical`: For categorical data like names or categories. - `linear`: For numeric data like stock prices or temperatures. - `time`: For date and time data The "y" axis is linear by default, but you can change it to a time axis by setting the `scale` attribute to `time`. The "x" axis will automatically use a time scale if the data is date or time values. Otherwise, it will use a categorical scale. ## Axis lines By default, axes do not include a visible baseline. You can add an axis line using `` inside the corresponding axis: ```html ``` **Styling axis lines** Because the axis line is rendered as a `` element, you can style it using any of the SVG attributes that are available for the `` element. ```css ``` ## Zero line The zero line is the line that represents the zero value on the axis. It will only be visible if the axis includes a negative value. ```html ``` **Styling the zero line** Because the zero line is rendered as a `` element, you can style it using any of the SVG attributes that are available for the `` element. ```css ``` ## Grid lines You can render horizontal and vertical grid lines by adding the `` component to the appropriate axis: ```html ``` **Styling grid lines** Because the grid lines are rendered as a `` element, you can style them using any of the SVG attributes that are available for the `` element. ```css ``` ## Ticks You can render tick mark lines and labels by adding the `` and/or `` components to the appropriate axis: ```html ``` **Styling tick mark lines** The tick mark component is a simple wrapper around the `` SVG element. You can customize the length, width, and color of the tick mark lines using plain CSS and SVG attributes: ```css ``` **Styling tick labels** The `` component is a simple wrapper around the `` SVG element. You can customize the font size, color, and position of the tick labels using plain CSS and SVG attributes: ```css ``` ### Tick frequency You can influence the number of ticks on an axis by setting the `tick-count` attribute: **Setting the tick count** ```html ``` Note that the `tick-count` attribute is only a target number, and the actual number of ticks may vary based on the range of values on the axis. **Setting the tick start** By default, the tick marks will start at zero, unless negative values are present. You can override this by setting the `tick-start` attribute: ```html ``` The available values for `tick-start` are: - `auto`: Automatically determine the starting tick value. - `min`: Start at the minimum value on the axis. - `0`: Start at zero. - `123`: Start at 123 (or any other number). **Setting the tick end** By default, the tick marks will end at the next tick mark after the maximum value on the axis. You can override this by setting the `tick-end` attribute: ```html ``` The available values for `tick-end` are: - `auto`: Automatically determine the ending tick value. - `max`: End at the maximum value on the axis. - `123`: End at 123 (or any other number). **Setting explicit tick values** You can also set explicit tick values by passing an array of values to the `tick-values` attribute: ```html ``` ### Tick formatting The tick labels can be formatted using the `format` attribute. Under-the-hood, the `format` attribute is passed to the `Intl.NumberFormat` constructor. This means that you can use any of the formatting options that are available for the `Intl.NumberFormat` constructor. [See the MDN documentation for more information on the formatting options ->](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) ```html ``` **Setting a tick prefix** You can set a tick prefix by passing a string to the `tick-prefix` attribute: ```html ``` **Setting a tick suffix** You can set a tick suffix by passing a string to the `tick-suffix` attribute: ```html ``` ## Cursor Adds a vertical guide when hovering over the chart to highlight values at specific points. Customizable with stroke styles, colors, and dash patterns. To enable a cursor, simply include `` inside ``: ```html ``` **Styling the cursor** Because the cursor is rendered as a `` element, you can style it using any of the SVG attributes that are available for the `` element. ```css ``` ## Tooltip Displays contextual data on hover. Supports multiple values and custom formatting for better readability. To enable tooltips, include `` inside ``: ```html ``` **Customizing tooltip content** You can display multiple values and format numbers dynamically. ```html ``` ## Legend Identifies multiple data series in the chart. Each legend item corresponds to a different dataset. When using a legend, you will need to include a `` component to wrap the `` component so that the legend is rendered outside of the chart: ```html
``` ## Summary Displays a single value from the dataset in a bold, easy-to-read format. Great for key performance indicators. To enable a summary, include `` inside ``: ```html ``` Notice that you will need to include a `` component to wrap the `` component so that the summary is rendered outside of the chart. **Setting a fallback value** You can set a fallback value by passing a string to the `fallback` attribute: ```html ``` This will be the value that is displayed if a data point is not being hovered over. ## Formatting You can customize how numbers and dates appear in your charts to make them more readable. Whether it's formatting currency, percentages, or large numbers, Flux charts let you easily control how values are displayed using the `:format` prop. Flux handles formatting for you behind the scenes using the `Intl.NumberFormat` and `Intl.DateTimeFormat` API, a built-in browser feature that ensures numbers and dates are displayed consistently based on locale and formatting rules. Just pass your desired format options to the `:format` prop, and Flux will apply them for you. ### Formatting numbers You can format numbers by passing an array of formatting options to the `:format` prop. ```html ``` **Commonly used formatting options** Here are some commonly used number formatting options you will likely need: | Description | Example Input | Example Output | Format Array | |---|---|---|---| | Currency (USD) | 1234.56 | $1,234.56 | `['style' => 'currency', 'currency' => 'USD']` | | Currency (EUR) | 1234.56 | €1,234.56 | `['style' => 'currency', 'currency' => 'EUR']` | | Percent | 0.85 | 85% | `['style' => 'percent']` | | Compact Number | 1000000 | 1M | `['notation' => 'compact']` | | Scientific | 123456789 | 1.235E8 | `['notation' => 'scientific']` | | Fixed Decimal | 3.1415926535 | 3.14 | `['maximumFractionDigits' => 2]` | | Thousands Separator | 1234567 | 1,234,567 | `['useGrouping' => true]` | | Custom Unit | 50 | 50 MB | `['style' => 'unit', 'unit' => 'megabyte']` | ### Formatting dates You can format dates by passing an array of formatting options to the `:format` prop. ```html ``` **Commonly used date formatting options** Here are some commonly used date formatting options you will likely need: | Description | Example Input | Example Output | Format Array | |---|---|---|---| | Full Date | 2024-03-15 | Friday, March 15, 2024 | `['dateStyle' => 'full']` | | Month and Day | 2024-03-15 | March 15 | `['month' => 'long', 'day' => 'numeric']` | | Short Month | 2024-03-15 | Mar 15 | `['month' => 'short', 'day' => 'numeric']` | | Time Only | 2024-03-15 14:30 | 2:30 PM | `['hour' => 'numeric', 'minute' => 'numeric', 'hour12' => true]` | | 24-hour Time | 2024-03-15 14:30 | 14:30 | `['hour' => '2-digit', 'minute' => '2-digit', 'hour12' => false]` | | Weekday | 2024-03-15 | Friday | `['weekday' => 'long']` | | Short Date | 2024-03-15 | 03/15/24 | `['month' => '2-digit', 'day' => '2-digit', 'year' => '2-digit']` | | Year Only | 2024-03-15 | 2024 | `['year' => 'numeric']` | ### Additional resources For more detailed information about formatting options, refer to: - [MDN Documentation on Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) - [MDN Documentation on Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) ## Reference ### flux:chart **Prop:** - `wire:model` - Binds the chart to a Livewire property containing the data to display. See the [wire:model documentation](https://livewire.laravel.com/docs/wire-model) for more information. - `value` - Array of data points for the chart. Each point should be an associative array with named fields. Used when not binding with `wire:model`. - `horizontal` - Places the chart's index on the Y axis and its values on the X axis. Useful for horizontal bars and other transposed chart layouts. **Slot:** - `default` - Chart components to render. Typically contains a `flux:chart.svg` component that defines the chart structure. **CSS:** - `class` - Additional CSS classes applied to the chart container. Common uses: `aspect-3/1` for aspect ratio, `h-64` for fixed height. **Attribute:** - `data-flux-chart` - Applied to the root element for styling and identification. ### flux:chart.svg Container for the chart's SVG elements. This component must be included within a `flux:chart` to render the chart. **Slot:** - `default` - Chart visualization components like lines, areas, axes, and interactive elements. ### flux:chart.line **Prop:** - `field` - Name of the data field to plot on the value axis. Required. - `curve` - Line curve type. Options: `smooth` (default), `none`. **CSS:** - `class` - Additional CSS classes applied to the line. Common use: `text-{color}` for line color. ### flux:chart.area **Prop:** - `field` - Name of the data field to plot on the value axis. Required. - `curve` - Area curve type. Options: `smooth` (default), `none`. **CSS:** - `class` - Additional CSS classes applied to the area. Common use: `fill-{color}/20` for fill color. ### flux:chart.point Adds points (dots) to mark data points on a line or area chart. **Prop:** - `field` - Name of the data field to plot points for. Required. **CSS:** - `class` - Additional CSS classes applied to the points. Common use: `fill-{color}` for point fill color, `r` attribute for point radius. ### flux:chart.pie Renders a pie or donut chart from one row per slice. Use one per chart, on its own, without other marks, axes, or a cursor. **Prop:** - `field` - Name of the numeric data field that sets each slice's size. Default: `value`. - `label-field` - Data field used as a slice's label and, when a row has no `id`, as its identity for stable colors. - `inner-radius` - Radius of the donut hole, as pixels or a percentage of the outer radius (e.g. `60%`). Default: `0`. - `radius` - Corner radius of each slice in pixels. Default: `0`. **CSS:** - `class` - Additional CSS classes applied to each slice. Common use: `stroke-{color}` to match the separator between slices to your surface. ### flux:chart.axis **Prop:** - `axis` - Axis to configure. Options: `x`, `y`. Required. - `field` - Data field to use for labels on the chart's index axis. - `format` - Date/number formatting options for axis labels. See [Formatting](#formatting) for more details. ### flux:chart.axis.mark Adds tick marks to the chart. Must be used within a `flux:chart.axis` component. **Prop:** - `position` - Position of the tick marks. Options: `top`, `bottom`, `left`, `right`. **CSS:** - `class` - Additional CSS classes applied to the tick marks. Common use: `text-{color}` for line color, `stroke-width="1"` for line thickness. ### flux:chart.axis.line Adds an axis line to the chart. Must be used within a `flux:chart.axis` component. **CSS:** - `class` - Additional CSS classes applied to the axis line. Common use: `text-{color}` for line color, `stroke-width="1"` for line thickness. ### flux:chart.axis.grid Adds gridlines to the chart. Must be used within a `flux:chart.axis` component. **CSS:** - `class` - Additional CSS classes applied to the gridlines. Common use: `text-{color}` for line color, `stroke-width="{width}"` for line thickness. ### flux:chart.axis.tick Adds tick marks and labels to an axis. Must be used within a `flux:chart.axis` component. **Prop:** - `format` - Date/number formatting options for tick labels. See [Formatting](#formatting) for more details. **CSS:** - `class` - Additional CSS classes applied to the tick marks and labels. Common use: `text-{color}` for label color, `font-{weight}` for label weight. ### flux:chart.zero-line Adds a line at zero on the value axis. It is horizontal for vertical charts and vertical for horizontal charts. **CSS:** - `class` - Additional CSS classes applied to the zero line. Common use: `text-{color}` for line color, `stroke-width="{width}"` for line thickness. ### flux:chart.tooltip **Prop:** - `field` - Data field to display in the tooltip. - `format` - Date/number formatting options for tooltip values. ### flux:chart.tooltip.heading **Prop:** - `field` - Data field to display in the tooltip heading. - `format` - Date/number formatting options for tooltip values. See [Formatting](#formatting) for more details. ### flux:chart.tooltip.value **Prop:** - `field` - Data field to display in the tooltip. - `format` - Date/number formatting options for tooltip values. See [Formatting](#formatting) for more details. - `label` - Static text shown before the value, such as a series name. - `label-field` - Data field to show as the label instead of static text. Useful for pie charts, where the label is the hovered slice's name. **Slot:** - `default` - Content rendered before the label, such as a `flux:chart.tooltip.indicator`. ### flux:chart.tooltip.indicator A small dot in the color of the hovered pie slice. Place it inside a `flux:chart.tooltip.value` row. Only pie charts set the hovered color. **CSS:** - `class` - Additional CSS classes applied to the indicator. ### flux:chart.cursor Adds an interactive cursor that follows mouse movement over the chart. Activates tooltips when present. **CSS:** - `class` - Additional CSS classes applied to the cursor line. ### flux:chart.summary Adds a summary section typically shown above the chart. Shows the latest values or values at cursor position. **Slot:** - `default` - Content to display in the summary section. Can include `flux:chart.value` components to display specific data values. ### flux:chart.summaryvalue Displays a specific data value, typically used within a `flux:chart.summary` component. **Prop:** - `field` - Data field to display. - `fallback` - Fallback text to display if the value is not found or cannot be formatted. - `format` - Date/number formatting options. See [Formatting](#formatting) for more details. ### flux:chart.legend **Prop:** - `field` - Data field this legend item represents. - `label` - Label text for the legend item. - `format` - Date/number formatting options. See [Formatting](#formatting) for more details. **Slot:** - `default` - Content to display in the legend. Can include arbitrary content, including `flux:chart.legend.indicator` components.