Chart

a graphical chart

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"

animate

Whether to animate drawing.

boolean
true
false

bounds

The limits for the values, specified as a two dimensional array.

array

The first array specifies the limits of the x-axis. The second array specifies the limits of the y-axis. For example: [[x-min, x-max], [y-min, y-max]]. If not specified, the bounds will automatically be set to fit the provided values.

[[0, 10], [0, 100]]
object
{ 
  x: { min: number, max: number },
  y: { min: number, max: number } 
}

color

A color identifier to use for the graphic color.

string
"graph-0"
object

'opacity' is deprecated, use top level 'opacity'.

{"color": "graph-0", "opacity": true}
array

If an array is specified, it is used to create a gradient mask. Array objects indicate what color to show at what value. In the simplest case, the values should map to the Y bounds values, resulting in a vertical gradient. Specifying more objects allows more fine grained control over where the gradient colors change.

[{
 color: "string" |
 { dark: "string", light: "string" },
 value: number
}]

dash

Whether to use dashed lines for line or bar charts.

boolean
true
false

gap

The amount of spacing between data points. This is only used when the size specifies width as 'auto'.

string

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

"none"
"xxsmall"
"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"

id

A unique identifier for the Chart. This is required if more than one Chart is shown and they use color gradients or if a pattern is specified.

string
"chart_1"

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: "..."
}
        

onClick

Called when the user clicks on the visualization. Clicking on individual bars or points are handled via values[].onClick for those types of charts.

function
() => {}

onHover

Called with a boolean argument indicating when the user hovers onto or away from it. This is only available when the type is line or area.

function
(true) => {}

opacity

What opacity to apply to the visuals. Supersedes 'color.opacity'

string
"weak"
"medium"
"strong"
boolean
true
false

overflow

Whether the chart strokes should overflow the component. Set this to true for precise positioning when stacking charts or including precise axes. Set this to false to have the graphical elements align with the component boundaries.

boolean
true
false

pad

Spacing around the outer edge of the drawing coordinate area. Related to 'overflow', this allows control over how much space is available for bars and points 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.


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

pattern

When using an 'area' type, what pattern to fill the area with.

string
"squares"
"circles"
"stripesHorizontal"
"stripesVertical"
"stripesDiagonalDown"
"stripesDiagonalUp"

point

When using a 'point' type, what shape the points should use. If this property is not specified, points will be drawn as a square or a circle, based on how 'round' is specified.

string
"circle"
"diamond"
"square"
"star"
"triangle"
"triangleDown"

round

Whether to round the line ends.

boolean
true
false

size

The size of the Chart. 'full' is deprecated as 'fill' is more consistent with how that term is used elsewhere.

string

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

"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"fill"
"full"
"any CSS size"
object
{"height": "...", "width": "..."}

thickness

The width of the stroke.

string

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

"none"
"hair"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"string"
number
5

type

The visual type of chart.

string
"bar"
"line"
"area"
"point"

values

Array of value objects describing the data.

array

'value' is a tuple indicating the coordinate of the value or a triple indicating the x coordinate and a range of two y coordinates. 'label' is a text string describing it. 'onHover' and 'onClick' only work when type='bar'. 'color', 'opacity', and 'thickness' allow bar and point charts to have color variation per-value.

[ 10, 20 ]
[ [10, 20], [20, 30] ]

[
  {
    color: "string" | { dark: "string", light: "string" },
    label: "string",
    onClick: function,
    onHover: function,
    opacity: "string" | number | boolean,
    thickness: "string",
    value: "..."
  },
]
            

Theme

chart.color

Color of the Chart.

string

A hex, name, or rgb value.

"graph-0"
object

An object with a color for dark and light modes.

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

chart.extend

Any additional style for the Chart.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

global.colors

Color options.

object

{
  "icon": { "dark": "#f8f8f8", "light": "#666666" },
  "active": "rgba(221, 221, 221, 0.5)",
  "background-back": { "dark": "#33333308", "light": "#EDEDED" },
  "background-front": { "dark": "#444444", "light": "#FFFFFF" },
  "background-contrast": { "light": "#33333310", "dark": "#FFFFFF18" },
  "active-background": "background-contrast",
  "active-text": "text-strong",
  "black": "#000000",
  "border": { "dark": "rgba(255, 255, 255, 0.33)", "light": "rgba(0, 0, 0, 0.33)" },
  "brand": "#7D4CDB",
  "control": { "dark": "graph-0", "light": "brand" },
  "focus": "#6FFFB0",
  "graph-0": "accent-1",
  "graph-1": "neutral-1",
  "graph-2": "neutral-2",
  "graph-3": "neutral-3",
  "graph-4": "neutral-4",
  "placeholder": "#AAAAAA",
  "selected": "brand",
  "text": { "dark": "#f8f8f8", "light": "#444444" },
  "text-strong": { "dark": "#FFFFFF", "light": "#000000" },
  "text-weak": { "dark": "#CCCCCC", "light": "#555555" },
  "text-xweak": { "dark": "#BBBBBB", "light": "#666666" },
  "selected-background": "brand",
  "selected-text": "text-strong",
  "white": "#FFFFFF",
  "accent-1": "#6FFFB0",
  "accent-2": "#FD6FFF",
  "accent-3": "#81FCED",
  "accent-4": "#FFCA58",
  "dark-1": "#333333",
  "dark-2": "#555555",
  "dark-3": "#777777",
  "dark-4": "#999999",
  "dark-5": "#999999",
  "dark-6": "#999999",
  "light-1": "#F8F8F8",
  "light-2": "#F2F2F2",
  "light-3": "#EDEDED",
  "light-4": "#DADADA",
  "light-5": "#DADADA",
  "light-6": "#DADADA",
  "neutral-1": "#00873D",
  "neutral-2": "#3D138D",
  "neutral-3": "#00739D",
  "neutral-4": "#A2423D",
  "status-critical": "#FF4040",
  "status-error": "#FF4040",
  "status-warning": "#FFAA15",
  "status-ok": "#00C781",
  "status-unknown": "#CCCCCC",
  "status-disabled": "#CCCCCC",
  "background": { "light": "#ffffff", "dark": "#000000" }
}
              

global.edgeSize

The possible sizes for the thickness in the Chart

object

    {
      none: '0px',
      hair: '1px',
      xxsmall: '3px',
      xsmall: '6px',
      small: '12px',
      medium: '24px',
      large: '48px',
      xlarge: '96px',
      responsiveBreakpoint: 'small'
    }
        

global.opacity

The opacity of the Chart stroke.

object

{
  strong: 0.8,
  medium: 0.4,
  weak: 0.1,
}

global.size

The possible sizes for Chart width and height.

object

{
  xxsmall: '48px',
  xsmall: '96px',
  small: '192px',
  medium: '384px',
  large: '768px',
  xlarge: '1152px',
  xxlarge: '1536px',
  full: '100%',
}

calcs()

a function to help calculate values for bounds and axis

const { axis, bounds, pad, thickness } = calcs(values, { coarseness, steps })

calcs() takes an array of values and provides recommendations on how to set Chart properties and construct axes.

options

coarseness

Affects the precision of the bounds and axes. For example, if the values are [27.35, 9.47], higher coarseness would bound it from 0-50, lower coarseness would bound it from 9-28.

number
5

steps

Affects the stepping of the axis values.

array
[1, 1]

returns

bounds

An array of arrays suitable for use with the Chart bounds property.

array
[[0, 2], [0, 100]]

thickness

A string suitable for use with the Chart thickness property.

string
"medium"

pad

A string suitable for use with the Chart pad property.

string
"medium"

axes

An array of arrays. The first array is for X axis values. The second array is for Y axis values.

array
[[0, 1, 2], [0, 50, 100]]

The X axis values could be rendered however you like, perhaps with something like:

<Box direction="row" justify="between" gap="small">
    {axis[0].map(a => <Text color="text-xweak" />)}
  </Box>