How to Use Astryx VegaChart and Chart Components for Data Visualization

The @astryxdesign/vega package exports a VegaChart React component that automatically detects Vega-Lite specifications via the $schema URL, compiles them to Vega when necessary, and manages the full Vega View lifecycle including data injection and cleanup.

The facebook/astryx repository provides a dedicated visualization package that bridges the gap between raw Vega specifications and React applications. By wrapping the Vega and Vega-Lite libraries in a single unified component, Astryx VegaChart eliminates the complexity of manual compilation while enforcing design system consistency through pre-themed configurations.

Core Architecture of Astryx VegaChart

The @astryxdesign/vega package consists of four tightly-coupled modules that handle specification parsing, type safety, and theming:

• VegaChart.tsx – Located at packages/vega/src/VegaChart.tsx, this is the main React component that owns the full Vega View lifecycle, including parsing, rendering, data injection, and cleanup.
• types.ts – Found at packages/vega/src/types.ts, this file exports TypeScript definitions for VegaChartProps, AnySpec, VegaSpec, and VegaLiteSpec, ensuring type safety across the public API.
• schema.ts – Stored at packages/vega/src/schema.ts, this utility validates $schema URLs and determines whether a specification belongs to Vega or Vega-Lite, guarding against malformed specs.
• vegaLiteConfig.ts – Located at packages/vega/src/vegaLiteConfig.ts, this module provides the buildVegaLiteConfig function that generates a ready-made Vega-Lite Config pre-themed with Astryx design tokens.

How Astryx VegaChart Processes Specifications

The VegaChart component in packages/vega/src/VegaChart.tsx processes specifications through a strict six-step lifecycle:

1. Spec Detection – The component calls parseSchema(spec.$schema) from packages/vega/src/schema.ts to match the URL against known Vega and Vega-Lite patterns, returning { library: 'vega' | 'vega-lite', ok: true }.

2. Compilation – When the spec is identified as Vega-Lite, the component invokes compile(spec as VegaLiteSpec, compileOptions).spec from the vega-lite package, producing a pure Vega specification.

3. Parsing and View Creation – The (possibly compiled) Vega spec is passed to vega.parse() along with optional parseConfig and parseOptions. The resulting runtime is wrapped in new View(runtime, { …viewOptions, container }).

4. Data Injection – The data prop accepts an object whose keys correspond to named datasets in the Vega spec. These are loaded via view.data(name, tuples) before the first render. Note: Data updates after mount are intentionally ignored to keep the view lifecycle simple.

5. Lifecycle Management – A useEffect hook creates the view on mount and tears it down on unmount via view.finalize(). Changes to spec, data, compileOptions, parseConfig, parseOptions, or viewOptions trigger a complete view recreation.

6. Error Handling – The onReady(view) callback fires after successful rendering, while onError(error) captures parsing, compilation, or runtime errors. Both callbacks are wrapped in useEffectEvent to prevent unnecessary view recreations when callback references change.

Implementing Astryx VegaChart in React

After installing the @astryxdesign/vega package, import the component and pass a specification with a mandatory $schema field:

import {VegaChart} from '@astryxdesign/vega';

// Vega-Lite specification with external data
<VegaChart
  spec={{
    $schema: 'https://vega.github.io/schema/vega-lite/v5.json',
    mark: 'bar',
    data: {name: 'sales'},
    encoding: {
      x: {field: 'category', type: 'ordinal'},
      y: {field: 'value', type: 'quantitative'},
    },
  }}
  data={{
    sales: [
      {category: 'A', value: 30},
      {category: 'B', value: 55},
      {category: 'C', value: 12},
    ],
  }}
/>;

For pure Vega specifications, provide the Vega schema URL and optional runtime configuration:

<VegaChart
  spec={{
    $schema: 'https://vega.github.io/schema/vega/v5.json',
    marks: [{type: 'rect', from: {data: 'table'}}],
    data: [{name: 'table', values: [{x: 0, y: 0, width: 100, height: 100}]}],
  }}
  parseConfig={{
    background: '#0d1117',
  }}
  viewOptions={{
    logLevel: 1,
  }}
/>;

Theming Astryx VegaChart with Design Tokens

Astryx provides the buildVegaLiteConfig utility to generate a Vega-Lite configuration object populated with design system tokens. Import this from packages/vega/src/vegaLiteConfig.ts and merge it with your specification:

import {VegaChart, buildVegaLiteConfig} from '@astryxdesign/vega';
import {useTheme} from '@astryxdesign/core';

function ThemedChart() {
  const theme = useTheme();
  const astroConfig = buildVegaLiteConfig(theme);

  return (
    <VegaChart
      spec={{
        $schema: 'https://vega.github.io/schema/vega-lite/v5.json',
        mark: 'line',
        encoding: {
          x: {field: 'date', type: 'temporal'},
          y: {field: 'price', type: 'quantitative'},
        },
      }}
      compileOptions={{
        config: {
          ...astroConfig,
          axis: {labelFontSize: 12},
        },
      }}
    />
  );
}

The useTheme hook from packages/core/src/theme/useTheme.ts exposes token values that buildVegaLiteConfig translates into Vega-Lite configuration properties for colors, fonts, and spacing.

Advanced Configuration Options

The VegaChart component accepts several optional configuration objects that map directly to Vega API parameters:

• compileOptions – Passed to the Vega-Lite compile() function when converting Vega-Lite to Vega.
• parseConfig – Passed to vega.parse() for runtime configuration such as background colors or locale settings.
• viewOptions – Passed to the View constructor for controlling log levels, tooltips, and renderer selection.

The $schema field is mandatory; without it, the component cannot determine whether compilation is required and will immediately invoke onError with a validation failure from packages/vega/src/schema.ts.

Summary

• Astryx VegaChart in packages/vega/src/VegaChart.tsx automatically detects Vega-Lite specs via $schema URL parsing and compiles them to Vega when necessary.
• Data injection occurs once at mount time through the data prop and is non-reactive to prevent lifecycle complexity.
• Use buildVegaLiteConfig from packages/vega/src/vegaLiteConfig.ts combined with useTheme from packages/core/src/theme/useTheme.ts to apply Astryx design tokens.
• The component intentionally excludes StyleX support; control layout via standard className or style props.
• All configuration changes trigger a full view recreation, ensuring the chart always reflects the latest inputs.

Frequently Asked Questions

How does VegaChart detect whether a spec is Vega or Vega-Lite?

VegaChart calls parseSchema(spec.$schema) from packages/vega/src/schema.ts, which matches the URL against known Vega and Vega-Lite schema patterns. The function returns { library: 'vega' | 'vega-lite', ok: true } or an error if the URL is invalid, allowing the component to decide whether compilation is necessary.

Can I update chart data dynamically after the initial render?

No. The data prop is intentionally non-reactive. Values are loaded once via view.data(name, tuples) before the first render, and subsequent updates are ignored. To update data, you must change the spec prop or remount the component, which triggers a fresh view creation.

Why doesn't VegaChart support StyleX for styling?

The component intentionally does not accept xstyle or StyleX props because the Vega wrapper has no dependency on StyleX. Layout and container styling should be controlled via standard className or style props on the component or its parent container.

How do I integrate Astryx design tokens into custom Vega configurations?

Import buildVegaLiteConfig from packages/vega/src/vegaLiteConfig.ts and pass your theme object from useTheme() (located at packages/core/src/theme/useTheme.ts). Merge the returned configuration into your compileOptions.config object to automatically apply Astryx colors, typography, and spacing to your charts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}