Serializable spec

The builders — createSpec, pipe, geom.*, scale.*, config — are a convenience. What they produce is a plain, immutable object of objects, arrays, strings, numbers and booleans. A spec holds no functions, class instances or DOM references, so it round-trips through JSON.stringify / JSON.parse unchanged. You can store a spec in a database, send it over the wire, generate it from another language, or write one by hand.

The builders only assemble an object

pipe(...) and the geom.* / scale.* / config helpers assemble and merge a plain object. This call:

import { createSpec, pipe, geom, scale, config } from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue', color: 'product' }),
  geom.line(),
  scale.x(),
  scale.y.continuous({ domainMin: 0 }),
  scale.color.discrete(),
  config({ legend: { position: 'bottom' } })
);

produces exactly this object — and JSON.stringify(spec) gives you exactly this JSON (fields left undefined drop out):

{
  "mapping": { "x": "month", "y": "revenue", "color": "product" },
  "layers": [{ "type": "layer", "geom": "line" }],
  "scales": [
    { "type": "scale", "scaledAesthetic": "x", "scaleType": "inferred" },
    {
      "type": "scale",
      "scaledAesthetic": "y",
      "scaleType": "continuous",
      "domainMin": 0,
      "domainMax": null,
      "domainMid": null
    },
    { "type": "scale", "scaledAesthetic": "color", "scaleType": "discrete" }
  ],
  "transforms": [],
  "highlights": [],
  "config": { "legend": { "position": "bottom" } }
}

You could paste that JSON into your source and pass it to GraphProvider as spec, with no builder in sight. What the builders add is types: autocomplete for aesthetics, options and params, and a type check on the shape. Defaults are filled in at compile time either way.

Every top-level key

createSpec seeds six keys — mapping, layers, scales, transforms, highlights and config — so they are present even when empty. The other three appear only once something is piped in:

Key	Holds
`mapping`	The spec-level aesthetic mapping
`layers`	One entry per geom
`scales`	One entry per declared scale
`transforms`	Spec-level transforms
`highlights`	Highlights
`config`	Chart chrome
`coords`	The coordinate system — a single object, not a list
`styles`	The stylesheet
`annotations`	Annotations, grouped by kind

A styled spec is still JSON

The stylesheet is the largest thing a spec carries, and it round-trips like the rest. A token('brand') reference is a plain object the compile stage inlines. A light/dark color pair is a plain object the renderer picks from at read time. Neither needs a function:

import {
  createSpec,
  pipe,
  geom,
  scale,
  styles,
  style,
  token,
} from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  scale.x(),
  scale.y(),
  styles({
    tokens: { brand: { light: '#0B5FFF', dark: '#6AA1FF' } },
    defaults: [style.geom({ fill: token('brand'), stroke: token('brand') })],
  })
);

{
  "styles": {
    "type": "styles",
    "tokens": { "brand": { "light": "#0B5FFF", "dark": "#6AA1FF" } },
    "defaults": [
      {
        "select": { "target": "geom" },
        "declarations": {
          "fill": { "token": "brand" },
          "stroke": { "token": "brand" }
        }
      }
    ]
  }
}

Writing the JSON by hand

Two things to know before you do. A layer’s aesthetic override is called aes on the builder and mapping in the object: geom.line({ aes: { y: 'profit' } }) serializes as { "type": "layer", "geom": "line", "mapping": { "y": "profit" } }. A spec that uses a plugin geom, stat or transform still serializes: a custom layer is just { "geom": "candlestick", "params": { … } }. The plugin itself is code. It reaches the chart through the plugins array on GraphProvider, not through the spec. Store the spec; ship the plugins with your app.

How a chart is built — the compile → render pipeline that consumes a spec
Data structure — the table a spec references by column name
Extending — custom geoms, stats and transforms, and the plugins they ship in

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

The builders only assemble an object

Every top-level key

A styled spec is still JSON

Writing the JSON by hand

Next

​The builders only assemble an object

​Every top-level key

​A styled spec is still JSON

​Writing the JSON by hand

​Next

The builders only assemble an object

Every top-level key

A styled spec is still JSON

Writing the JSON by hand

Next