Data Grid
Allows users to interact with data in a tabular format.
import '@vonage/vivid/data-grid';
import '@vonage/vivid/data-grid-row';
import '@vonage/vivid/data-grid-cell';
or, if you need to use a unique prefix:
import { registerDataGrid } from '@vonage/vivid';
registerDataGrid('your-prefix');
Data Grid Row and Data Grid Cell sub-components are registered automatically in the same function.
<script setup lang="ts">
import { VDataGrid, VDataGridRow, VDataGridCell } from '@vonage/vivid-vue';
</script>
<template>
<VDataGrid>
<VDataGridRow>
<VDataGridCell>Data 11</VDataGridCell>
<VDataGridCell>Data 12</VDataGridCell>
<VDataGridCell>Data 13</VDataGridCell>
</VDataGridRow>
<VDataGridRow>
<VDataGridCell>Data 21</VDataGridCell>
<VDataGridCell>Data 22</VDataGridCell>
<VDataGridCell>Data 23</VDataGridCell>
</VDataGridRow>
</VDataGrid>
</template>
Use the no-tabbing
attribute to remove the component from the tab order.
Use the focusRowIndex
and focusColumnIndex
to determine which row or cell to set focus on when the Data Grid component receieves focus.
In the example below, change the value of the row / column index and then tab into the Data Grid.
The cell-click
event is fired when a cell is clicked on or when the enter or space key is pressed on a focused cell.
Event details: { cell, row, isHeaderCell, columnDataKey }
Use the rowsData
property to provide the component with the data (an array
or objects
) to be displayed.
If not used in conjuction with column defintions (title
), text displayed in the column headers will be the data keys of the object.
The rowsData
property provides an alternative way to populate the data grid with content.
However, we recommend using the Data Grid Row and Data Grid Cell sub-components to construct the content declaratively. This approach offers greater flexibility, allowing you to incorporate non-text-based elements such as other components or HTML elements (see Select in grid use case).
Use the columnDefinitions
property to programmatically configure the column headers that are generated when using rows-data
. See the ColumnDefinition interface for more information.
The sortable feature doesn't actually sort the data, it only changes the visual representation of the column header. See the sorting use case for more information.
Use the generate-header
property to programmatically define the type of grid header that is generated when using rows-data
.
The ViewTemplate
s used to render rows, cells and header cells can be customised using the following properties:
rowItemTemplate
cellItemTemplate
headerCellItemTemplate
You need to use html
from fast-element
.
<vwc-data-grid class="data-grid"></vwc-data-grid>
<script>
import { html } from '@microsoft/fast-element';
const grid = document.querySelector('.data-grid');
grid.rowItemTemplate = html`<div>All rows will look like me!</div>`;
grid.cellItemTemplate = html`<div>All cells will look like me!</div>`;
grid.headerCellItemTemplate = html`<div>
All header cells will look like me!
</div>`;
grid.rowsData = [
{ data1: 'data11', data2: 'data12' },
{ data1: 'data21', data2: 'data22' },
];
</script>
Use the rowElementTag
to set the element tag for header row cells. If not set, the default tag vwc-data-grid-cell
will be used.
When Row is set to sticky there's a default canvas background-color.
Use --data-grid-row-background
to change the sticky row background-color.
When a grid has the fixed-columns
attribute, fixed columns cells have a default canvas background-color.
Use --data-grid-cell-background
to overwrite the default background-color.
Use --data-grid-cell-block-size
to change the cell's block-size
.
By default, header cells have a fixed height while data cells have a dynamic height based on content.
Use --data-grid-cell-white-space
to change the cell's white-space
.
By default, header cells will not wrap text (nowrap
), while data cells will wrap text (normal
).
Properties
Name | Type | Description |
---|---|---|
cellItemTemplate | ViewTemplate |
Templete to use when rendering cells |
columnDefinitions | ColumnDefinition[] |
Configure the grid header columns |
focusColumnIndex | number |
Index of column to be focused on when the Data Grid receives focus |
focusRowIndex | number |
Index of row to be focused on when the Data Grid receives focus |
generateHeader | enum: default , sticky , none |
Type of header to be generated |
headerCellItemTemplate | ViewTemplate |
Templete to use when rendering grid header cells |
grid-template-columns | string |
Sets the width of the columns |
no-tabbing | boolean |
Remove the grid from the tab order |
rowsData | object[] |
Content of the grid in data format |
rowElementTag | string |
Element tag for header rows |
rowItemTemplate | ViewTemplate |
Templete to use when rendering rows |
selection-mode | enum: none , single-row , multi-row , single-cell , multi-cell |
Set the selection mode |
fixed-columns | number |
Sets the number of columns fixed to the left when horizontal scrolling |
Interfaces
ColumnDefinition
Name | Type | Description |
---|---|---|
columnDataKey |
string |
The property from which the data of the column is taken from |
title |
string |
The title of the column |
headerCellTemplate |
ViewTemplate |
A custom template for a header cell |
headerCellInternalFocusQueue |
boolean |
Indicates whether the header cell has in internal focus queue. This should be set to true for header cells that host controls that need to use arrow keys or have multiple focusable internal elements. When the user hits the Enter or F2 key the element specified by the headerCellFocusTargetCallback function will be focused (see keyboard interactions described here). |
headerCellFocusTargetCallback |
(cell) => HTMLElement |
Callback function that takes the cell node as a parameter and returns the HTMLElement to focus in a custom cell. This enables authors to direct focus in a custom cell with interactive elements. When headerCellInternalFocusQueue is false this function is called when the cell is first focused to immediately move focus to a cell element, for example a cell that contains a button could move focus directly to the button when focused. When headerCellInternalFocusQueue is true this function is called when the user hits Enter or F2. |
cellTemplate |
ViewTemplate |
A custom template for a cell |
cellInternalFocusQueue |
boolean |
Indicates whether the cell has in internal focus queue. This should be set to true for cells that host controls that need to use arrow keys or have multiple focusable internal elements. When the user hits the Enter or F2 key the element specified by the cellFocusTargetCallback function will be focused (see keyboard interactions described here). |
cellFocusTargetCallback |
(cell) => HTMLElement |
Callback function that takes the cell node as a parameter and returns the HTMLElement to focus in a custom cell. This enables authors to direct focus in a custom cell with interactive elements. When cellInternalFocusQueue is false this function is called when the cell is first focused to immediately move focus to a cell element, for example a cell that contains a button could move focus directly to the button when focused. When cellInternalFocusQueue is true this function is called when the user hits Enter or F2. |
isRowHeader |
boolean |
Whether this column is the row header |
sortable |
boolean |
Whether this column is sortable |
sortDirection |
'none' | 'ascending' | 'descending' | 'other' |
Define the column's sort direction |
Properties
Name | Type | Description |
---|---|---|
aria-selected |
string , true , false |
Selected state of row |
row-type |
enum: default , header , sticky-header |
Selected state of row |
Events
Name | Type | Bubbles | Composed | Description |
---|---|---|---|---|
row-focused |
CustomEvent<HTMLElement> |
Yes | Yes | Fires a custom 'row-focused' event when focus is on an element (usually a cell or its contents) in the row |
Properties
Name | Type | Description |
---|---|---|
selected |
true , false |
Selected state of cell |
sort-direction |
ascending , decending , none , other |
Sort state of the header cell |
Events
Name | Type | Bubbles | Composed | Description |
---|---|---|---|---|
cell-focused |
CustomEvent<HTMLElement> |
Yes | Yes | Fires a custom 'cell-focused' event when focus is on the cell or its contents |
sort |
CustomEvent<{columnDataKey: string, ariaSort: string | null, sortDirection: string | null}> |
Yes | Yes | Event that fires when a sortable column header is clicked |
cell-click |
CustomEvent<{cell: HTMLElement, row: HTMLElement, isHeaderCell: boolean, columnDataKey: string}> |
Yes | Yes | Event that fires when a cell is clicked |