The Line series is a good choice when you need to spot a trend, render large amounts of data or create a real-time chart. Line series is also the preferred choice for rendering continuous data with irregular intervals or incomplete data that has some values missing.
Single Series
Since the 'line' series type is so common, it doesn't have to be specified explicitly. The chart factory method, AgChart.create, uses it as the default type.
The simplest line series config therefore only requires two properties, xKey and yKey:
series: [{
xKey: 'year',
yKey: 'spending'
}]
The chart expects the data (chart.data property) to be an array of objects, where each object is a table row or a database record and each key is a column.
To plot anything on a plane, we need at least two coordinates: x and y. The xKey and yKey series configs tell the series which keys should be used to fetch the values of these coordinates from each object in the data array.
Showing labels on top of data points is also an option with the label config. Labels can be enabled independently of series markers.
For example, to show bold labels on top of each data point (and in this case a marker) we would use the following config:
series: [{
...
label: {
enabled: true,
fontWeight: 'bold'
}
}]
The above config is used in the example below. Feel free to open it in Pluker and experiment with other label options.
Multiple Series
If we have more than two fields inside each object in the data array, we can create a multi-series line chart. For example, if a datum looks like this:
{
quarter: 'Q1',
petrol: 200,
diesel: 100
}
We can use the same quarter key as xKey for both series and petrol and diesel keys for yKey of the first and second line series, respectively.
To create multiple line series we need to provide two config objects in the series array:
series: [
{
xKey: 'quarter',
yKey: 'petrol'
},
{
xKey: 'quarter',
yKey: 'diesel'
}
]
And we get a result like this:
By default the legend shows the keys used to fetch the series data, but those may not be very presentable. In our case, the petrol and diesel keys inside the data objects are not capitalised. We can provide a better display name using the yName config, and the legend will show that instead.
series: [
{
xKey: 'quarter',
yKey: 'petrol',
yName: 'Petrol'
},
{
xKey: 'quarter',
yKey: 'diesel',
yName: 'Diesel'
}
]
The provided yName will also show up in tooltip titles:
Line and Marker Colours
The chart above is not complicated, but it could still benefit from more visual separation. Let's make the diesel series look more like diesel. Just add the following two configs to the second series:
stroke: 'black',
marker: {
fill: 'gray',
stroke: 'black'
}
We'll get a result like this:
There are many other customisations you can make to the markers; see the markers section for more information.
Missing Data
In a perfect world all data would be 100% complete. Unfortunately, in the real one, data for certain items or time periods might be missing or corrupted. But that shouldn't result in corrupted charts, and AG Charts supports the correct rendering of incomplete data:
If the yKey value of a data point is positive or negative Infinity, null, undefined or NaN, that data point will be rendered as a gap.
If the bottom axis is also continuous (for example, if it's a 'number' axis too), rather than being rendered as a gap, invalid xKey values from the data will be skipped all together.
Continuous Data
By default, the bottom axis is a 'category' axis, but this can be changed if you have continuous data that you would like to plot. See the axes section for more information on configuring axes.
Time-Series Data
The following example shows how line series can be used to render time-series data, using a 'time' axis. In this case, we have two ambient temperature sensors that give us two independent data sets, with different numbers of readings taken at different times:
Because we have two separate data sets, we are using the series.data property of each series, rather than the data property of the chart itself:
series: [
{
data: [
{
time: new Date('01 Jan 2020 13:25:30 GMT'),
sensor: 25
},
{
time: new Date('01 Jan 2020 13:26:30 GMT'),
sensor: 24
}
],
...
},
{
data: [
{
time: Date.parse('01 Jan 2020 13:25:00 GMT'),
sensor: 21
},
{
time: Date.parse('01 Jan 2020 13:26:00 GMT'),
sensor: 22
}
],
...
}
]
Notice that even though one data set has dates as Date objects and another uses timestamps, it doesn't present a problem and both series render just fine.
The time axis automatically selects an appropriate label format depending on the time span of the data, making a best-effort attempt to prevent the labels from overlapping.
Real-Time Data
The chart will update whenever new data is supplied via the chart's or series' data property.
This example uses the 'time' axis which is configured to show a tick every 5 seconds and to use the %H:%M:%S label format to show colon separated hours, minutes and seconds.
API Reference
Properties available on the AgLineSeriesOptions<DatumType = any> interface.
| string | The key to use to retrieve x-values from the data. |
| string | The key to use to retrieve y-values from the data. |
| 'line' | 'line' |
| AgCartesianSeriesMarker<DatumType> | AgCartesianSeriesMarker marker: AgCartesianSeriesMarker<DatumType>;
interface AgCartesianSeriesMarker<DatumType> {
// Function used to return formatting for individual markers, based on the supplied information. If the current marker is highlighted, the `highlighted` property will be set to `true`; make sure to check this if you want to differentiate between the highlighted and un-highlighted states.
formatter?: AgCartesianSeriesMarkerFormatter<DatumType>;
// Whether or not to show markers.
enabled?: boolean;
// The shape to use for the markers. You can also supply a custom marker by providing a `Marker` subclass.
shape?: MarkerShape;
// The size in pixels of the markers.
size?: PixelSize;
// For series where the size of the marker is determined by the data, this determines the largest size a marker can be in pixels.
maxSize?: PixelSize;
// The colour to use for marker fills. If this is not specified, the markers will take their fill from the series.
fill?: CssColor;
// Opacity of the marker fills.
fillOpacity?: Opacity;
// The colour to use for marker strokes. If this is not specified, the markers will take their stroke from the series.
stroke?: CssColor;
// The width in pixels of the marker stroke. If this is not specified, the markers will take their stroke width from the series.
strokeWidth?: PixelSize;
// Opacity of the marker strokes.
strokeOpacity?: Opacity;
}
type AgCartesianSeriesMarkerFormatter =
(params: AgCartesianSeriesMarkerFormatterParams<DatumType>) => AgCartesianSeriesMarkerFormat
| undefined
interface AgCartesianSeriesMarkerFormatterParams<DatumType> {
xKey: string;
yKey: string;
datum: DatumType;
fill?: CssColor;
stroke?: CssColor;
strokeWidth: PixelSize;
size: number;
highlighted: boolean;
seriesId: string;
}
type CssColor = string
type PixelSize = number
interface AgCartesianSeriesMarkerFormat {
fill?: CssColor;
stroke?: CssColor;
strokeWidth?: PixelSize;
size?: PixelSize;
}
type MarkerShape =
'circle'
| 'cross'
| 'diamond'
| 'heart'
| 'plus'
| 'triangle'
| any
type Opacity = number
|
| string | A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters. |
| string | A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters. |
| string | The title to use for the series. Defaults to yName if it exists, or yKey if not. |
| CssColor | The colour of the stroke for the lines. Default: '#aa4520' stroke: CssColor;
type CssColor = string
|
| PixelSize | The width in pixels of the stroke for the lines. Default: 1 strokeWidth: PixelSize;
type PixelSize = number
|
| Opacity | The opacity of the stroke for the lines. Default: 1 strokeOpacity: Opacity;
type Opacity = number
|
| PixelSize[] | Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, [6, 3] means dashes with a length of 6 pixels with gaps between of 3 pixels. lineDash: PixelSize[];
type PixelSize = number
|
| PixelSize | The initial offset of the dashed line in pixels. Default: 0 lineDashOffset: PixelSize;
type PixelSize = number
|
| AgCartesianSeriesLabelOptions | Configuration for the labels shown on top of data points. label: AgCartesianSeriesLabelOptions;
interface AgCartesianSeriesLabelOptions {
// Function used to turn 'yKey' values into text to be displayed by a label. By default the values are simply stringified.
formatter?: (params: AgCartesianSeriesLabelFormatterParams) => string;
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
interface AgCartesianSeriesLabelFormatterParams {
// The ID of the series.
seriesId: string;
// The value of yKey as specified on series options.
value: number;
}
type FontStyle =
'normal'
| 'italic'
| 'oblique'
type FontWeight =
'normal'
| 'bold'
| 'bolder'
| 'lighter'
| '100'
| '200'
| '300'
| '400'
| '500'
| '600'
| '700'
| '800'
| '900'
type FontSize = number
type FontFamily = string
type CssColor = string
|
| AgLineSeriesTooltip | Series-specific tooltip configuration. tooltip: AgLineSeriesTooltip;
interface AgLineSeriesTooltip {
// Function used to create the content for tooltips.
renderer?: (params: AgCartesianSeriesTooltipRendererParams) => string | AgTooltipRendererResult;
format?: string;
// Whether or not to show tooltips when the series are hovered over.
enabled?: boolean;
// The position of the tooltip. By default the tooltip follows the mouse pointer.
position?: AgTooltipPositionOptions;
// Configuration for tooltip interaction.
interaction?: AgSeriesTooltipInteraction;
}
interface AgCartesianSeriesTooltipRendererParams {
// xKey as specified on series options.
xKey: string;
// xValue as read from series data via the xKey property.
xValue?: any;
// xName as specified on series options.
xName?: string;
// yKey as specified on series options.
yKey: string;
// yValue as read from series data via the yKey property.
yValue?: any;
// yName as specified on series options.
yName?: string;
// Datum from the series data array that the tooltip is being rendered for.
datum: any;
// Series title or yName depending on series configuration.
title?: string;
// Series primary colour, as selected from the active theme, series options or formatter.
color?: CssColor;
// The ID of the series.
seriesId: string;
}
type CssColor = string
interface AgTooltipRendererResult {
// Title text for the tooltip header.
title?: string;
// Content text for the tooltip body.
content?: string;
// Tooltip title text color.
color?: string;
// Tooltip title background color.
backgroundColor?: string;
}
type AgTooltipPositionOptions =
AgMovingTooltipPositionOptions
interface AgMovingTooltipPositionOptions {
// The type of positioning for the tooltip. By default, the tooltip follows the pointer.
type: AgTooltipPositionType;
// The horizontal offset in pixels for the position of the tooltip.
xOffset?: PixelSize;
// The vertical offset in pixels for the position of the tooltip.
yOffset?: PixelSize;
}
type AgTooltipPositionType = 'pointer' | 'node'
type PixelSize = number
interface AgSeriesTooltipInteraction {
// Set to true to keep the tooltip open when the mouse is hovering over it, and enable clicking tooltip text
enabled: boolean;
}
|
| AgSeriesListeners<DatumType> | A map of event names to event listeners. listeners: AgSeriesListeners<DatumType>;
interface AgSeriesListeners<DatumType> {
// The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked.
nodeClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
// The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is double clicked.
nodeDoubleClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
}
interface AgSeriesNodeClickParams<DatumType> {
// Event type.
type: 'nodeClick';
// Series ID, as specified in series.id (or generated if not specified)
seriesId: string;
// Datum from the series data array.
datum: DatumType;
// xKey as specified on series options
xKey?: string;
// yKey as specified on series options
yKey?: string;
// sizeKey as specified on series options
sizeKey?: string;
// labelKey as specified on series options
labelKey?: string;
// colorKey as specified on series options
colorKey?: string;
// angleKey as specified on series options
angleKey?: string;
// calloutLabelKey as specified on series options
calloutLabelKey?: string;
// sectorLabelKey as specified on series options
sectorLabelKey?: string;
// radiusKey as specified on series options
radiusKey?: string;
}
|
| string | Primary identifier for the series. This is provided as seriesId in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique id value.
Default: auto-generated value
|
| DatumType[] | The data to use when rendering the series. If this is not supplied, data must be set on the chart instead. |
| boolean | Whether or not to display the series. |
| boolean | Whether or not to include the series in the legend. |
| string | The cursor to use for hovered area markers. This config is identical to the CSS cursor property. |
| AgSeriesHighlightStyle | Configuration for series markers and series line highlighting when a marker / data point or a legend item is hovered over. highlightStyle: AgSeriesHighlightStyle;
interface AgSeriesHighlightStyle {
// Highlight style used for an individual marker when tapped or hovered over.
item?: AgSeriesHighlightMarkerStyle;
// Highlight style used for whole series when one of its markers is tapped or hovered over.
series?: AgSeriesHighlightSeriesStyle;
}
interface AgSeriesHighlightMarkerStyle {
// The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
fill?: CssColor;
// The opacity of the fill for the highlighted item.
fillOpacity?: Opacity;
// The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
stroke?: CssColor;
// The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
type CssColor = string
type Opacity = number
type PixelSize = number
interface AgSeriesHighlightSeriesStyle {
enabled?: boolean;
// The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming.
dimOpacity?: Opacity;
// The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
|
| AgChartInteractionRange | Range from a node a click triggers the listener. nodeClickRange: AgChartInteractionRange;
type AgChartInteractionRange =
PixelSize
| 'exact'
| 'nearest'
type PixelSize = number
|
