Area series are line series with the area under the line filled, placing more emphasis on the magnitude of the change. Area series additionally support stacking to show the total value and the way individual values relate to the whole.
Single Area Series
To create a simple area chart we need to use series type 'area'. We also have to provide the xKey and yKey properties. A minimal 'area' series config would therefore look like this:
series: [{
type: 'area',
xKey: 'year',
yKey: 'ie',
}]
In the snippet above we are using 'ie' as the yKey to show market share of this internet browser. Using this simple series config produces the following chart:
Even though area series support markers, they are turned off by default for this series type, as this stylisation is the most common.
To enable area markers, all we need to do is add this to the series config:
series: [{
...
marker: {
enabled: true
}
}]
Tooltips will be shown on hover, which in this case show percentage values without a % suffix.
The series are designed to work with all kinds of data and are unaware of the nature of the values. So we additionally provide a tooltipRenderer to add the % suffix. After this change, the tooltips will change like so:
The final result can be seen in the example below.
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: {
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 Area Series
It is possible to use more than one 'area' series in a single chart. For example, if we want one series to show the magnitude of change in market share of Internet Explorer and the other series the change in market share of Chrome, we could use the following series config:
series: [
{
type: 'area',
xKey: 'year',
yKey: 'ie'
},
{
type: 'area',
xKey: 'year',
yKey: 'chrome'
}
]
Since multiple area series can overlap, it is a good idea to make the fill translucent, for example using fillOpacity: 0.7.
Note that in the example below we also:
- Use
yName to control the text that the legend displays
- Enable
markers
- Define custom
fill and stroke
- Make the fill translucent using the
fillOpacity config
Stacked Area Series
The stacked: true property controls series stacking behaviour. For example, to have a stacked area chart that shows changes in market share for the most popular internet browsers we could use a config like this:
series: [
{ type: 'area', xKey: 'year', yKey: 'ie', stacked: true },
{ type: 'area', xKey: 'year', yKey: 'firefox', stacked: true },
{ type: 'area', xKey: 'year', yKey: 'safari', stacked: true },
{ type: 'area', xKey: 'year', yKey: 'chrome', stacked: true }
]
This produces the following chart:
Normalized Area Series
Following on from our stacked area series example, if we want to normalize the totals so that for any given year stack levels always added up to a certain value, for example 100%, we could add the following to our series config:
It's possible to use any non-zero value to normalize to.
Missing Data
Sometimes data for certain items or time periods might be missing.
The chart handles such cases based on whether the xKey or yKey value of a data point is invalid.
The yKey value of a data point is invalid if it’s +/-Infinity, null, undefined or NaN. A data point with an invalid yKey value will be rendered as a gap in the series.
The xKey value of a data point is invalid if it’s a number, object, +/-Infinity, null, undefined or NaN. The chart handles this depending on the X-axis type:
- For continuous X axes (either a
'time' or 'number' axis), the data point will be skipped altogether.
- For category X axes the data point will not be skipped. It will be rendered as a category along the X axis.
The following example demonstrates how missing data is handled for a continuous X-axis type (time axis) in Area Series:
- Initially there is no missing data, all values are valid for their associated axes.
- Click the Missing Y values button and note that missing Y values are rendered as gaps in the area chart.
- Click the Missing X values button and note that missing X values causes no data point to be displayed (hence fewer data points shown in the area chart).
- The second row of buttons allow switching between stacked and grouped area series.
API Reference
Properties available on the AgAreaSeriesOptions<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. |
| 'area' | 'area' |
| AgAreaSeriesMarker<DatumType> | Configuration for the markers used in the series. marker: AgAreaSeriesMarker<DatumType>;
interface AgAreaSeriesMarker<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
|
| number | The number to normalise the area stacks to. For example, if normalizedTo is set to 100, the stacks will all be scaled proportionally so that their total height is always 100. |
| 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. |
| CssColor | The colour to use for the fill of the area. fill: CssColor;
type CssColor = string
|
| CssColor | The colours to use for the stroke of the areas. stroke: CssColor;
type CssColor = string
|
| PixelSize | The width in pixels of the stroke for the areas. Default: 1 strokeWidth: PixelSize;
type PixelSize = number
|
| Opacity | The opacity of the fill for the area. Default: 1 fillOpacity: Opacity;
type Opacity = number
|
| Opacity | The opacity of the stroke for the areas. Default: 1 strokeOpacity: Opacity;
type Opacity = number
|
| PixelSize[] | Defines how the area strokes are 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
|
| shadow
AgDropShadowOptions | Configuration for the shadow used behind the chart series. shadow: AgDropShadowOptions;
interface AgDropShadowOptions {
// Whether or not the shadow is visible.
enabled?: boolean;
// The colour of the shadow.
color?: CssColor;
// The horizontal offset in pixels for the shadow.
xOffset?: PixelSize;
// The vertical offset in pixels for the shadow.
yOffset?: PixelSize;
// The radius of the shadow's blur, given in pixels.
blur?: PixelSize;
}
type CssColor = string
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
|
| AgAreaSeriesTooltip | Series-specific tooltip configuration. tooltip: AgAreaSeriesTooltip;
interface AgAreaSeriesTooltip {
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;
}
|
| boolean | boolean |
| 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. |
| 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;
}
|
| 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. Default: 'nearest' nodeClickRange: AgChartInteractionRange;
type AgChartInteractionRange =
PixelSize
| 'exact'
| 'nearest'
type PixelSize = number
|
