Results:
Loading...

React Data GridSparklines - Column CustomisationEnterprise

This section shows how Column Sparklines can be customised by overriding the default column options.

The following Column Sparkline Options can be used to customise Column Sparklines:

Also see Additional Customisations for more advanced customisations that are common across all sparklines.

The snippet below shows option overrides for the Column Sparkline:

sparklineOptions: {
    type: 'column',
    fill: '#91cc75',
    stroke: '#91cc75',
    highlightStyle: {
        fill: 'orange'
    },
    paddingInner: 0.3,
    paddingOuter: 0.1,
},

The following example demonstrates the results of the Column Sparkline options above:

Column Fill Options

To apply a custom color to the columns, set the fill property in sparklineOptions as shown:

sparklineOptions: {
    type: 'column',
    fill: '#91cc75', // sets the column fill
}
Column fill default
Default
Column fill customisation
Custom fill

It is possible to set the fill for the highlighted state of the column by adding fill in highlightStyle options as follows:

sparklineOptions: {
    type: 'column',
    highlightStyle: {
        fill: 'orange', // sets the highlighted column fill
    }
}
Highlighted Column fill default
Default highlighted fill
Highlighted Column fill customisation
Custom highlighted fill

The given fill string can be in one of the following formats:

  • #rgb - Short Hex Code
  • #rrggbb - Hex Code
  • rgb(r, g, b) - RGB
  • rgba(r, g, b, a) - RGB with an alpha channel
  • CSS color keyword - such as aqua, orange, etc.

Column Stroke Options

By default, the strokeWidth of each column is 0, so no outline is visible around the columns.

To add a stroke, modify the strokeWidth and stroke properties as shown below.

sparklineOptions: {
    type: 'column',
    stroke: '#ec7c7d', // sets the column stroke
    strokeWidth: 2, // sets the column stroke width
    highlightStyle: {
        stroke: '#b5ec7c', // sets the highlighted column stroke
        strokeWidth: 2, // sets the highlighted column stroke width
    }
}
  • In the snippet above, we have configured the column stroke to be 2px in the un-highlighted state, and 2px in the highlighted state.
  • Note that the stroke property is also different depending on the highlighted state of the column.

Here is the result of the configuration shown in the above snippet.

Stroke default
Default
Stroke customisation
Custom stroke
Stroke customisation for highlighted state
Custom highlighted stroke

If strokeWidth is set to a value greater than 1, it is recommended to set the axis line strokeWidth to the same value in order to preserve the alignment of the columns with the axis line.

Column Padding Options

The spacing between columns is adjustable via the paddingInner property. This property takes values between 0 and 1.

It is a proportion of the “step”, which is the interval between the start of a band and the start of the next band.

Here's an example.

sparklineOptions: {
    type: 'column',
    paddingInner: 0.5, // sets the padding between columns.
}
Column padding default
Default
PaddingInner customisation
Custom paddingInner

The padding on the outer edges of the first and last columns can also be adjusted. As with paddingInner, this value can be between 0 and 1.

If the value of paddingOuter is increased, the axis line will stick out more at both ends of the sparkline.

Here's a snippet where the paddingOuter is set to 0.

sparklineOptions: {
    type: 'column',
    paddingOuter: 0, // sets the padding on the outer edge of the first and last columns.
}

In this case there will be no gap on either end of the sparkline, i.e. between the axis line start and the first column and the axis line end and the last column. This is demonstrated below in the middle sparkline.

column padding default
Default
PaddingOuter customisation
No paddingOuter
PaddingOuter customisation
Increased paddingOuter

Column Label Options

To enable column labels, set the enabled property in label options as shown:

sparklineOptions: {
    type: 'column',
    label: {
        enabled: true // show column labels
    }
}
Column default
Default
Column labels enabled
Label enabled

It is possible to change the text value displayed as the label of individual columns by adding a formatter callback function to label options as follows:

sparklineOptions: {
    type: 'column',
    label: {
        enabled: true,
        formatter: labelFormatter
    }
}

function labelFormatter({ value }) {
    return `${value}%`
}
Column default
Default
Column label text customisation
Custom label text

To customise the label text style, set the style attributes in label options as follows:

sparklineOptions: {
    type: 'column',
    label: {
        enabled: true,
        fontWeight: 'bold',
        fontStyle: 'italic',
        fontSize: 9,
        fontFamily: 'Arial, Helvetica, sans-serif',
        color: 'black',
    }
}
Column default
Default
Column label text style customisation
Custom label text styles

The position of the labels can be specified by setting the placement property in label options. By default, the labels are positioned at the end of the columns on the inside, i.e. placement is set to insideEnd. The snippet below shows how the positioning of the label can be modified:

sparklineOptions: {
    type: 'column',
    label: {
        enabled: true,
        placement: 'center', // positions the labels in the center of the columns
    }
}

Label placement options include insideBase, center, insideEnd and outsideEnd. These are shown in the screenshots below.

Column label insideBase placement
insideBase
Column label center placement
center
Column label insideEnd placement
insideEnd
Column label placement default
outsideEnd

When configuring labels with placement:outsideEnd, it is recommended to add some padding to the sparkline using the padding options in order to prevent the labels from being clipped.

Axis Line Options

By default, an axis line is displayed which can be modified using the axis options.

Here is a snippet to demonstrate axis formatting.

sparklineOptions: {
    type: 'column',
    axis: {
        stroke: '#7cecb3', // sets the axis line stroke
        strokeWidth: 3, // sets the axis line strokeWidth
    },
}
Axis line default
Default axis line
Axis line customisation
Custom axis line

It's possible to remove the axis line entirely by setting the axis strokeWidth to 0.

Sparkline Padding Options

To add extra space around the sparklines, custom padding options can be applied in the following way.

sparklineOptions: {
    type: 'column',
    // sets the padding around the sparklines
    padding: {
        top: 10,
        right: 5,
        bottom: 10,
        left: 5
    },
}
  • The top, right, bottom and left properties are all optional and can be modified independently.
Padding customisation
Default padding
Padding customisation
Custom padding

Additional Customisations

More advanced customisations are discussed separately in the following sections:

  • Axis - configure the axis type via axis options.
  • Tooltips - configure tooltips using tooltip options.
  • Points of Interest - configure individual points of interest using a formatter.

Interfaces

ColumnSparklineOptions

Properties available on the ColumnSparklineOptions interface.

type
'column'
The type of sparklines to create, in this case it would be 'column'.
fill
string
The CSS colour value for the fill of the columns.
Default: 'rgb(124, 181, 236)'
stroke
string
The CSS colour value for the outline of the columns.
Default: 'silver'
strokeWidth
number
The thickness in pixels for the stroke of the columns.
Default: 0
paddingInner
number
The size of the gap between the columns as a proportion, between 0 and 1. This value is a fraction of the “step”, which is the interval between the start of a band and the start of the next band.
Default: 0.1
paddingOuter
number
The padding on the outside i.e. left and right of the first and last columns, to leave some room for the axis. In association with paddingInner, this value can be between 0 and 1.
Default: 0.2
valueAxisDomain
[number, number]
User override for the automatically determined domain (based on data min and max values). Only applied to number axes. Used to interpolate the numeric pixel values corresponding to each data value.
formatter
SparklineColumnFormatter
A callback function to return format styles of type ColumnFormat, based on the data represented by individual columns.
formatter: SparklineColumnFormatter;

type SparklineColumnFormatter = 
      (params: ColumnFormatterParams) => ColumnFormat


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

interface ColumnFormat {
  // The CSS colour value for the fill of the individual column. 
  fill?: string;
  // The CSS colour value for the outline of the individual column. 
  stroke?: string;
  // The thickness in pixels for the stroke of the individual column.
  strokeWidth?: number;
}
label
SparklineLabelOptions
Configuration for the labels. See SparklineLabelOptions.
label: SparklineLabelOptions;

interface SparklineLabelOptions {
  // Set to true to enable labels.
  // Default: `false`
  enabled?: boolean;
  // Set size of the font.
  // Default: `8`
  fontSize?: number;
  // Specify the font for the label text.
  // Default: `Verdana, sans-serif`
  fontFamily?: string;
  // Specify the font style for the label text. 
  fontStyle?: 'normal' | 'italic' | 'oblique';
  // Set how thick or thin characters in label text should be displayed. 
  fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
  // Set the color of the label text. The color can be specified by a color name, a HEX or an RGB value.
  // Default: `rgba(70, 70, 70, 1)`
  color?: string;
  // A callback function to return the text to be displayed as the label, based on the value represented by the column or bar.
  // By default the values are simply stringified. 
  formatter?: (params: LabelFormatterParams) => string;
  // Where to render labels relative to the segments.
  // Default: `insideEnd`
  // 
  placement?: BarColumnLabelPlacement;
}

interface LabelFormatterParams {
  // The Y value of the data point. 
  value: number | undefined;
}

enum BarColumnLabelPlacement {
  InsideBase = 'insideBase'
  InsideEnd = 'insideEnd'
  Center = 'center'
  OutsideEnd = 'outsideEnd'
}
xKey
string
The key to use to retrieve X values from the data. This will only be used if the data array contains objects with key-value pairs.
Default: 'x'
yKey
string
The key to use to retrieve Y values from the data. This will only be used if the data array contains objects with key-value pairs.
Default: 'y'
padding
PaddingOptions
Configuration for the padding in pixels shown around the sparklines.
padding: PaddingOptions;

interface PaddingOptions {
  // The number of pixels of padding at the top of the sparkline area.
  // Default: `3`
  top?: number;
  // The number of pixels of padding at the right of the sparkline area.
  // Default: `3`
  right?: number;
  // The number of pixels of padding at the bottom of the sparkline area.
  // Default: `3`
  bottom?: number;
  // The number of pixels of padding at the left of the sparkline area.
  // Default: `3`
  left?: number;
}
axis
SparklineAxisOptions
The options for the axis line in the sparklines. See SparklineAxisOptions.
axis: SparklineAxisOptions;

interface SparklineAxisOptions {
  // The type of axis used to plot the data.
  // Default: `'category'`
  type?: AxisType;
  // The CSS colour value for the outline of the axis line.
  // Default: `'rgb(204, 214, 235)'`
  stroke?: string;
  // The thickness in pixels for the stroke of the axis line.
  // Default: `1`
  strokeWidth?: number;
}

type AxisType = 
      'number' 
    | 'category' 
    | 'time'
highlightStyle
HighlightStyleOptions
The configuration for the highlighting used when the items are hovered over.
highlightStyle: HighlightStyleOptions;

interface HighlightStyleOptions {
  // The width in pixels of the markers when hovered over. This is only for the Line and Area sparklines as Column and Bar sparklines do not have markers.
  // Default: `6`
  size?: number;
  // The fill colour of the markers, columns or bars when hovered over. Use `undefined` for no highlight fill.
  // Default: `'yellow'`
  fill?: string;
  // The CSS colour value for the outline of the markers, columns or bars when hovered over. Use `undefined` for no highlight stroke.
  // Default: `'silver'`
  stroke?: string;
  // The thickness in pixels for the stroke of the markers, columns or bars when hovered over.
  // Default: `1`
  strokeWidth?: number;
}
tooltip
SparklineTooltipOptions
Configuration for the tooltips.
tooltip: SparklineTooltipOptions;

interface SparklineTooltipOptions {
  // Set to false to disable tooltips. 
  enabled?: boolean;
  // The element to place the tooltip into. This can be used to confine the tooltip to a specific area which may be outside of the sparkline grid cell. 
  container?: HTMLElement;
  // The horizontal distance in pixels between the cursor and the top left corner of the tooltip.
  // Default: `10`
  xOffset?: number;
  // The vertical distance in pixels between the cursor and the top left corner of the tooltip.
  // Default: `0`
  yOffset?: number;
  // A callback function used to create the content for the tooltips. This function should return an object or a HTML string used to render the tooltip. 
  renderer?: SparklineTooltipRenderer;
}

type SparklineTooltipRenderer = 
      (params: TooltipRendererParams) => TooltipRendererResult


interface TooltipRendererParams {
  // The grid context, includes row data, giving access to data from other columns in the same row. 
  context?: any;
  // The raw datum associated with the point. 
  datum: any;
  // The X value of the data point. 
  xValue: any;
  // The Y value of the data point. 
  yValue: any;
}

interface TooltipRendererResult {
  // Set to false to disable individual tooltip. 
  enabled?: boolean;
  // The content to display in each tooltip. 
  content?: string;
  // The title of the tooltip. 
  title?: string;
  // The CSS color for the title text. 
  color?: string;
  // The CSS color for the background of the tooltip title. 
  backgroundColor?: string;
  // The opacity of the background for the tooltip title. 
  opacity?: number;
}

SparklineAxisOptions

Properties available on the SparklineAxisOptions interface.

type
AxisType
The type of axis used to plot the data.
Default: 'category'
type: AxisType;

type AxisType = 
      'number' 
    | 'category' 
    | 'time'
stroke
string
The CSS colour value for the outline of the axis line.
Default: 'rgb(204, 214, 235)'
strokeWidth
number
The thickness in pixels for the stroke of the axis line.
Default: 1

SparklineLabelOptions

Properties available on the SparklineLabelOptions interface.

enabled
boolean
Set to true to enable labels.
Default: false
fontSize
number
Set size of the font.
Default: 8
fontFamily
string
Specify the font for the label text.
Default: Verdana, sans-serif
fontStyle
'normal' | 'italic' | 'oblique'
Specify the font style for the label text.
fontWeight
'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
Set how thick or thin characters in label text should be displayed.
color
string
Set the color of the label text. The color can be specified by a color name, a HEX or an RGB value.
Default: rgba(70, 70, 70, 1)
formatter
Function
A callback function to return the text to be displayed as the label, based on the value represented by the column or bar. By default the values are simply stringified.
formatter = (
    params: LabelFormatterParams
) => string;

interface LabelFormatterParams {
  // The Y value of the data point. 
  value: number | undefined;
}
placement
BarColumnLabelPlacement
Where to render labels relative to the segments.
Default: insideEnd
placement: BarColumnLabelPlacement;

enum BarColumnLabelPlacement {
  InsideBase = 'insideBase'
  InsideEnd = 'insideEnd'
  Center = 'center'
  OutsideEnd = 'outsideEnd'
}

Next Up

Continue to the next section to learn about: Line Sparkline Customisation.