Chart

<caos-chart>

a set of figures drawn as bars or a line, so a trend can be seen rather than read

May be placed on a record page, an app’s home page and a page inside an app.

Inputs

Name	Attribute	Description	Type	Default	Required
points	property only	The readings, in the order they are drawn. Each is either a plain number or an object with value and, optionally, label and display. display is the figure already formatted — this piece rounds, groups and abbreviates nothing, the same way StatTile does not, because currency and locale are known where the data comes from and not here. A reading whose value is not a finite number is dropped rather than drawn as a zero.	json	empty list	Optional
type	type, markup only	Which drawing. bar is one bar per category, scaled against the largest figure in the set. line is a value over time with a dot at each reading. sparkline is that line with its caption, axis and dots stripped, sized to sit inside another piece. Anything unrecognised reads as bar.	text — recognises bar, line, sparkline; anything else reads as bar	bar	Optional
label	label, markup only	What the whole set is. Drawn as a caption above the figures, and used as the heading of the text equivalent a line carries. A sparkline draws no caption — it sits inside a piece that has already said what the figures are — but still uses this to name its text equivalent.	text	none declared	Optional
max	max, markup only	The top of the scale. Left out, the largest figure in the set is the top, which makes each chart tell its own story well and makes two charts side by side incomparable. Set it when the point is the comparison — a quota, a target, or the same ceiling across several charts.	number	none declared	Optional
emptyLabel	empty-label, markup only	What is said when there are no readings. There is always something rather than an empty frame, because a chart with no bars in it reads as “everything is nought”, which is a different and usually wrong statement.	text	Nothing to show yet.	Optional

Events

This piece raises no events.

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
--caos-font	The face of every label, figure and caption.
--caos-space-2	The gap between the caption and the figures, and between one bar and the next.
--caos-space-3	The gap holding a bar’s label apart from its figure.
--caos-color-text	The caption, each bar’s label, and each bar’s figure.
--caos-color-text-muted	The axis at the ends of a line, and the words shown when there is nothing to draw.
--caos-color-bg	The track a bar is drawn along.
--caos-color-accent	The fill of a bar, and the stroke and dots of a line.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(chart)	the whole piece	Always
::part(caption)	the label above the figures	a label is set and the type is not a sparkline
::part(rows)	the list of bars	the type is a bar
::part(row)	one bar and its heading	the type is a bar
::part(label)	what one bar is	the type is a bar
::part(value)	the figure beside one bar	the type is a bar
::part(track)	the groove a bar is drawn along	the type is a bar
::part(fill)	the drawn length of one bar	the type is a bar
::part(figure)	the drawing itself	the type is a line or a sparkline
::part(line)	the stroke joining the readings	the type is a line or a sparkline
::part(point)	the dot at one reading	the type is a line
::part(axis)	the first and last labels beneath a line	the type is a line
::part(table)	the figures as text, for assistive technology	the type is a line or a sparkline
::part(empty)	what is said when there is nothing to draw	there are no readings

When to use it

When the SHAPE of a set of figures is the point — that it is rising, that one category dwarfs the rest — rather than the figures themselves. A handful of readings up to a few dozen. It takes its data directly and needs no saved report, so a page can draw a trend from data it already has.

What to use instead

• StatTile — There is one figure rather than a set, and what matters is the number itself.
• ProgressBar — The figure is one proportion of a whole, or how far a long job has got.
• DataTable — The figures need reading exactly, sorting, or comparing against each other row by row. A chart shows a shape; a table answers “what was it in March”.

Accessibility

Bars are ordinary elements, so each label and figure is already text in the page and is read without help. A line and a sparkline are pictures, so the drawing is hidden from assistive technology and the same figures are carried beside it as a table that is present but not visible — the label names its caption. Nothing here depends on telling two colours apart: there is only ever one series, and every figure sits beside its own label. Two things are left to the author. The piece is not a live region, so figures that change while somebody is looking announce nothing. And a set of readings whose labels do not say what they are — “1”, “2”, “3” — is as unreadable in the table as it is in the picture, so give each reading a label.

Examples

A breakdown by stage

One bar per category with its own figure beside it, each scaled against the largest in the set.

{
  "id": "example",
  "section": "A breakdown by stage",
  "columns": 1,
  "items": [
    {
      "id": "chart_1",
      "type": "component",
      "key": "chart",
      "inputs": {
        "label": "Pipeline by stage",
        "type": "bar",
        "points": [
          {
            "label": "Qualification",
            "value": 48200,
            "display": "$48,200"
          },
          {
            "label": "Proposal",
            "value": 121500,
            "display": "$121,500"
          },
          {
            "label": "Negotiation",
            "value": 76400,
            "display": "$76,400"
          },
          {
            "label": "Closed won",
            "value": 33800,
            "display": "$33,800"
          }
        ]
      }
    }
  ]
}

<caos-chart id="chart1" label="Pipeline by stage" type="bar"></caos-chart>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const chart1 = document.getElementById('chart1');
chart1.points = [
  {
    "label": "Qualification",
    "value": 48200,
    "display": "$48,200"
  },
  {
    "label": "Proposal",
    "value": 121500,
    "display": "$121,500"
  },
  {
    "label": "Negotiation",
    "value": 76400,
    "display": "$76,400"
  },
  {
    "label": "Closed won",
    "value": 33800,
    "display": "$33,800"
  }
];

A figure over time

A line with a dot at each reading and the ends of the run written out beneath it.

{
  "id": "example",
  "section": "A figure over time",
  "columns": 1,
  "items": [
    {
      "id": "chart_1",
      "type": "component",
      "key": "chart",
      "inputs": {
        "label": "Orders per week",
        "type": "line",
        "points": [
          {
            "label": "Week 1",
            "value": 18
          },
          {
            "label": "Week 2",
            "value": 24
          },
          {
            "label": "Week 3",
            "value": 21
          },
          {
            "label": "Week 4",
            "value": 33
          },
          {
            "label": "Week 5",
            "value": 41
          },
          {
            "label": "Week 6",
            "value": 38
          }
        ]
      }
    }
  ]
}

<caos-chart id="chart1" label="Orders per week" type="line"></caos-chart>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const chart1 = document.getElementById('chart1');
chart1.points = [
  {
    "label": "Week 1",
    "value": 18
  },
  {
    "label": "Week 2",
    "value": 24
  },
  {
    "label": "Week 3",
    "value": 21
  },
  {
    "label": "Week 4",
    "value": 33
  },
  {
    "label": "Week 5",
    "value": 41
  },
  {
    "label": "Week 6",
    "value": 38
  }
];

A sparkline inside a tile

The same line stripped to its stroke, sitting in the visual slot StatTile documents but could not fill.

{
  "id": "example",
  "section": "A sparkline inside a tile",
  "columns": 1,
  "items": [
    {
      "id": "stat_tile_1",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Open orders",
        "value": "248",
        "delta": "+12%",
        "trend": "up"
      },
      "children": [
        {
          "id": "chart_2",
          "type": "component",
          "key": "chart",
          "inputs": {
            "label": "Open orders, last six weeks",
            "type": "sparkline",
            "points": [
              18,
              24,
              21,
              33,
              41,
              38
            ]
          },
          "slot": "visual"
        }
      ]
    }
  ]
}

<caos-stat-tile label="Open orders" value="248" delta="+12%" trend="up">
  <caos-chart id="statTile1chart1" slot="visual" label="Open orders, last six weeks" type="sparkline"></caos-chart>
</caos-stat-tile>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const statTile1chart1 = document.getElementById('statTile1chart1');
statTile1chart1.points = [
  18,
  24,
  21,
  33,
  41,
  38
];

Nothing to draw

With no readings it says so in words, rather than drawing an empty frame that reads as nought.

{
  "id": "example",
  "section": "Nothing to draw",
  "columns": 1,
  "items": [
    {
      "id": "chart_1",
      "type": "component",
      "key": "chart",
      "inputs": {
        "label": "Revenue by region",
        "type": "bar",
        "points": [],
        "empty_label": "No revenue recorded yet."
      }
    }
  ]
}

<caos-chart id="chart1" label="Revenue by region" type="bar" empty-label="No revenue recorded yet."></caos-chart>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const chart1 = document.getElementById('chart1');
chart1.points = [];