@microsoft/fabric-datagrid-web-components

Framework-agnostic Web Component for the Fabric Apps - Analytics DataGrid. This package wraps the React DataGrid component as a standard custom element (<fabric-data-grid>), bundling React internally so consumers do not need a React dependency.

For the Vega-Lite visualization web component, see @microsoft/fabric-visuals-web-components.

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.

Installation

npm install @microsoft/fabric-datagrid-web-components

Sibling dependency

• @microsoft/fabric-visuals-core — provides DataTable, VisualTheme, and design tokens consumed by properties of this component.

Note: React and ReactDOM are bundled internally — you do not need to install them.

Architecture

@microsoft/fabric-visuals-core            (framework-agnostic types & tokens)
        ↓
@microsoft/fabric-datagrid                (React DataGrid component)
        ↓
@microsoft/fabric-datagrid-web-components (this package — wraps React as a custom element)
        ↓
@microsoft/fabric-datagrid-angular        (optional Angular wrapper)

Quick Start

<script type="module">
  import { registerFabricDataGrid } from '@microsoft/fabric-datagrid-web-components';

  registerFabricDataGrid();

  const el = document.querySelector('fabric-data-grid');
  el.columns = [
    { id: 'name', header: 'Name' },
    { id: 'age', header: 'Age', sortable: true },
  ];
  el.data = [
    { name: 'Alice', age: 30 },
    { name: 'Bob', age: 25 },
  ];
</script>

<fabric-data-grid style="height: 400px"></fabric-data-grid>

Public API

registerFabricDataGrid(tagName?)

Registers the custom element with the browser. Must be called before using <fabric-data-grid> in the DOM.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | tagName | string | 'fabric-data-grid' | Custom element tag name. Override to avoid conflicts. |

Returns: true if registration occurred, false if the tag was already registered to this class.

Throws: If the tag is already registered to a different constructor.

FabricDataGridElement

The custom element class (extends HTMLElement). All properties are set as JavaScript object properties.

Properties

| Property | 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. | | 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. |

Events

| Event | Detail 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. |

Re-exported DataGrid Types

• DataGridProps, GridColumnDef, Row, CellValue, SortConfig, SortDirection, CellRange, FilterChangeDetail

Using with Angular

For Angular applications, use the @microsoft/fabric-datagrid-angular package which provides a thin Angular wrapper (<fabric-data-grid-ng>) with @Input/@Output bindings. See its README for details.