This section shows how Bar Sparklines can be customised by overriding the default bar options.
The following Bar Sparkline Options can be used to customise Bar Sparklines:
- Bar Fill Options
- Bar Stroke Options
- Bar Padding Options
- Bar Label Options
- Axis Line Options
- Sparkline Padding Options
Also see Additional Customisations for more advanced customisations that are common across all sparklines.
The snippet below shows option overrides for the Bar Sparkline:
sparklineOptions: {
type: 'bar',
// Optional customisation properties
fill: '#5470c6',
stroke: '#91cc75',
highlightStyle: {
fill: '#fac858'
},
valueAxisDomain: [0, 1]
},
In the snippet above, the valueAxisDomain
property is optional.
valueAxisDomain
is used to specify the interval within which the data values lie. These boundaries are used to create a scale which will be used to map data values from 0px
to the size of the sparkline.
If the valueAxisDomain
property is ommitted, the domain will be set to the minmum and maximum values in the provided data, hence it could be different for different sparklines in the grid depending on the provided data.
The following example demonstrates the results of the Bar Sparkline options above:
- Note that
valueAxisDomain
has been set to[0, 1]
, indicating that the supplied data across all sparklines will contain values from0
to1
. This allows easy comparisons across the different sparklines in the grid column as all sparklines will have the same domain.
Bar Fill Options
To apply a custom color to the bars, set the fill
property in sparklineOptions
as shown:
sparklineOptions: {
type: 'bar',
fill: '#91cc75', // sets the bar fill
}
It is possible to set the fill for the highlighted state of the bar by adding fill
in highlightStyle
options as follows:
sparklineOptions: {
type: 'bar',
highlightStyle: {
fill: 'orange', // sets the highlighted bar fill
}
}
The given fill
string can be in one of the following formats:
#rgb
- Short Hex Code#rrggbb
- Hex Codergb(r, g, b)
- RGBrgba(r, g, b, a)
- RGB with an alpha channel- CSS color keyword - such as
aqua
,orange
, etc.
Bar Stroke Options
By default, the strokeWidth
of each bar is 0
, so no outline is visible around the bars.
To add a stroke, modify the strokeWidth
and stroke
properties as shown below.
sparklineOptions: {
type: 'bar',
stroke: '#ec7c7d', // sets the bar stroke
strokeWidth: 2, // sets the bar stroke width
highlightStyle: {
stroke: '#b5ec7c', // sets the highlighted bar stroke
strokeWidth: 2, // sets the highlighted bar stroke width
}
}
- In the snippet above, we have configured the bar stroke to be
2
px in the un-highlighted state, and2
px in the highlighted state. - Note that the
stroke
property is also different depending on the highlighted state of the bar.
Here is the result of the configuration shown in the above snippet.
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 bars with the axis line.
Bar Padding Options
The spacing between bars 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: 'bar',
paddingInner: 0.5, // sets the padding between bars.
}
The padding on the outer edges of the first and last bars 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: 'bar',
paddingOuter: 0, // sets the padding on the outer edge of the first and last bars.
}
In this case there will be no gap on either end of the sparkline, i.e. between the axis line start and the first bar and the axis line end and the last bar. This is demonstrated below in the middle sparkline.
Bar Label Options
To enable bar labels, set the enabled
property in label
options as shown:
sparklineOptions: {
type: 'bar',
label: {
enabled: true // show bar labels
}
}
It is possible to change the text value displayed as the label of individual bars by adding a formatter
callback function to label
options as follows:
sparklineOptions: {
type: 'bar',
label: {
enabled: true,
formatter: labelFormatter
}
}
function labelFormatter({ value }) {
return `${value}%`
}
To customise the label text style, set the style attributes in label
options as follows:
sparklineOptions: {
type: 'bar',
label: {
enabled: true,
fontWeight: 'bold',
fontStyle: 'italic',
fontSize: 9,
fontFamily: 'Arial, Helvetica, sans-serif',
color: 'black',
}
}
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 bars 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: 'bar',
label: {
enabled: true,
placement: 'center', // positions the labels in the center of the bars
}
}
Label placement
options include insideBase
, center
, insideEnd
and outsideEnd
. These are shown in the screenshots below.
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: 'bar',
axis: {
stroke: '#7cecb3', // sets the axis line stroke
strokeWidth: 3, // sets the axis line strokeWidth
},
}
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: 'bar',
// sets the padding around the sparklines
padding: {
top: 10,
right: 5,
bottom: 10,
left: 5
},
}
- The
top
,right
,bottom
andleft
properties are all optional and can be modified independently.
Building Progress Bars
A progress bar can be used to visualise and compare values across multiple sparklines in the grid. It can illustrate values which have a fixed domain such as percentages and scores.
The following example shows how to build progress bars using bar sparklines. Note that:
- In order to display a progress bar in a sparkline, the data array should only contain a single value, more values in the data array will produce additional bars in the same sparkline.
valueAxisDomain
has been set to[0, 100]
, indicating that the supplied data across all sparklines will contain values from0
to100
.- This allows easy comparisons of percentages across the different sparklines in the grid column as all sparklines will have the same domain.
- The
formatter
callback function is used to dynamically set the fill color of each progress bar to different color values based on the datayValue
. - Percentage Y values are displayed on the inside end of each bar by configuring
label
options. - The axis line and padding are removed to allow more space in each cell for the progress bar.
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
BarSparklineOptions
Properties available on the BarSparklineOptions
interface.
The type of sparklines to create, in this case it would be 'bar' . |
The CSS colour value for the fill of the bars. |
The CSS colour value for the outline of the bars. Default 'silver'
|
The thickness in pixels for the stroke of the bars. |
The size of the gap between the bars 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. |
The padding on the outside i.e. left and right of the first and last bars, to leave some room for the axis. In association with paddingInner , this value can be between 0 and 1. |
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.
|
A callback function to return format styles of type BarFormat, based on the data represented by individual bars. |
Configuration for the labels. |
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. |
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. |
Configuration for the padding in pixels shown around the sparklines. |
The options for the axis line in the sparklines. |
The configuration for the highlighting used when the items are hovered over. |
Configuration for the tooltips. |
SparklineAxisOptions
Properties available on the SparklineAxisOptions
interface.
The type of axis used to plot the data. |
The CSS colour value for the outline of the axis line. |
The thickness in pixels for the stroke of the axis line. |
SparklineLabelOptions
Properties available on the SparklineLabelOptions
interface.
Set to true to enable labels. |
Set size of the font. |
Specify the font for the label text. |
Specify the font style for the label text. |
Set how thick or thin characters in label text should be displayed. |
Set the color of the label text. The color can be specified by a color name, a HEX or an RGB value. |
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. |
Where to render labels relative to the segments. |
Next Up
Continue to the next section to learn about: Column Sparkline Customisation.