@data-ui/sparkline

@data-ui/sparkline

A React + d3 library for creating sparklines 📈 implemented with vx.

npm install --save @data-ui/sparkline

Demo it live at williaster.github.io/data-ui.

Example usage

Sparklines are composable using the container <Sparkline /> component and different types of children including one or more <*Series /> components and reference lines or bands. Additionally, you can customize aesthetics using the exported <PatternLines /> and <LinearGradient/> components.

Note that the order of children passed to <Sparkline /> determines their rendering order, for example a <HorizontalReferenceLine /> passed after a <BarSeries /> will overlay the line on the bars.

import {
  Sparkline,
  LineSeries,
  HorizontalReferenceLine,
  BandLine,
  PatternLines,
  PointSeries } from '@data-ui/sparkline';
import { allColors } from '@data-ui/theme'; // open-color colors

const data = Array(25).fill().map(Math.random);

<Sparkline
      ariaLabel="A line graph of randomly-generated data"
      margin={{ top: 24, right: 64, bottom: 24, left: 64,}}
      width={500}
      height={100}
      data={data}
      valueAccessor={datum => datum}
    >
      {/* this creates a <defs> referenced for fill */}
      <PatternLines
        id="unique_pattern_id"
        height={6}
        width={6}
        stroke={allColors.grape[6]}
        strokeWidth={1}
        orientation={['diagonal']}
      />
      {/* display innerquartiles of the data */}
      <BandLine
        band="innerquartiles"
        fill="url(#unique_pattern_id)"
      />
      {/* display the median */}
      <HorizontalReferenceLine
        stroke={allColors.grape[8]}
        strokeWidth={1}
        strokeDasharray="4 4"
        reference="median"
      />
      {/* Series children are passed the data from the parent Sparkline */}
      <LineSeries
        showArea={false}
        stroke={allColors.grape[7]}
      />
      <PointSeries
        points={['min', 'max']}
        fill={allColors.grape[3]}
        size={5}
        stroke="#fff"
        renderLabel={val => val.toFixed(2)}
      />
    </Sparkline>

Components

Check out the example source code and PropTable tabs in the Storybook williaster.github.io/data-ui for more!

<Sparkline />

The Sparkline component renders an <svg /> and coordinates scales across all of it's child series and reference lines. It takes the following props:

Name	Type	Default	Description
ariaLabel	PropTypes.string.isRequired	-	Accessibility label for the svg
children	PropTypes.node.isRequired	-	Child series, reference lines, defs, or other valid svg children
className	PropTypes.string	-	Optional className to add to the svg
data	PropTypes.array	[]	an array of data that is shared across, items can be any shape or number
height	PropTypes.number.isRequired	-	Height of the svg including top/bottom margin
margin	PropTypes.shape({ top: PropTypes.number, right: PropTypes.number, bottom: PropTypes.number, left: PropTypes.number })	{ top: 16, right: 16, bottom: 16, left: 16 }	chart margin, leave room for labels! note 0 may clip LineSeries and PointSeries. a partial { top/right/bottom/ left } object is filled with the other default values
max	PropTypes.number	-	Optionally set the maximum y-value of the chart (e.g., to coordinate axes across multiple Sparklines)
min	PropTypes.number	-	Optionally set the minimum y-value of the chart (e.g., to coordinate axes across multiple Sparklines)
onMouseMove	PropTypes.func	-	func({ data, datum, event, index, color }), passed to an invisible BarSeries that intercepts all mouse events (can pass to individual series for more control)
onMouseLeave	PropTypes.func	-	func(), passed to an invisible BarSeries that intercepts all mouse events
styles	PropTypes.object	-	Optional styles to apply to the svg
width	PropTypes.number.isRequired	-	Width of the svg including left/right margin
valueAccessor	PropTypes.func	d => d	Optional accessor function that takes an item from the data array as input and returns the y value of the datum. This value is passed back in e.g., renderLabel functions.

Series

The following series components are available, they are passed the data and scales from the parent Sparkline component, and you may compose multiple to create the sparkline you want 😍:

• <LineSeries />
• <PointSeries />
• <BarSeries />

<PointSeries /> and <BarSeries /> support labeling of specific data points.

<LineSeries />

This component can be used to create lines and or area sparklines with various curve types, and takes the following props:

Name	Type	Default	Description
fill	PropTypes.string	@data-ui/themes color.default	If showArea=true, this sets the fill of the area path.
fillOpacity	PropTypes.number	0.3	If showArea=true, this sets the fillOpacity of the area shape.
curve	PropTypes.oneOf(['linear', 'cardinal', 'basis', 'monotoneX'])	'cardinal'	The type of curve interpolator to use.
onMouseMove	PropTypes.func	-	func({ data, datum, event, index, color }) called on line mouse move for the closest datum
onMouseLeave	PropTypes.func	-	func() called on line mouse leave
showArea	PropTypes.bool	false	Boolean indicating whether to render an Area path.
showLine	PropTypes.bool	true	Boolean indicating whether to render a Line path.
stroke	PropTypes.string	@data-ui/themes color.default	If showLine=true, this sets the stroke of the line path.
strokeDasharray	PropTypes.string	-	If showLine=true, this sets the strokeDasharray attribute of the line path.
strokeLinecap	PropTypes.oneOf(['butt', 'square', 'round', 'inherit'])	'round'	If showLine=true, this sets the strokeLinecap attribute of the line path.
strokeWidth	PropTypes.number	2	If showLine=true, this sets the strokeWidth attribute of the line path.

<BarSeries />

This component can be used to bar-graph sparklines and takes the following props:

Name	Type	Default	Description
fill	PropTypes.oneOfType([PropTypes.func, PropTypes.string])	@data-ui/themes color.default	A single fill to use for all Bars or a function with the following signature (yVal, i) => fill called for each data point. If data objects have a fill property, it overrides this value.
fillOpacity	PropTypes.oneOfType([PropTypes.func, PropTypes.number])	0.7	A single fillOpacity value (0 - 1) to use for all Bars or a function with the following signature (yVal, i) => opacity called for each data point. If data objects have a fillOpacity property, it overrides this value.
LabelComponent	PropTypes.element	@data-ui/sparkline's <Label /> component	Component to use for labels, if relevant. This component is cloned with appropriate x, y, dx, and dy values for positioning.
labelOffset	PropTypes.number	8	(Absolute) pixel offset to use for positioning a label relative to a Bar. labelPosition is used to determine direction.
labelPosition	PropTypes.oneOfType([PropTypes.func, PropTypes.oneOf(['top', 'right', 'bottom', 'left']), ])	'top'	A single string indicating how to position a label relative to the top point of a bar, or a function with the following signature (yVal, i) => position called for each data point. If the return value is not one of top, right, bottom, left, it is spread on the LabelComponent directly (e.g., { dx: -100, dy: 100 })
onMouseMove	PropTypes.func	-	func({ data, datum, event, index, color }) called on bar mouse move
onMouseLeave	PropTypes.func	-	func() called on bar mouse leave
renderLabel	PropTypes.func	-	Optional function called for each datum, with the following signature (yVal, i) => node. If this is passed to the Series and returns a value, a label will be rendered for the passed point. This is used as the child of LabelComponent so any valid child of svg <text> elements can be returned.
stroke	PropTypes.oneOfType([PropTypes.func, PropTypes.string])	white	A single stroke to use for all Bars or a function with the following signature (yVal, i) => stroke. If data objects have a stroke property, it overrides this value.
strokeWidth	PropTypes.oneOfType([PropTypes.func, PropTypes.number])	1	A single strokeWidth to use for all Bars or a function with the following signature (yVal, i) => stroke. If data objects have a strokeWidth property, it overrides this value.

<PointSeries />

This component can be used to render all or a subset of points for a sparkline and takes the following props:

Name	Type	Default	Description
fill	PropTypes.oneOfType([PropTypes.func, PropTypes.string])	@data-ui/themes color.default	A single fill to use for all Points or a function with the following signature (yVal, i) => fill called for each data point. If data objects have a fill property, it overrides this value.
fillOpacity	PropTypes.oneOfType([PropTypes.func, PropTypes.number])	1	A single fillOpacity value (0 - 1) to use for all Points or a function with the following signature (yVal, i) => opacity called for each data point. If data objects have a fillOpacity property, it overrides this value.
LabelComponent	PropTypes.element	@data-ui/sparkline's <Label /> component	Component to use for labels, if relevant. This component is cloned with appropriate x, y, dx, and dy values for positioning.
labelOffset	PropTypes.number	12	(Absolute) pixel offset to use for positioning a label relative to a Point. labelPosition is used to determine direction.
labelPosition	PropTypes.oneOfType([PropTypes.func, PropTypes.oneOf(['auto', 'top', 'right', 'bottom', 'left']), ])	'auto'	A single string indicating how to position a label relative to the center of a point, or a function with the following signature (yVal, i) => position called for each data point. 'auto' attempts to position the label on top or bottom of a point depending on the surrounding data points. If the return value is not one of auto, top, right, bottom, left, it is spread on the LabelComponent directly (e.g., { dx: -100, dy: 100 })
onMouseMove	PropTypes.func	-	func({ data, datum, event, index, color }) called on point mouse move
onMouseLeave	PropTypes.func	-	func() called on point mouse leave
points	PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.oneOf(['all', 'min', 'max', 'first', 'last']), ]))	['min', 'max']	String(s) or index(s) indicating which point(s) to render. e.g., If all, all points are rendered, if ['min', 'max'], only the minimum and maximum points are rendered.
size	PropTypes.oneOfType([PropTypes.func, PropTypes.number])	3	A single size to use as the radius of all Pointss or a function with the following signature (yVal, i) => size called for each data point. If data objects have a size property, it overrides this value.
renderLabel	PropTypes.func	-	Optional function called for each datum, with the following signature (yVal, i) => node. If this is passed to the Series and returns a value, a label will be rendered for the passed point. This is used as the child of LabelComponent so any valid child of svg <text> elements can be returned.
stroke	PropTypes.oneOfType([PropTypes.func, PropTypes.string])	white	A single stroke to use for all Points or a function with the following signature (yVal, i) => stroke. If data objects have a stroke property, it overrides this value.
strokeWidth	PropTypes.oneOfType([PropTypes.func, PropTypes.number])	1	A single strokeWidth to use for all Points or a function with the following signature (yVal, i) => stroke. If data objects have a strokeWidth property, it overrides this value.

Tooltips

You can add tooltips to <Sparkline /> components by wrapping them with the higher-order <WithTooltip /> component. This component accepts a renderTooltip function whose output is rendered into a boundary-aware (html-based) tooltip. <WithTooltip /> handles tooltip visibility state and passes onMouseMove onMouseLeave and tooltipData props to its child. If these are passed to <Sparkline />, it will render a series of invisible Bars to intercept mouse events. If they are passed to individual series, mouse events will be handled on the series level.

See the storybook for example usage!

Name	Type	Default	Description
children	PropTypes.func or PropTypes.object	-	Child function (to call) or element (to clone) with onMouseMove, onMouseLeave, and tooltipData props/keys
className	PropTypes.string	-	Class name to add to the <div> container wrapper
renderTooltip	PropTypes.func.isRequired	-	Renders the contents of the tooltip, signature of ({ event, data, datum, color }) => node. If this function returns a falsy value, a tooltip will not be rendered.
styles	PropTypes.object	{}	Styles to add to the <div> container wrapper
TooltipComponent	PropTypes.func or PropTypes.object	@vx's TooltipWithBounds	Component (not instance) to use as the tooltip container component. It is passed top and left numbers for positioning
tooltipProps	PropTypes.object	-	Props that are passed to TooltipComponent
tooltipTimeout	PropTypes.number	200	Timeout in ms for the tooltip to hide upon calling onMouseLeave

Reference lines and bands

The following reference line components are exported to support different types of annotations you may want:

• <HorizontalReferenceLine />
• <VerticalReferenceLine />
• <BandLine />.

<HorizontalReferenceLine />

This component can be used to render a single horizontal reference line to call out a point of interest. It takes the following props:

Name	Type	Default	Description
reference	PropTypes.oneOfType([PropTypes.number, PropTypes.oneOf(['mean', 'median', 'min', 'max'] ]))	mean	What reference to create a line for. This may be a raw number to call out, or one of 'mean', 'median', 'min', 'max' which will compute the relevant y value.
LabelComponent	PropTypes.element	@data-ui/sparkline's <Label /> component	Component to use for labels, if relevant. This component is cloned with appropriate x, y, dx, and dy values for positioning.
labelOffset	PropTypes.number	8	(Absolute) pixel offset to use for positioning a label relative to a Point. labelPosition is used to determine direction.
labelPosition	PropTypes.oneOf(['top', 'right', 'bottom', 'left'])	'right'	A single string indicating how to position a label relative to the end of a reference line
renderLabel	PropTypes.func	-	Optional function called for each datum, with the following signature (yVal) => node. If this is passed and returns a value, a label will be rendered. This is used as the child of LabelComponent so any valid child of svg <text> elements can be returned.
stroke	PropTypes.string	@data-ui/themes color.default	Sets the stroke of the line path.
strokeDasharray	PropTypes.string	-	Sets the strokeDasharray attribute of the line path.
strokeLinecap	PropTypes.oneOf(['butt', 'square', 'round', 'inherit'])	'round'	Sets the strokeLinecap attribute of the line path.
strokeWidth	PropTypes.number	2	Sets the strokeWidth attribute of the line path.

<VerticalReferenceLine />

@TODO picture

This component can be used to render a single vertical reference line to call out a point of interest. It takes the following props:

Name	Type	Default	Description
reference	PropTypes.oneOfType([PropTypes.number, PropTypes.oneOf(['first', 'last', 'min', 'max'] ]))	last	What reference to create a line for. This may be a raw number (x index) to call out, or one of 'first', 'last', 'min', 'max' which will compute the relevant x index value.
LabelComponent	PropTypes.element	@data-ui/sparkline's <Label /> component	Component to use for labels, if relevant. This component is cloned with appropriate x, y, dx, and dy values for positioning.
labelOffset	PropTypes.number	10	(Absolute) pixel offset to use for positioning a label relative to a Point. labelPosition is used to determine direction.
labelPosition	PropTypes.oneOf(['top', 'right', 'bottom', 'left'])	'top'	A single string indicating how to position a label relative to the top of a reference line
renderLabel	PropTypes.func	-	Optional function called for each datum, with the following signature (xVal) => node. If this is passed and returns a value, a label will be rendered. This is used as the child of LabelComponent so any valid child of svg <text> elements can be returned.
stroke	PropTypes.string	@data-ui/themes color.default	Sets the stroke of the line path.
strokeDasharray	PropTypes.string	-	Sets the strokeDasharray attribute of the line path.
strokeLinecap	PropTypes.oneOf(['butt', 'square', 'round', 'inherit'])	'round'	Sets the strokeLinecap attribute of the line path.
strokeWidth	PropTypes.number	2	Sets the strokeWidth attribute of the line path.

<BandLine />

This component can be used to render ranges of interest as opposed to single values. It may be used to create vertical or horizontal bands and takes the following props:

Name	Type	Default	Description
band	PropTypes.oneOfType([PropTypes.oneOf([ 'innerQuartiles' ]), PropTypes.shape({ from: PropTypes.shape({ x: PropTypes.number, y: PropTypes.number }).isRequired, to: PropTypes.shape({ x: PropTypes.number, y: PropTypes.number }) ]).isRequired })	'innerQuartiles'	Specifies the band to render. May be innerQuartiles which computes the midspread of the data values, or an object with the keys { from: coords, to: coords } specifying a custom band. If an x or y value is missing in either the from or to key, the bounds (min, max) of the chart are used.
fill	PropTypes.string	@data-ui/themes color.lightGray	Sets the fill of the bar shape.
fillOpacity	PropTypes.number	0.5	Sets the fillOpacity of the bar shape.
stroke	PropTypes.string	transparent	Sets the stroke of the bar shape.
strokeWidth	PropTypes.number	0	Sets the strokeWidth of the bar shape.

<PatternLines /> and <LinearGradient/>s

These components are exported for convenience from @vx to support customization of the aesthetics of your sparklines. They create <defs/> elements with the specified id, which are then referenced for fills or strokes in other components via url(#my_id). See example usage above and the Storybook for examples!

They take the following props:

<PatternLines />

Name	Type	Default	Description
id	PropTypes.string.isRequired	-	id for the <defs> that is created. When used as a fill in another component it can be referenced via url(#my_id).
width	PropTypes.number.isRequired	-	Width of the pattern (which is then repeated).
height	PropTypes.number.isRequired	-	Height of the pattern (which is then repeated).
stroke	PropTypes.string	-	Sets the stroke attribute of the pattern line.
strokeWidth	PropTypes.number	-	Sets the strokeWidth attribute of the pattern line.
strokeDasharray	PropTypes.string	-	Sets the strokeDasharray attribute of the pattern line.
strokeLinecap	PropTypes.string	'square'	Sets the strokeLinecap attribute of the pattern line.
shapeRendering	PropTypes.string	'auto'	Sets the shapeRendering attribute of the pattern line.
orientation	PropTypes.arrayOf(PropTypes.oneOf(['vertical', 'horizontal', 'diagonal']))	['vertical']	Array of orientations for lines. If multiple are passed, one path is rendered for each.
background	PropTypes.string	-	Optional background fill for the pattern.
className	PropTypes.string	-	Optional className added to the pattern path's.

<LinearGradient />

Name	Type	Default	Description
id	PropTypes.string.isRequired	-	id for the <defs> that is created. When used as a fill in another component it can be referenced via url(#my_id).
from	PropTypes.string	-	String used for the start color in the gradient.
to	PropTypes.string	-	String used for the end color in the gradient.
fromOffset	PropTypes.string	0%	Sets the offset (as a %) of the from color.
fromOpacity	PropTypes.number	1	Sets the opacity of the from color.
toOffset	PropTypes.string	100%	Sets the offset (as a %) of the to color
toOpacity	PropTypes.number	1	Sets the opacity of the to color.
rotate	PropTypes.oneOfType([PropTypes.string, PropTypes.number])	-	Sets the transform attribute of the gradient to rotate(<rotate>)
transform	PropTypes.string	-	Sets the gradientTransform of the linearGradient element, overridden by rotate