replot-bar v0.4.1

replot-bar: Bar graphs for react

Intelligent and customizable bar graph components for react.

Installation

Only works with React projects. React must be installed separately.

npm install replot-bar

Then with a module bundler like webpack/browserify that supports CommonJS/ES2015 modules, use as you would anything else.

import BarGraph from 'replot-bar'

API

replot-bar is designed to create beautiful bar graphs right out of the box. The only required input is properly formatted data.

Basic Usage

In the simplest case, just supply data (as a Javascript array) and specify the keys associated with the values:

render() {
  let populations = [
    {country: "Github", year: 2017, population: 2400000},
    {country: "Netherlands", year: 2017, population: 1703500},
    {country: "Israel", year: 2017, population: 832100},
    {country: "New Zealand", year: 2017, population: 470500},
    {country: "Iceland", year: 2017, population: 33500}
  ]

  return(
    <BarGraph data={populations}
      	xKey="country"
      	yKey="population"
    />
  )
}

• data is the only required prop
• xKey defaults to "x"
• yKey defaults to "y"

Grouped Bar Graph

You can supply the data as an array of JSON objects.

render() {
  let populations = [
    {country: "Github", year: 2015, population: 1100000},
    {country: "Github", year: 2016, population: 1600000},
    {country: "Github", year: 2017, population: 2400000},
    {country: "Netherlands", year: 2015, population: 1692500},
    {country: "Netherlands", year: 2016, population: 1698700},
    {country: "Netherlands", year: 2017, population: 1703500},
    {country: "Israel", year: 2015, population: 806400},
    {country: "Israel", year: 2016, population: 819100},
    {country: "Israel", year: 2017, population: 832100},
    {country: "New Zealand", year: 2015, population: 452900},
    {country: "New Zealand", year: 2016, population: 466000},
    {country: "New Zealand", year: 2017, population: 470500},
    {country: "Iceland", year: 2015, population: 32900},
    {country: "Iceland", year: 2016, population: 33200},
    {country: "Iceland", year: 2017, population: 33500}
  ]

  return(
    <BarGraph data={populations}
      	xKey="year"
      	yKey="population"
      	groupKey="country"
    />
  )
}

• groupKey defaults to "group"

Dimensions

Dimensions may be specified by passing in width and height props with numbers in the unit of pixels.

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	width={600}
      	height={450}
    />
  )
}

• width defaults to 800
• height defaults to 600

Width dimensions may also be specified with a string, as a percentage. The width will then be calculated as a proportion of the parent container.

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
        width="50%"
        height={450}
    />
  )
}

Default	width={600} height={450}	width="50%" height={450}

Error Bars

Error bars may be displayed by passing in errorBarMinKey and errorBarMaxKey props with the keys associated with the error ranges.

render() {
  let estimates = [
    {country: "Github", year: 2015, population: 1100000, max: 1200000, min: 1000000},
    {country: "Github", year: 2016, population: 1600000, max: 1700000, min: 1500000},
    {country: "Github", year: 2017, population: 2400000, max: 2500000, min: 2300000},
    {country: "Netherlands", year: 2015, population: 1692500, max: 1800000, min: 1600000},
    {country: "Netherlands", year: 2016, population: 1698700, max: 1800000, min: 1600000},
    {country: "Netherlands", year: 2017, population: 1703500, max: 1800000, min: 1600000},
    {country: "Israel", year: 2015, population: 806400, max: 900000, min: 700000},
    {country: "Israel", year: 2016, population: 819100, max: 900000, min: 700000},
    {country: "Israel", year: 2017, population: 832100, max: 900000, min: 700000},
    {country: "New Zealand", year: 2015, population: 452900, max: 550000, min: 450000},
    {country: "New Zealand", year: 2016, population: 466000, max: 550000, min: 450000},
    {country: "New Zealand", year: 2017, population: 470500, max: 550000, min: 450000},
    {country: "Iceland", year: 2015, population: 32900, max: 35000, min: 32000},
    {country: "Iceland", year: 2016, population: 33200, max: 35000, min: 32000},
    {country: "Iceland", year: 2017, population: 33500, max: 35000, min: 32000}
  ]

  return(
    <BarGraph data={estimates} xKey="year" yKey="population" groupKey="country"
      	errorBarMaxKey="max"
	errorBarMinKey="min"
    />
  )
}

• errorBarMaxKey is unspecified by default
• errorBarMinKey is unspecified by default

Color of error bars may also be specified by passing in errorBarColor prop with a color string.

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	errorBarMaxKey="max"
	errorBarMinKey="min"
	errorBarColor="#ff0000"
    />
  )
}

• errorBarColor defaults to "#AAA"

  Default	Error Bars	errorBarColor="#ff0000"

Colors

Colors may be specified through 2 different mechanisms, both through a color prop. If none of the mechanisms are specified, BarGraph defaults to a built in color palette.

User-provided Color Palette

Users can specify a list of colors to use as a palette, passed to the color prop.

render() {
  let colors = [
    "#fea9ac", "#fc858f", "#f46b72", "#de836e",
    "#caa56f", "#adcc6f", "#8ebc57", "#799b3f"
  ]

  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country" 
      	color={colors}
    />
  )
}

User-provided Color function

Users can also specify a function to assign colors to different bars. Expected arguments to the function are the index of the bar (from 0), its corresponding x-value, and its group (if it exists).

let colorMe = (i, value, group) => {
  if (value === "Github"){
    return "red"
  } else {
    return "grey"
  }
}

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	color={colorMe}
    />
  )
}

color={colors}	color={colorMe}

Axis Customization

Replot BarGraphs allow for incredible customization of the graph axis. A complete explanation of axis customization can be found below:

Titles

Title props accept strings to display in the appropriate location on the graph. To compensate for the inclusion of a title, graph content will be condensed, but the overall size of the component will stay constant.

• graphTitle: string displayed above the graph
• xTitle: string displayed left of the x-axis
• yTitle: string displayed under the y-axis

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
    	graphTitle="Population by Country"
      	xTitle="Year"
      	yTitle="Population" />
  )
}

Default	Custom titles

Displaying Axis Elements

Users can customize the display of the lines, labels, and gridlines of the axes.

• showXAxisLine: defaults to true, controls display of the x-axis line
• showYAxisLine: defaults to true, controls display of the y-axis line
• showXLabels: defaults to true, controls display of labels on the x-axis
• showYLabels: defaults to true, controls display of labels on the y-axis
• showGrid: defaults to true, controls display of gridlines

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	showXAxisLine={false}
	showYAxisLine={false}
	showXLabels={false}
	showYLabels={false}
	showGrid={false}
    />
  )
}

Lines hidden	Labels hidden

Axis Scale

Users can control the scale of the graph, linear or logarithmic. Users can also control the number of increments on the y-axis.

• yScale: defaults to "lin" for linear scale, can be "log" for logarithmic scale

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	yScale="log"
    />
  )
}

• ySteps: defaults to 1 division per 100 pixels, accepts a number given by the user

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	ySteps={20}
    />
  )
}

yScale="log"	yStep={20}

Axis Style

Users can customize the axis style by passing in the prop(s) below:

• axisColor
  • modifies the color of axis lines
  • defaults to "#AAA"
  • accepts any color string
• tickColor
  • modifies the color of axis ticks
  • defaults to "#AAA"
  • accepts any color string
• gridColor
  • modifies the color of axis gridlines
  • defaults to "#AAA"
  • accepts any color string
• labelColor
  • modifies the color of both axis labels
  • defaults to "#AAA"
  • accepts any color string
• graphTitleColor
  • modifies the color of all graph titles
  • defaults to "#AAA"
  • accepts any color string

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	axisColor="#ff0000"
	tickColor="#ff0000"
	gridColor="#ff0000"
	labelColor="#ff0000"
	graphTitleColor="#ff0000"
    />
  )
}

• axisWidth
  • modifies the thickness of axis lines
  • defaults to 1.5
  • accepts any number
• tickWidth
  • modifies the thickness of axis ticks
  • defaults to 1.5
  • accepts any number
• gridWidth
  • modifies the thickness of axis gridlines
  • defaults to 1
  • accepts any number

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	axisWidth={5}
	tickWidth={5}
	gridWidth={5}
    />
  )
}

• axisOpacity
  • modifies the opacity of axis lines
  • defaults to 1
  • accepts any number
• tickOpacity
  • modifies the opacity of axis ticks
  • defaults to 1
  • accepts any number
• gridOpacity
  • modifies the opacity of axis gridlines
  • defaults to 0.5
  • accepts any number

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
      	axisOpacity={0.2}
	tickOpacity={0.2}
	gridOpacity={0.2}
    />
  )
}

Custom colors	Custom widths	Custom opacities

• labelFontSize
  • sets the font size of both axis labels
  • automatically calculated when unspecified
  • accepts any number
• graphTitleFontSize
  • sets the font size of all graph titles
  • automatically calculated when unspecified
  • accepts any number

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
        labelFontSize={8}
    	graphTitleFontSize={10}
    />
  )
}

• labelFontFamily
  • sets the font family of both axis labels
  • inherits when unspecified
  • accepts any font family name string
• graphTitleFontFamily
  • sets the font family of all graph titles
  • inherits when unspecified
  • accepts any font family name string

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
	labelFontFamily="Courier"
	graphTitleFontFamily="Courier"
    />
  )
}

Custom font sizes	Custom font families

Legend Customization

Users can customize the graph legend in several ways.

• showLegend: defaults to true if there is a group key, controls display of the legend

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
	showLegend={false}
    />
  )
}

Default	showLegend={false}

Legend Style

Users can customize the legend style by passing in the prop(s) below:

• legendFontColor Modifies the color of the font used in the legend Defaults to "#AAA" * Accepts any color string
• legendBackground Modifies the background color of the legend Defaults to "none" * Accepts any color string
• legendShowBorder Determines whether a border will be drawn around the legend Defaults to false * Accepts true or false
• legendBorderColor Modifies the color of the border of the legend Defaults to "#AAA" * Accepts any color string

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
	legendFontColor="#ff0000"
	legendBackground="#ffffff"
	legendShowBorder={true}
	legendBorderColor="#ff0000"
    />
  )
}

Default	Custom Style

• legendFontSize
  • sets the font size of legend texts
  • automatically calculated when unspecified
  • accepts any number
• legendFontFamily
  • sets the font family of legend texts
  • inherits when unspecified
  • accepts any font family name string

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
  	legendFontSize={10}
  	legendFontFamily="Courier"
    />
  )
}

Default	legendFontSize={10}	legendFontFamily="Courier"

Tooltip

Tooltips can display more specific information about a data series.

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
	tooltip={false}
	tooltipColor="light"
    />
  )
}

• tooltip defaults to true, false turns the tooltip off

• tooltipColor defaults to dark, it can be set to light or dark

  Default tooltip	tooltipColor="light"	tooltip={false}

User-provided Tooltip Function

Users can customize what is displayed inside the tooltip with a function. Expected arguments to the function are the data for the specific bar hovered over. The function should return JSX.

let fillTooltip = (data) => {
  return(
    <span>The country for this bar is {data.country}</span>
  )
}

render() {
  return(
    <BarGraph data={populations} xKey="year" yKey="population" groupKey="country"
	tooltipContents={fillTooltip}
    />
  )
}

Animation Customization

Users can control the initial animation of the graph, bars growing out from the x-axis line.

• initialAnimation: defaults to true, controls the animation