@data-ui/sparkline

React + d3 library for creating sparklines

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
45725Feb 14, 2020Apr 11, 2017Minified + gzip package size for @data-ui/sparkline in KB

Readme

@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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.