# AstrolChart

> AstrolChart: Blazor charts from AstrolUI based on ApexCharts. Lines, areas, bars, circular, radar, heatmaps, ranges, candlesticks and more, with C# data and the AstrolUI light/dark theme.

Source page: https://doc.astrolui.com/chart/chart-component

**AstrolChart<TItem>** is the chart container, and one or more **series** go inside it. Each series receives a list of your own objects (**Items**) and functions that say which value goes on each axis. No arrays or JSON to prepare: you work with your own classes and LINQ.

## 1. Minimal example

## 2. How data is connected

- **TItem**: the class of your data. It goes on the chart and on each series (**TItem="Sale"**).
- **Items**: the list of objects of the series. For several series from one list, filter with LINQ: **Items="sales.Where(s => s.Year == 2026)"**.
- **XValue**: what goes on the X axis (category, number or date). Objects with the same X make a single point.
- **YValue**: the Y value of each object, when there is one object per point.
- **YAggregate**: when there are several objects per point, how they are combined: **e => e.Sum(x => x.Amount)**, **Average**, **Count()**, **Max**...
- **OrderBy / OrderByDescending**: order of the points, e.g. **OrderByDescending="p => p.Y"** for a ranking.
- **Name**: series name (legend and tooltip). **Color** sets its color; **PointColor** gives a color per point.
- **ShowDataLabels**: shows the value on each point or bar.
- **Group**: in stacked bars, series with the same Group form one stack.
- **DataPointMutator**: changes each point before it is drawn (color, extra text...).
- **Dates**: set **XAxisType="XAxisType.Datetime"** on the chart and pass the date as Unix milliseconds: **XValue="e => e.Date.ToUnixTimeMilliseconds()"**.
- **Numeric axes** (scatter): **XAxisType="XAxisType.Numeric"** and a numeric XValue.
- If the list content changes (without creating another list), call **UpdateSeriesAsync()** through **@ref**; if you assign a new list, the chart updates by itself.

## 3. Series types

- **AstrolPointSeries**: one value per point (**YValue** or **YAggregate**). Its **SeriesType** chooses the drawing:
**Line**, **Area**, **Bar** (columns; horizontal with **PlotOptions.Bar.Horizontal**), **Pie**, **Donut**, **PolarArea**, **RadialBar**, **Radar**, **Scatter**, **Heatmap** and **Treemap**.
Types can be combined in one chart (columns + line).

- **AstrolRangeSeries**: bars from a start to an end (**YMinValue**, **YMaxValue**): Gantt charts and timelines.
- **AstrolRangeAreaSeries**: band between **Bottom** and **Top** (minimum and maximum).
- **AstrolCandleSeries**: candlesticks with **Open**, **High**, **Low** and **Close**.
- **AstrolBoxPlotSeries**: box plots with **Min**, **Quantile1**, **Median**, **Quantile3** and **Max**.
- **AstrolBubbleSeries**: bubbles with **YAggregate** (position) and **ZAggregate** (size).
- **AstrolGauge**: a single-percentage indicator without defining series: **Title**, **Label**, **Percentage** (0-100) and **Options**.
- All series share **Items**, **Name**, **XValue**, **Color**, **PointColor**, **ShowDataLabels**, **Stroke** (**SeriesStroke**: Color, Width, DashSpace) and **Group**.

## 4. Options (AstrolChartOptions)

The whole look is configured with **Options** (**AstrolChartOptions<TItem>**). Its properties follow the [ApexCharts options documentation](https://apexcharts.com/docs/options/) exactly, with C# names: **Chart** (stacked, zoom, toolbar, animations), **Colors**, **Stroke** (width and curve), **Fill**, **Markers**, **DataLabels**, **Legend**, **Tooltip**, **Xaxis**, **Yaxis** (several axes), **Grid**, **PlotOptions** (per type: Bar, Pie, RadialBar, Heatmap, Treemap...), **Annotations**, **Theme** and **Responsive**. Create the options once (a field), not on every render.

```csharp
private readonly AstrolChartOptions<Sale> options = new()
{
    Chart = new Chart { Stacked = true, Toolbar = new Toolbar { Show = false } },
    Colors = new List<string> { "#ffd800", "#007bff" },
    Stroke = new Stroke { Curve = Curve.Smooth, Width = 3 },
    DataLabels = new DataLabels { Enabled = true },
    Legend = new Legend { Position = LegendPosition.Bottom },
    PlotOptions = new PlotOptions { Bar = new PlotOptionsBar { Horizontal = true, BorderRadius = 4 } },
    Xaxis = new XAxis { Title = new AxisTitle { Text = "Month" } },
    Yaxis = new List<YAxis> { new YAxis { Title = new AxisTitle { Text = "Amount" } } },
    Tooltip = new Tooltip { Shared = true, Intersect = false },
};

// <AstrolChart TItem="Sale" Options="options"> ... </AstrolChart>
```

## 5. Theme, colors and performance

- Texts, axes and tooltips follow the AstrolUI light/dark mode automatically.
- Colors: **Options.Colors** (a list, one per series or slice), **Color** on each series, **PointColor** per point or an ApexCharts palette with **Options.Theme = new Theme { Palette = PaletteType.Palette3 }**.
- Size: by default it takes the container width; set the height with **Height** (e.g. **Height="@(300)"** or **Height="@("50vh")"**).
- ApexCharts is downloaded only once and only on pages with charts. With many points, aggregate the data (YAggregate or on the server) instead of sending thousands of objects.
- **FormatXAxisLabel** and **FormatYAxisLabel** (C# functions for the labels) only work in Blazor WebAssembly; in Blazor Server use **Options.Xaxis.Labels.Formatter** (a JavaScript function as text).

### Supported parameters

**AstrolChart<TItem>**:

- TItem **(T)**, data class **(required)**.
- ChildContent **(RenderFragment)**, the series. If you use **AstrolPointTooltip**, put the series inside **<ChildContent>**.
- Title **(string)**, chart title.
- Options **(AstrolChartOptions<TItem>)**, look and behavior (see section 4).
- XAxisType **(XAxisType?)**, X axis type: **Category**, **Datetime** or **Numeric**.
- Width / Height **(object)**, size (number in px or CSS text).
- AstrolPointTooltip **(RenderFragment<HoverData<TItem>>)**, tooltip with Blazor content; **context.DataPoint.Items** are the objects of the point.
- FormatXAxisLabel / FormatYAxisLabel **(Func<decimal, string>)**, axis labels with C# (WebAssembly only).
- GroupPoints **(GroupPoints)**, groups small points into one ("Other"): **MaxCount**, **MinCount**, **PercentageThreshold**, **Name**.
- Debug **(bool)**, logs the ApexCharts calls to the console.
- Data events: **OnDataPointSelection**, **OnMarkerClick**, **OnClick** (**SelectedData<TItem>**: Series, DataPoint, IsSelected, indexes), **OnDataPointEnter** / **OnDataPointLeave** (**HoverData<TItem>**), **OnLegendClicked**, **OnXAxisLabelClick**, **OnMouseMove**, **OnMouseLeave**.
- Zoom and selection events: **OnZoomed**, **OnSelection**, **OnBrushScrolled**, **OnScrolled**, **OnBeforeZoom**, **OnBeforeResetZoom**.
- Lifecycle events: **OnBeforeMount**, **OnMounted**, **OnRendered**, **OnUpdated**, **OnAnimationEnd**.
- Annotation events: **OnAnnotationLabelClick**, **OnAnnotationLabelMouseEnter/Leave**, **OnAnnotationPointClick**, **OnAnnotationPointMouseEnter/Leave**.

### Public methods

With **@ref** (**private AstrolChart<Sale>? chart;**):

- **UpdateSeriesAsync(animate)**: reads the series again (after changing the data).
- **UpdateOptionsAsync(redrawPaths, animate, updateSyncedCharts)**: applies changes in **Options**.
- **RenderAsync()**: creates the whole chart again.
- **AppendDataAsync(items)**: adds points at the end (real-time data).
- **ToggleSeriesAsync / ShowSeriesAsync / HideSeriesAsync(name)**: shows or hides a series.
- **ToggleDataPointSelectionAsync(series, point)**: selects a point from code.
- **ZoomXAsync(start, end)** and **ResetSeriesAsync(update, resetZoom)**.
- **AddPointAnnotationAsync**, **AddXAxisAnnotationAsync**, **AddYAxisAnnotationAsync**, **RemoveAnnotationAsync(id)**, **ClearAnnotationsAsync()**.
- **GetDataUriAsync(new DataUriOptions { Scale, Width })**: PNG image of the chart (data URI).
- **SetLocaleAsync(name)**: changes the chart language (defined in **Options.Chart.Locales**).

### Examples