JavaScript Data GridSparklines - Points of Interest

Enterprise

This section covers customisation of Sparkline Points of Interest.

Some data points in the sparklines are special and can be emphasised to allow for quick identification and comparisons across the values of a single sparkline or across multiple sparklines of the same type. These include:

  • First and Last
  • Minimum and Maximum
  • Positive and Negative
Line sparkline

First and last

Area sparkline

Minimum and Maximum

Column sparkline

Negative and positive

These special points can be customised via the formatter callback function to make them stand out from the rest of the data points which are using the global styles.

  • The formatter is a callback function used to return formatting for individual data points based on the given parameters.
  • The formatter receives an input parameter according to the sparkline type.

Below are some examples demonstrating the different formatters for the three sparkline types:

Line and Area Sparklines Points of Interest

In the line and area sparklines, each data point is represented by a marker. To customise the points of interest, the formatter function is added to the marker options:

sparklineOptions: {
    marker: {
        formatter: markerFormatter, // add formatter to marker options
    },
}

The formatter callback function will receive an input parameter of type markerFormatterParams.

The function return type should be MarkerFormat, allowing the following attributes to be customised:

  • size
  • fill
  • stroke
  • strokeWidth

The following sections outline how the attributes mentioned above can be customised for various special points of interest:

First and Last

Let's say we have a line sparkline where the markers are all 'skyblue' but we want to make the first and last markers stand out with a purple fill and stroke style.

We can do this by adding the following formatter to the marker options.

const markerFormatter = (params) => {
    const { first, last } = params;

    return {
        size: first || last ? 5 : 3,
        fill: first || last ? '#9a60b4' : 'skyblue',
        stroke: first || last ? '#9a60b4' : 'skyblue'
    }
}
  • In the snippet above, first and last boolean values are extracted from the params object and used to conditionally set the size, fill and stroke of the markers.
  • If the given data point is the first or last point i.e. if first or last is true, the size of the marker is set to 5px. All other markers will be 3px.
  • Similar conditional logic is applied to colorise the markers to distinguish the first and last points from the rest.

See the result of adding this formatter in the sparklines on the right below, compared with the ones on the left which are using global styles in marker options:

Global styles

Global marker styles

Area first and last marker customisation

Formatted first and last points

Global styles

Global marker styles

Line first and last marker customisation

Formatted first and last points

Min and Max

Similar to first and last, to emphasise the min and max data points, the min and max booleans from the formatter params can be used to conditionally style the markers.

const markerFormatter = (params) => {
    const { min, max } = params;

    return {
        size: min || max ? 5 : 3,
        fill: min ? '#ee6666' : max ? '#3ba272' : 'skyBlue',
        stroke: min ? '#ee6666' : max ? '#3ba272' : 'skyBlue',
    }
}
  • If the data point is a minimum or a maximum point – if min or max is true – the size is set to 5px, otherwise it is set to3px.
  • If the marker represents a minimum point, the fill and stroke are set to red, if the marker represents a maximum point, the fill and stroke are set to green. Otherwise the fill and stroke are set to sky blue.

See the result of adding this formatter in the sparklines on the right below, compared with the ones on the left which are using global styles in marker options:

Global styles

Global marker styles

Area min and max marker customisation

Formatted min and max points

Global styles

Global marker styles

Line min and max marker customisation

Formatted min and max points

Positive and Negative

The positive and negative values can be distinguished by adding a formatter which returns styles based on the yValue of the data point.

This is demonstrated in the snippet below.

const markerFormatter = (params) => {
    const { yValue } = params;

    return {
        // if yValue is negative, the marker should be 'red', otherwise it should be 'green'
        fill: yValue < 0 ? 'red' : 'green',
        stroke: yValue < 0 ? 'red' : 'green'
    }
}

See the result of adding this formatter in the sparklines on the right below, compared with the ones on the left which are using global styles in marker options:

Global styles

Global marker styles

Area positive and negative marker customisation

Formatted positive and negative points

Global styles

Global marker styles

Line positive and negative marker customisation

Formatted positive and negative points

Column And Bar Sparklines Points of Interest

Bar sparklines are just transposed column sparklines and have the same configuration. This section only covers column sparkline examples but the same applies for bar sparklines.

In the column sparklines, each data point is represented by a rectangle/ column. The formatter callback function applies to the individual columns and is added to sparklineOptions:

sparklineOptions: {
    type: 'column',
    formatter: columnFormatter, // add formatter to sparklineOptions
}

The formatter will receive an input parameter with values associated with the data point it represents. The input parameter type is columnFormatterParams.

The function return type should be ColumnFormat, allowing these attributes to be customised:

  • fill
  • stroke
  • strokeWidth

The following sections outline how the attributes mentioned above can be customised for various special points of interest:

First and Last

Let's say we want to make the first and last columns in our column sparklines stand out by styling them differently to the rest of the columns.

We can do this by adding the following formatter to the sparklineOptions.

const columnFormatter = (params) => {
    const { first, last } = params;

    return {
        fill: first || last ? '#ea7ccc' : 'skyblue',
        stroke: first || last ? '#ea7ccc' : 'skyblue'
    }
}

Here is the result of adding this formatter compared with setting global styles in sparklineOptions:

Global styles

Global column styles

Column first and last customisation

Formatted first and last points

Min and Max

Similar to first and last, to emphasise the min and max data points, the min and max booleans from the formatter params can be used to conditionally style the markers.

const columnFormatter = (params) => {
    const { min, max } = params;

    return {
        fill: min ? '#ee6666' : max ? '#3ba272' : 'skyBlue',
        stroke: min ? '#ee6666' : max ? '#3ba272' : 'skyBlue',
    }
}

Here is the result of adding this formatter compared with setting global styles in sparklineOptions:

Global styles

Global column styles

Column minimum and maximum customisation

Formatted minimum and maximum points

Positive and Negative

The positive and negative values can be distinguished by adding a formatter which returns styles based on the yValue of the data point.

This is demonstrated in the snippet below.

const columnFormatter = (params) => {
    const { yValue } = params;

    return {
        // if yValue is negative, the column should be dark red, otherwise it should be purple
        fill: yValue < 0 ? '#a90000' : '#5470c6',
        stroke: yValue < 0 ? '#a90000' : '#5470c6'
    }
}

Here is the result of adding this formatter compared with setting global styles in sparklineOptions:

Global styles

Global column styles

Column positive and negative customisation

Formatted positive and negative points

Example: Points of Interest

The example below shows formatting of special points for line, area and column sparklines.

It should be noted that

  • The highlighted property on the params object is used to distinguish between highlighted and un-highlighted states.
  • The formatter for line and area sparklines is added to the marker options
  • The size property is returned from the area and line formatters to make certain special markers visible and the rest invisible.

All formatters will receive the highlighted property in the input. If the current data point 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 when customising the special points.

Interfaces

MarkerFormatterParams

Properties available on the MarkerFormatterParams interface.

datum
any
The raw data associated with the specific marker.
xValue
any
The X value of the data point.
yValue
any
The Y value of the data point.
min
boolean
Whether or not the marker is a minimum point.
max
boolean
Whether or not the marker is a maximum point.
first
boolean
Whether or not the marker represents the first data point.
last
boolean
Whether or not the marker represents the last data point.
fill
string
The CSS colour value for the fill of the individual marker.
stroke
string
The CSS colour value for the outline of the individual marker.
strokeWidth
number
The thickness in pixels for the stroke of the individual marker.
size
number
The width in pixels of the individual marker.
highlighted
boolean
Whether or not the marker is highlighted.

MarkerFormat

Properties available on the MarkerFormat interface.

enabled
boolean
Set to false to make marker invisible.
size
number
The width in pixels of the individual marker.
fill
string
The CSS colour value for the fill of the individual marker.
stroke
string
The CSS colour value for the outline of the individual marker.
strokeWidth
number
The thickness in pixels for the stroke of the individual marker.

ColumnFormatterParams

Properties available on the ColumnFormatterParams interface.

datum
any
The raw data associated with the specific column.
xValue
any
The X value of the data point.
yValue
any
The Y value of the data point.
width
number
The width of the column in pixels.
height
number
The height of the column in pixels.
min
boolean
Whether or not the column is a minimum point.
max
boolean
Whether or not the column is a maximum point.
first
boolean
Whether or not the column represents the first data point.
last
boolean
Whether or not the column represents the last data point.
fill
string
The CSS colour value for the fill of the individual column.
stroke
string
The CSS colour value for the outline of the individual column.
strokeWidth
number
The thickness in pixels for the stroke of the individual column.
highlighted
boolean
Whether or not the column is highlighted.

ColumnFormat

Properties available on the ColumnFormat interface.

fill
string
The CSS colour value for the fill of the individual column.
stroke
string
The CSS colour value for the outline of the individual column.
strokeWidth
number
The thickness in pixels for the stroke of the individual column.