DataChart

DataChart takes an array of objects in data and provides various visualization capabilities on that data. It attempts to default as much as it possibly can to make it easy to get started and then customize later. What follows is some guidance on how to get started and then delve into what DataChart can do.

series

To begin with, give your DataChart some data and set the series property to indicate which properties in the data objects should be used.

Note that the X and Y axis are defaulted and the dates are automatically formatted based on the granularity given.

chart

Next, we can customize the kind of chart we are looking at.

axis and guide

Next, we can customize the axis and add guide lines.

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

axis

Whether to show an axis and how it should look.

boolean

If axis is true, DataChart will look for a property called 'date' or 'time' and automatically use that for the x-axis. DataChart will use the first property in 'series' for the y-axis.

true

false

string

The name of a property.

"date"

object

If 'x' or 'y' is a string, it indicates the property to use to determine the values to show. If 'x' is true, DataChart will look for a property called 'date' or 'time' and automatically use that for the x-axis. 'granularity' indicates how many values to show. If DataChart can't find a property to use, it will use the data index for the x-axis. If axis or 'y' is true, DataChart will use the first property in 'series'. 'coarse' granularity shows two values, one at each end. 'fine' granularity shows all x-axis values and 5 y-axis values. 'medium' granularity picks something in between.


{
  x: boolean | string |
    {
      granularity: "...",
      property: "date"
    },
  y: boolean | string |
    {
      granularity: "...",
      "property": "amount"
    }
  ]
}

where granularity could be:

"coarse"

"medium"

"fine"

bounds

When set to 'align', indicates that the bounds of all series should be aligned. When not set, the bounds of each series property are based solely on the data found for that property.

string

"align"

object

The bounds to use on the X/Y axis. This is useful to maintain consistent X/Y axis labelling across different data sets.


{
  x: [0, 100],
  y: [0, 100],
}

chart

How to visualize the data.

string

If only a string is specified, that is the property to use and all other aspects are defaulted.

"property"

object

'property' indicates which property of the data objects to use. When 'type' is 'bars' or 'areas', 'property' is an array of strings or objects. If 'property' is an object, it specifies a map of properties to graphic aspects: x, y, color, thickness. If 'transform' is specified, it will be used to transform the data value before using it. For example, to convert a data value to a hex color string for the color.


{
  property: "...",
  color: "...",
  dash: boolean,
  opacity: "...",
  pattern: "...",
  point: "...",
  round: boolean,
  thickness: "...",
  type: "..."
}

where property could be:

"string"

array["property1", "property2"]

array[{ property: "...", color: "..." }]

{ color: "string" | { property: "...", transform: function }, thickness: "...", x: "string", y: "string" }

where color could be:

"string"

{ dark: "string", light: "string" }

where opacity could be:

"weak"

"medium"

"strong"

number

boolean

where pattern could be:

"squares"

"circles"

"stripesHorizontal"

"stripesVertical"

"stripesDiagonalDown"

"stripesDiagonalUp"

where point could be:

"circle"

"diamond"

"square"

"star"

"triangle"

"triangleDown"

where thickness could be:

"hair"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"none"

"string"

where type could be:

"bar"

"bars"

"line"

"area"

"areas"

"point"

data

The data set.

array


[
  {
    "date": "2020-05-28",
    "amount": 88,
    "percent": 20
  },
  {
    "date": "2020-05-27",
    "amount": 77,
    "percent": 15
  }
]

detail

Whether to add the ability to interact with the chart via mouse or keyboard to show details on specific values in the chart. It shows all properties specified in 'series', using any 'render' functions therein.

boolean

true

false

direction

The orientation of the data.

string

"horizontal"

"vertical"

gap

The spacing between the axes and the Charts.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"string"

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

guide

Whether to put guidelines underneath the chart graphics. See the description of 'granularity' under 'axis'.

boolean

true

false

object


{
  x: boolean |
    {
      granularity:
        "coarse"
        "medium"
        "fine"
    }
  y: boolean |
    {
      granularity:
        "coarse"
        "medium"
        "fine"
    }
}

legend

Whether to include a legend

boolean

true

false

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

offset

Whether to offset each chart by the thickness of the preceding charts. This can be used to show adjacent bar charts.

boolean

true

false

object

A gap can be specified using the same t-shirt sizes as thickness to indicate the space between offset charts.


{
  gap: "string"
}

pad

Spacing around the outer edge of the drawing coordinate area for the graphic elements to overflow into.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

placeholder

A text message or any content to place over the chart graphic. For example, to say "loading ..." when waiting for data to arrive.

string

"loading..."

node

<Box>...</Box>

series

Describes which parts of the 'data' are of interest and how to handle them.

string

"property"

array[string]

["property1", "property2"]

object

'property' indicates which property of the 'data' objects this series refers to. 'label' indicates how to label the series in a legend or hover details. 'prefix' and 'suffix' are applied to the data values shown in an axis, legend, or details. 'render' allows custom rendering of the data value. 'render' is called with: (value, datum, property) => { return < />; }


{
  label: "string",
  prefix: "$",
  property: "string",
  render: (value, datam, dataIndex) => element,
  suffix: "%"
}

array[object]


[
  {
    label: "string",
    prefix: "$",
    property: "string",
    render: (value, datam, dataIndex) => element,
    suffix: "%"
  },
]

size

The size of the Charts. This does not include the axes and any gap. It is passed through to the underlying Chart.

string

"fill"

object

{ height: "...", width: "..." }

React/DOM Properties

At its core, the DataChart component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.