# How to Use Astryx VegaChart and Chart Components for Data Visualization

> Learn to use Astryx VegaChart and chart components for powerful data visualization in React. Effortlessly integrate and manage Vega specs for dynamic charts.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/facebook/astryx/blob/main/VegaChart.tsx)** – Located at [`packages/vega/src/VegaChart.tsx`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/types.ts)** – Found at [`packages/vega/src/types.ts`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/schema.ts)** – Stored at [`packages/vega/src/schema.ts`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/vegaLiteConfig.ts)** – Located at [`packages/vega/src/vegaLiteConfig.ts`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/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:

```tsx
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:

```tsx
<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`](https://github.com/facebook/astryx/blob/main/packages/vega/src/vegaLiteConfig.ts) and merge it with your specification:

```tsx
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`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/packages/vega/src/schema.ts).

## Summary

- **Astryx VegaChart** in [`packages/vega/src/VegaChart.tsx`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/packages/vega/src/vegaLiteConfig.ts) combined with `useTheme` from [`packages/core/src/theme/useTheme.ts`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/packages/vega/src/vegaLiteConfig.ts) and pass your theme object from `useTheme()` (located at [`packages/core/src/theme/useTheme.ts`](https://github.com/facebook/astryx/blob/main/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.