@microsoft/fabric-visuals-angular
v5.4.0
Published
Vega-Lite visualization component for Fabric Apps - Analytics (Angular bindings)
Readme
@microsoft/fabric-visuals-angular
Angular 21 component for the Fabric Apps - Analytics Vega-Lite visualization system. This package provides a thin Angular wrapper around the <fabric-vega-visual> web component from @microsoft/fabric-visuals-web-components, offering signal-backed Angular inputs and Angular outputs:
<fabric-vega-visual-ng>— Vega-Lite visualization component
For the DataGrid Angular component, see
@microsoft/fabric-datagrid-angular.
All rendering logic is handled by the underlying web component, which internally uses React.
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.
Architecture
@microsoft/fabric-visuals-core (framework-agnostic types & tokens)
↓
@microsoft/fabric-visuals (React VegaVisual component)
↓
@microsoft/fabric-visuals-web-components (<fabric-vega-visual> custom element, bundles React)
↓
@microsoft/fabric-visuals-angular (this package — <fabric-vega-visual-ng> Angular wrapper)Installation
npm install @microsoft/fabric-visuals-angularPeer dependencies
@angular/core>= 21.2.0 < 22.0.0@angular/common>= 21.2.0 < 22.0.0
Dependencies (installed automatically)
@microsoft/fabric-visuals-web-components— the<fabric-vega-visual>custom element (bundles React internally)@microsoft/fabric-visuals-core— providesDataTable,ColumnDef,VisualTheme, and design tokens
Public API
All exports come from the package entry point (@microsoft/fabric-visuals-angular):
Component: VegaVisualComponent
A standalone Angular 21 component (<fabric-vega-visual-ng>) that wraps the <fabric-vega-visual> web component. It forwards signal-backed Angular inputs to the web component's properties and bridges native vegaevent CustomEvents to an Angular output.
Inputs
| Input | Type | Required | Description |
|-------|------|----------|-------------|
| spec | VisualizationSpec \| string | yes | A Vega-Lite spec object or a JSON string. |
| theme | VisualTheme | yes | Semantic color theme from @microsoft/fabric-visuals-core. Bridges into Vega-Lite config so chart internals respond to the host's theme. Use lightThemeColors or darkThemeColors. |
| data | DataTable \| Record<string, DataTable> \| null | no | One table or named datasets. |
| selections | readonly SemanticSelection[] | no | Accepted source selection; omitted is local, [] is controlled and cleared. |
| selectableFields | readonly string[] | no | Raw identity fields, including eligible hidden keys. |
| groupOnKeys | Readonly<Record<string, readonly string[]>> | no | Key fields by field ID. With managed selections, a text value shared by more than one key is shown with a suffix. |
| isCrossHighlightActive | boolean | no | The highlight flag paired with the displayed datasets. |
| configVegaLite | VegaLiteConfig | no | Custom Vega-Lite configuration merged (deep) with the built-in base theme. |
| capabilities | VegaVisualCapabilities | no | Compilation and rendering options. |
| visualFraming | VisualFramingProps | no | Header, Copy action, chromeless mode, containerRootClassName for the internal React frame root, and containerClassName for the inner card surface. Apply dashboard grid/flex placement to the Angular host itself. |
Outputs
| Output | Type | Description |
|--------|------|-------------|
| vegaEvent | VegaVisualEventDetail | Fired for all visualization lifecycle events (render, error, vega log, spec update). |
Basic Usage
import { Component } from '@angular/core';
import { VegaVisualComponent } from '@microsoft/fabric-visuals-angular';
import type { DataTable } from '@microsoft/fabric-visuals-core';
import { lightThemeColors } from '@microsoft/fabric-visuals-core';
@Component({
selector: 'app-chart',
standalone: true,
imports: [VegaVisualComponent],
template: `
<fabric-vega-visual-ng
[spec]="spec"
[data]="data"
[theme]="theme"
(vegaEvent)="onEvent($event)"
[style.height.px]="400"
/>
`,
})
export class ChartComponent {
theme = lightThemeColors;
spec = {
$schema: 'https://vega.github.io/schema/vega-lite/v6.json',
mark: 'bar',
encoding: {
x: { field: 'city', type: 'nominal' },
y: { field: 'pop', type: 'quantitative' },
},
};
data: DataTable = {
columns: [
{ name: 'city', displayName: 'City' },
{ name: 'pop', displayName: 'Population' },
],
rows: [
['New York', 8336817],
['London', 8982000],
],
};
onEvent(event: any): void {
console.log('Vega event:', event);
}
}Event System
All events are emitted through the vegaEvent output as VegaVisualEventDetail.
VegaVisualEventDetail
interface VegaVisualEventDetail {
readonly type: VegaVisualEventType; // 'render' | 'error' | 'vega' | 'specUpdate'
readonly level: VegaVisualEventLevel; // 'error' | 'warn' | 'info' | 'debug'
readonly message: string;
readonly spec?: string; // present on specUpdate events
readonly args?: readonly unknown[]; // present on vega log events
}| Event type | When emitted |
|---|---|
| render | Vega View has finished rendering (level: info). |
| error | Compilation or runtime error occurred (level: error). |
| vega | A Vega runtime log message at any level (error/warn/info/debug). |
| specUpdate | The spec was updated externally. |
LOG_LEVEL_MAP
Maps friendly names to Vega numeric log level constants:
{ none: 0, error: 1, warn: 2, info: 3, debug: 4 }Re-exported Utilities
| Function | Description |
|----------|-------------|
| registerVbaFormatter() | Registers the vbaFormat custom format type with Vega. Idempotent. |
Component: DataGridComponent
A standalone Angular component (<fabric-data-grid-ng>) that wraps the <fabric-data-grid> web component.
Inputs
| Input | Type | Required | Description |
|-------|------|----------|-------------|
| columns | GridColumnDef[] | no | Column definitions. Auto-derived from DataTable data when omitted. |
| data | DataTable \| Row[] \| string | no | Data source: a DataTable, Row[] array, or URL string to fetch JSON. |
| selections | readonly SemanticSelection[] | no | Accepted row selection; omitted is local, [] is controlled and cleared. |
| selectableFields | readonly string[] | no | Raw row identity fields, including eligible hidden keys. |
| defaultSort | SortConfig[] | no | Initial sort configuration. Applied only on first mount. |
| rowHeight | number | no | Row height in pixels. Defaults to 40. |
| theme | VisualTheme | no | Semantic color theme from @microsoft/fabric-visuals-core. |
| pageSize | number | no | Rows per page. When set, pagination controls are shown. |
Outputs
| Output | Type | Description |
|--------|------|-------------|
| columnsChange | GridColumnDef[] | Fired when columns are resized or reordered. |
| rowToggle | string | Fired when a tree row is expanded/collapsed. Detail is the row ID. |
| filterChange | FilterChangeDetail | Fired when a column filter selection changes. |
Basic Usage
import { Component } from '@angular/core';
import { DataGridComponent } from '@microsoft/fabric-visuals-angular';
import type { GridColumnDef, Row } from '@microsoft/fabric-visuals-angular';
import { lightThemeColors } from '@microsoft/fabric-visuals-core';
@Component({
selector: 'app-table',
standalone: true,
imports: [DataGridComponent],
template: `
<fabric-data-grid-ng
[columns]="columns"
[data]="rows"
[theme]="theme"
[pageSize]="50"
(columnsChange)="onColumnsChange($event)"
[style.height.px]="600"
/>
`,
})
export class TableComponent {
theme = lightThemeColors;
columns: GridColumnDef[] = [
{ id: 'name', header: 'Name' },
{ id: 'age', header: 'Age', sortable: true },
];
rows: Row[] = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 },
];
onColumnsChange(cols: GridColumnDef[]): void {
console.log('Columns changed:', cols);
}
}Comparison with sibling packages
| Feature | React (@microsoft/fabric-visuals) | Web Component (@microsoft/fabric-visuals-web-components) | Angular (@microsoft/fabric-visuals-angular) |
|---------|-------------------------------------|-----------------------------------------------------|-----------------------------------------------|
| Element | <VegaVisual> (React component) | <fabric-vega-visual> (custom element) | <fabric-vega-visual-ng> (Angular component) |
| Props/Inputs | React props | JavaScript properties | Signal-backed Angular inputs |
| Events | onEvent callback prop | vegaevent CustomEvent | (vegaEvent) @Output() |
| View access | ref.current.view | el.view | — (access via underlying WC element) |
| Framework deps | React, ReactDOM | None (bundles React internally) | Angular >=21.2.0 <22.0.0 |
