@microsoft/fabric-visuals

The fabric-visuals package provides an all-inclusive data visualization component for React environments, supporting both Vega-Lite and Flint visualization JSON specifications. The intention of the component is to provide a smart, principled component for good looking, well-behaving data visualizations with clear inputs and outputs.

Its architectural and interaction design targets the co-authoring of data visualizations by both AI agents and developers.

This component is also intended to live in the context of "Fabric visual components", a family of components that target visual data analysis and presentation for use in React applications. These components share common structures for data, visual formatting (theming), interaction, and other functionality (see @microsoft/fabric-visuals-core and its dependents).

import { VegaVisual, useCssTheme } from '@microsoft/fabric-visuals';

export function RevenueChart() {
    const theme = useCssTheme();

    return (
        <VegaVisual
            spec={spec}
            data={data}
            theme={theme}
            header={{ title: 'Revenue by region', subtitle: 'FY26' }}
        />
    );
}

The component provides a multitude of options to customize its appearance and behavior. A considerable amount of inline behavior updates are added during runtime to the given specification by default, with the goal of ensuring good visualization and formatting practice. These behaviors can be customized or disabled with "capabilities", described below.

Quick Reference

• Package: @microsoft/fabric-visuals
• Purpose: React and headless APIs for rendering Vega-Lite visualizations in React/Fabric Apps.
• Use when: You need to render charts (bar, line, area, scatter, etc.) from a DataTable using Vega-Lite specs.
• Do NOT use when: You need a data grid/table (use @microsoft/fabric-datagrid), or you only need shared types/tokens (use @microsoft/fabric-visuals-core).
• Key exports: VegaVisual, VegaVisualProps, VegaVisualHandle, renderVisualToSvg, useCssTheme
• Node-safe entry: @microsoft/fabric-visuals/headless — exports renderVisualToSvg without loading React UI dependencies
• CSP-safe entry: @microsoft/fabric-visuals/embeddable — exports EmbeddableVegaVisual for sandboxed/iframe environments
• Peer dependencies: @microsoft/fabric-visuals-core
• Install: npm install @microsoft/fabric-visuals @microsoft/fabric-visuals-core

Table of contents:

• Installation
• Public API
• Visualization specification
• Data / theming
• Capabilities
• Visual framing
• Accessible navigation
• Examples
• Embeddable (CSP-Safe) Variant
• Trademarks
• Security
• Code of conduct

Installation

npm install @microsoft/fabric-visuals @microsoft/fabric-visuals-core

@microsoft/fabric-visuals-core is required alongside this package because the public API uses its DataTable and VisualTheme types.

The VegaVisual component is intended to be used in a React app. The headless rendering API is used for browserless SVG output.

Public API

The package entry point exports the symbols below.

React exports

export interface VegaVisualProps {
    /** A visualization spec, either Vega-Lite or Flint */
    spec: VisualizationSpec | string;
    /** A theme definition, see `@microsoft/fabric-visuals-core` */
    theme: VisualTheme;
    /** A table of input data, see `@microsoft/fabric-visuals-core` */
    data?: DataTable | null;
    /** A Vega-Lite `config` object, overwriting defaults defined within */
    configVegaLite?: VegaLiteConfig;
    /** Allows customizing default behavior of the visual and its functionality */
    capabilities?: VegaVisualCapabilities;
    /** A callback for arbitrary events emitted by this visual */
    onEvent?: VegaVisualEventCallback;
    /** A callback for interactions emitted by this visual */
    onInteraction?: InteractionEventCallback;
    /** CSS classes to attach to the visual element */
    className?: string;
    /** CSS styles to attach to the visual element */
    style?: CSSProperties;

    //-- Visual Container customization
    /** Allows customizing default behavior of the visual container */
    visualContainerCapabilities?: VisualContainerCapabilities;
    /** Allows adding metadata (e.g., title) to the container */
    header?: HeaderProps;
    /** Disables wrapping the visual in a visible container */
    chromeless?: boolean;
    /** CSS classes for outer frame placement, margins and sizing */
    containerRootClassName?: string;
    /** CSS classes for the inner card surface, not outer layout */
    containerClassName?: string;
}

export interface VegaVisualHandle {
    readonly view: View | null;
}

export const VegaVisual: React.ForwardRefExoticComponent<
    VegaVisualProps & React.RefAttributes<VegaVisualHandle>
>;

| Export | Signature | Notes | | --- | --- | --- | | VegaVisual | React.ForwardRefExoticComponent<VegaVisualProps & React.RefAttributes<VegaVisualHandle>> | Responsive SVG Vega/Vega-Lite renderer. Injects DataTable data, compiles Vega-Lite, and exposes the underlying Vega View through a ref. | | VegaVisualProps | interface above | Main React component props to render/control a data visualization | | VegaVisualHandle | interface above | ref.current?.view gives direct access to the current Vega View. |

Headless rendering

import { renderVisualToSvg } from '@microsoft/fabric-visuals/headless';

const result = await renderVisualToSvg(spec, {
    data,
    configVegaLite,
    capabilities,
});

renderVisualToSvg() uses the same compilation pipeline as VegaVisual to render SVG without a browser. Use the /headless entry to avoid loading React UI dependencies. Rendering uses the built-in theme with optional configVegaLite overrides; browser sizing, layout, and the host's live theme are not reproduced.

renderedDataMarkCount and renderedMarkCountsByType count data marks with visible paint and renderable local SVG geometry.

| Result field | Type | Notes | | --- | --- | --- | | svg | string | Serialized SVG output. | | diagnostics | readonly CompileDiagnostic[] | Warnings and errors emitted by the shared compiler. | | renderedDataMarkCount | number | Total data-mark SVG elements with visible paint and renderable local geometry. | | renderedMarkCountsByType | Readonly<Record<string, number>> | Painted, locally renderable data-mark counts keyed by Vega mark type, such as rect or symbol. |

Visualization specification

The VegaVisual component supports visualization specifications in either the Vega-Lite or Flint domain-specific languages. These languages attach bindings of data columns to visual properties, where generally each row of data maps to a visual item within the visualization.

Our component assumes that the provided spec is Vega-Lite, unless it finds the required chartType and encodings Flint properties as top-level properties.

Vega-Lite

For Vega-Lite, we do not expect data to be populated on the spec itself. If data is passed in as a prop to the component, then the data property defined in spec is overwritten. Similarly, we expect customizations to the Vega-Lite config property to be passed in as a prop to the component (see above).

Flint

For Flint, we use a subset of the entire Flint specification (ChartAssemblyInput), as many properties are defined at runtime due to the component's construction (e.g., chart size). An example Flint spec appropriate for VegaVisual is below:

{
  "chartType": "Bar Chart",
  "encodings": {
    "y": {
      "field": "[Studio/Distributor]"
    },
    "x": {
      "field": "[WW Gross]"
    }
  }
}

Two caveats about using Flint:

Semantic types for Flint

For Flint to work, a "semantic type" must be defined for each referenced field in the associated DataTable. This semantic type for each lives on the semanticType property in the respective column's metadata, defined within the DataTable's columns property array. If these semantic types are missing on the input data, the component will error.

These semantic types are intended to be ascertained by an AI agent from a sample of data and its column metadata. See Flint's authoring skill under the "Semantic types" heading or their documentation about semantic types (prefer to specify T2 types, the most specific type) for more information.

chartProperties not currently supported

Because of how the components' behaviors are stacked onto the given Vega-Lite specification, it can be functionally ambiguous how user-specific Flint-specific formatting combines with the formatting and behavior changes that the VegaVisual component makes. Currently, chartProperties is ignored by our component, but this will likely change in the future (see Flint docs for available options in Flint).

Data / theming

Our visualization components use common definitions of data and theming from our @microsoft/fabric-visuals-core package. See more information in that package's README.

Data

DataTable is our preferred structure for input data, which the VegaVisual component takes in on its data prop. It is a non-binary, serializable format that defines a two-dimensional structure of data (rows and columns) along with metadata about columns (display name, format string, semantic types).

Our visual component also can take multiple tables of data in a Record<string, DataTable> format on the component's data prop. If provided in this manner, then data will be loaded as Vega-Lite named data sources, and the spec should reference data according to the relevant key of this anonymous Record object. For example, a specific Vega-Lite layer can reference a named dataset by specifying data: { name: 'key1' } as its top-level property.

Note that it is not required to use the data prop to populate data for the VegaVisual component. Data can be provided within the data property of the given Vega-Lite spec. Providing data in this manner does not preclude the application of the optimistic behavior transforms described below in the Capabilities section. However, passing data in this way skips the automatic smarts of applying consistent display names and formating of data in data labels, axes, legends, and tooltips. This therefore puts the onus on the specification author to wire this support themselves within the given Vega-Lite spec.

Theming

VisualTheme is our structure for defining app-wide semantic and data colors, typography classes, borders, and spacing. While it is all customizable, we define a complete theme by default. You can consider CSS variables stored within the page as the authoritative source, where the convenience function useCssTheme() generates a VisualTheme object from those definitions to be passed programmatically to components.

The VegaVisual component will use semantic and data colors, spacing, as well as typography settings to format the visual via setting properties in the Vega-Lite config option automatically.

Capabilities

VegaVisual applies a set of optimistic behavior transforms during spec compilation by updating the given Vega-Lite spec at runtime (or the compiled Vega spec).

The optional capabilities prop lets consumers selectively disable these behaviors by passing a partial VegaVisualCapabilities object. Most flags default to false (behavior enabled); set a flag to true to disable it.

Interface

import type { VegaVisualCapabilities } from '@microsoft/fabric-visuals';

interface VegaVisualCapabilities {
    disableStackedDataLabels?: boolean;
    disableArcDataLabels?: boolean;
    disableNiceAxisBounds?: boolean;
    disableLineChartCrosshairTooltip?: boolean;
    disableTextTruncation?: boolean;
    disableLegendTruncation?: boolean;
    disableLegendScroll?: boolean;
    disableCategoricalScroll?: boolean | { options: CategoricalScrollOptions };
    disableMinBarSize?: boolean;
    disableDynamicAxisLabelOverlap?: boolean;
    disableNonZeroQuantitativeBaseline?: boolean;
    disablePointMarkClip?: boolean;
    disablePointRangeInset?: boolean;
    disableSelfHighlight?: boolean;
    disableCompactNumberFormatting?: boolean;
}

Capability flags

All visual capabilities are designed to be an explicit opt-out, so their default values are all false, except for disableLegendScroll, which conflicts with legend truncation.

Some options take additional options to customize relevant behavior; see detail in subsections below the table.

| Flag | Effect when true | |------|-------------------| | disableStackedDataLabels | Skips adding centered text labels on eligible stacked column/bar charts. | | disableArcDataLabels | Skips adding <category> <value> (<percentage>) labels and leader lines on eligible pie/donut (arc) charts. | | disableNiceAxisBounds | Skips setting scale.nice = 5 on quantitative axes, allowing quantitative axes to fit tighter to the data domain. | | disableLineChartCrosshairTooltip | Skips the convenience tooltip adding the ability to view multiple series' values in a line chart. | | disableTextTruncation | Skips truncating long text marks to prevent overflow, and hiding text marks if none shows more than one character. | | disableLegendTruncation | Skips capping legend entry count (symbolLimit) based on chart dimensions. Only applies when legend scrolling is disabled. | | disableLegendScroll | NOTE: true by default -- skips extracting legends into scrollable HTML. When disabled, legends stay in SVG. | | disableCategoricalScroll |Skips making bar/column charts scrollable when categories overflow. When set to { options: CategoricalScrollOptions }, configures scroll behavior (see below). | | disableMinBarSize | Skips enforcing a minimum bar size for small non-zero values; zero values still render no shape. | | disableDynamicAxisLabelOverlap | Skips automatic axis-label overlap management, band-scale tick truncation, and tick tooltips. By default, horizontal line-chart axes use 'parity' to show fewer, but readable labels. Any categorical axis with bars/shapes will have their band-scale ticks truncated with tooltip support. | | disableNonZeroQuantitativeBaseline | Skips allowing non-zero baselines for non-stacked, quantitative measures. | | disablePointMarkClip | Skips clipping Cartesian point-based charts (scatter and bubble) to the plot area. Projected points are never clipped automatically. | | disablePointRangeInset | Skips conditional point/bubble domain padding when a rendered marker would be clipped by the original niced domain. Nicing is retained unless padding would add wrong-sign ticks to one-sided data; in that case, nicing is disabled and those ticks are hidden (see below). | | disableSelfHighlight | Skips injecting native self-highlight (point selection param + conditional opacity) that dims unselected marks on click; Shift/Ctrl/Cmd-click adds to the selection. | | disableCompactNumberFormatting | Skips compact notation on quantitative axis ticks and data labels ("$10K" instead of "$10,000"). Tooltips and legends retain their existing formatting regardless of this flag (see below). |

Categorical scroll options

The disableCategoricalScroll flag accepts boolean | { options: CategoricalScrollOptions } for fine-grained scroll control:

| Value | Behavior | |-------|----------| | false (default) | Scrolling enabled with default threshold (15) and window size (10). | | true | Scrolling disabled entirely. | | { options: CategoricalScrollOptions } | Customize threshold, window size, and force-showing the scrollbar. |

CategoricalScrollOptions fields:

| Field | Type | Default | Description | |-------|------|---------|-------------| | threshold | number | 15 | Category count above which scrolling activates. | | forceShow | boolean | false | Always show the scrollbar. A diagnostic warning is emitted if the spec lacks structural prerequisites (band scale, rect marks). | | windowSize | number | 10 | Number of categories visible in the detail window at a time. |

Projected point maps

For point, circle, and square marks that use longitude/latitude channels or a top-level projection, VegaVisual leaves mark clipping disabled and insets Vega-Lite's automatic projection-fit extent by the largest marker radius. This keeps edge bubbles fully visible while preserving the geographic domain.

This behavior currently applies only when the point mark is the top-level mark of a unit spec. It is not applied when the point mark is one layer within a layered chart.

For every eligible unit spec, the full projection-fit extent is inset conservatively. The transform does not measure whether a bubble would actually cross the plot edge before applying the inset, so it may reserve space even when the existing fit already leaves enough room.

Automatic projection insetting is skipped when the spec explicitly controls layout with mark.clip or projection scale, translate, fit, or clipExtent. It is applied independently of the Cartesian disablePointRangeInset capability.

Compact number formatting

When labels are compacted using the current formatting locale, the compacted number is formatted according to the format string associated with the field. This means that the number of decimals (precision) will influence the number of fraction digits in the compacted number. To ensure a minimum level of disambiguation in axis ticks, we force at least one fraction digit, regardless of the format string setting. If an associated format string is not found, then up to two fraction digits may be emitted.

Example capabilities usage

import { VegaVisual, useCssTheme } from '@microsoft/fabric-visuals';
import type { VegaVisualCapabilities } from '@microsoft/fabric-visuals';

const capabilities: VegaVisualCapabilities = {
    disableCategoricalScroll: true,
    disableMinBarSize: true,
};

export function Example() {
    const theme = useCssTheme();

    return (
        <VegaVisual
            spec={spec}
            data={data}
            theme={theme}
            capabilities={capabilities}
        />
    );
}

Omitted keys keep their default behavior. The capabilities object is shallowly merged with the defaults at render time — you only need to specify the flags you want to change.

Visual framing

VegaVisual uses the shared VisualFramingProps contract from @microsoft/fabric-visuals-core. It creates a frame by default and renders without one when chromeless is set. When nested in an explicit VisualContainer, it does not create a second frame; configure the outer container instead.

import { VegaVisual, useCssTheme } from '@microsoft/fabric-visuals';

export function RevenueChart() {
    const theme = useCssTheme();

    return (
        <VegaVisual
            spec={spec}
            data={data}
            theme={theme}
            header={{ title: 'Revenue by region' }}
        />
    );
}

export function PlainChart() {
    const theme = useCssTheme();
    return <VegaVisual spec={spec} data={data} theme={theme} chromeless />;
}

capabilities controls chart behavior; visualContainerCapabilities controls frame behavior. For custom actions, capture APIs, and direct container usage, see the VisualContainer documentation.

Accessible keyboard navigation

VegaVisual provides keyboard exploration of Vega-Lite charts through an accessible overlay. The overlay follows the rendered chart geometry and exposes a hierarchy of chart regions (axes, plot, and legends, when present) and their contents (axis ticks, data points, and legend items). No additional prop is needed to enable navigation.

Entering and leaving a chart

For a framed visual, tab to the VisualContainer and press Enter after the chart has rendered. For a chromeless visual without a container, the visual's own root is the tab stop and keyboard entry point. A chromeless visual nested inside an explicit VisualContainer still uses the outer container's entry point; it does not add a second tab stop.

The overlay is created on Enter, not on focus or click. Entry moves focus into the first available chart region, usually the Y axis for a Cartesian chart.

Use Enter to move through the chart hierarchy, and use Tab, Shift+Tab, or arrow keys to explore items within a region. In scrollable visuals, navigation automatically updates the visible category window when focus reaches its edge.

Tab stays within the overlay while exploring. To leave the chart, press Escape until focus returns to its entry point, then use Tab or Shift+Tab to continue through the page. Container toolbar navigation remains separate from chart exploration.

| Key | Behavior inside the overlay | | --- | --- | | Tab / Shift+Tab | Move forward or backward among peers at the current level. For visuals without a scrollbar, focus wraps at the ends of the window. For scrollable visuals, focus moves forward or backward, scrolling the view as needed, and stops at the first or last item. | | Arrow keys | Move between items along the navigation directions available for the chart or region. | | Enter | Drill into a region, such as the plot's data points or an axis's ticks. | | Escape | Move up one level. From a top-level region, return focus to the container or chromeless visual root. |

Examples

Basic component usage (Vega-Lite)

import { VegaVisual, useCssTheme } from '@microsoft/fabric-visuals';
import type { VisualizationSpec } from '@microsoft/fabric-visuals';
import type { DataTable } from '@microsoft/fabric-visuals-core';

const spec: VisualizationSpec = {
    $schema: 'https://vega.github.io/schema/vega-lite/v6.json',
    mark: 'bar',
    encoding: {
        x: { field: 'category', type: 'nominal', title: 'Category' },
        y: { field: 'value', type: 'quantitative', title: 'Value' },
    },
};

const data: DataTable = {
    columns: [
        { name: 'category', displayName: 'Category' },
        { name: 'value', displayName: 'Value', format: '#,##0' },
    ],
    rows: [
        ['A', 10],
        ['B', 25],
        ['C', 18],
    ],
};

export function VegaLiteExample() {
    const theme = useCssTheme();

    return (
        <VegaVisual
            spec={spec}
            data={data}
            theme={theme}
            style={{ height: 320 }}
        />
    );
}

Basic component usage (Flint)

import { VegaVisual, useCssTheme } from '@microsoft/fabric-visuals';
import type { VisualizationSpec } from '@microsoft/fabric-visuals';
import type { DataTable } from '@microsoft/fabric-visuals-core';

const spec: VisualizationSpec = {
    "chartType": "Bar Chart",
    "encodings": {
        "y": {
            "field": "product"
        },
        "x": {
            "field": "revenue"
        }
    }
};

const data: DataTable = {
    columns: [
        { name: 'product', semanticType: 'Category' },
        { name: 'revenue', semanticType: 'Revenue', format: '#,##0.00' },
    ],
    rows: [
        ['A', 10],
        ['B', 25],
        ['C', 18],
    ],
};

export function FlintExample() {
    const theme = useCssTheme();

    return (
        <VegaVisual
            spec={spec}
            data={data}
            theme={theme}
        />
    );
}

Common pitfalls and strategies

The following is a list of pitfalls that may arise when authoring a Vega-Lite specification for the VegaVisual to render:

DO NOT put config in Vega-Lite spec JSON files

VegaVisual always applies its built-in theme. A custom config defined within the the given spec is overridden.

// ✅ DO: Pass overrides via configVegaLite prop
<VegaVisual spec={spec} theme={theme} configVegaLite={{ axis: { labelAngle: -45 } }} />

// ❌ DON'T: Put config inside the Vega-Lite spec
const spec = { mark: "bar", config: { axis: { labelAngle: -45 } }, ... }; // config is ignored

Hide a legend with legend: null

To blank a legend, set legend: null on the encoding channel (e.g. the size channel of a bubble chart). This is honored even when another channel encodes the same field. VegaVisual auto-applies column formats to legends, but it will not resurrect a legend you explicitly suppressed with legend: null.

// ✅ DO: Suppress the size legend explicitly — the merged legend stays hidden
{ "encoding": { "size": { "field": "Score", "legend": null }, "color": { "field": "Score" } } }

// ❌ DON'T: Omit legend and expect no legend — a formatted, merged legend may appear
{ "encoding": { "size": { "field": "Score" }, "color": { "field": "Score" } } }

Bracket escaping differs between encoding and calculate

// ✅ DO: Use \\[ in encoding field references
{ "encoding": { "x": { "field": "Date\\[MonthName\\]" } } }

// ✅ DO: Use raw brackets in calculate expressions
{ "calculate": "datum['Date[MonthName]']", "as": "Month" }

// ❌ DON'T: Use raw brackets in encoding fields
{ "encoding": { "x": { "field": "Date[MonthName]" } } }

// ❌ DON'T: Use \\[ escaping in calculate expressions
{ "calculate": "datum['Date\\[MonthName\\]']", "as": "Month" }

Dual Y-axis charts need nested layers

// ✅ DO: Wrap each series in its own layer
{
    "resolve": { "scale": { "y": "independent" } },
    "layer": [
        { "layer": [{ "mark": "line", ... }, { "mark": "point", ... }] },
        { "layer": [{ "mark": "line", ... }, { "mark": "point", ... }] }
    ]
}

Embeddable (CSP-Safe) Variant

For environments with restrictive Content Security Policy (sandboxed iframes, M365 Copilot widgets, VS Code MCP Apps), use EmbeddableVegaVisual from the ./embeddable entry point.

Why

VegaVisual relies on Vega's default expression compiler which uses new Function(). This is blocked in CSP environments that disallow unsafe-eval. When VegaVisual detects this restriction, it renders an error message instead of a blank chart.

EmbeddableVegaVisual uses vega-interpreter for expression evaluation — a CSP-safe alternative that interprets expression ASTs at runtime without code generation. More details about this implementation is in the Vega documentation, under Expression Interpreter.

Usage

import { EmbeddableVegaVisual, useCssTheme } from '@microsoft/fabric-visuals/embeddable';
import type { VisualizationSpec } from '@microsoft/fabric-visuals/embeddable';

export function SecureWidget() {
    const theme = useCssTheme();

    return (
        <EmbeddableVegaVisual
            spec={spec}
            data={data}
            theme={theme}
            style={{ height: 320 }}
        />
    );
}

API

EmbeddableVegaVisual accepts the same props as VegaVisual (VegaVisualProps) and exposes the same VegaVisualHandle ref. It is a drop-in replacement — switch the import path and component name.

The ./embeddable entry re-exports all types from the main entry (VisualizationSpec, VegaVisualEventCallback, VegaVisualProps, etc.) plus useCssTheme, so you only need one import path.

Tradeoffs

| | VegaVisual | EmbeddableVegaVisual | |---|---|---| | CSP-safe | ❌ Requires unsafe-eval | ✅ No unsafe-eval needed | | Bundle size | Smaller | +~6 KB gzipped | | Expression performance | Native (compiled) | Interpreted (negligible for typical charts) | | API surface | Full | Identical |

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See full Microsoft Open Source Code of Conduct