Data Grid

The Data Grid is a versatile and dynamic way to display tabular data of any size. Unlike the Table component, which has a fixed number of columns, the Data Grid can adapt to a variable amount of columns. In addition, it allows you to add color highlights to cells, making it easy to draw attention to important data or identify patterns in your information.

Example of the Data Grid component with color highlights

Data structure

The Data Grid component can handle input data in a variety of structures. Depending on your needs, you can choose to use an object with “headers” and “records” keys, an array of objects, or an array of arrays to populate the Data Grid with your data. We’ll cover each of these three options in detail and with examples, so you can choose the one that works best for your specific use case.

We however first need to understand how a single cell value is described across all possible input structures. A cell value can be provided as follows:

type GridCellValue = string | {
  html?: string;
  markdown?: string;
  text?: string;
  color?: DataGridColor;
  alignment?: 'left' | 'center' | 'right';
  weight?: 400 | 500 | 600 | 700;
}

The most basic way of providing a cell value is expressing it as a simple string. For example, 'city' is a valid cell value and will be displayed as-is in the grid. The Data Grid however allows to describe a cell value with an object structure, in case special formatting should be applied. Firstly, there are three possible objects keys to provide the actual content of a cell:

• text: This property expects a string, which will be displayed as-is in the particular cell. This is perfect for cases where a basic textual value should be displayed with additional formatting.

• markdown: Text provided via this key will be processed as markdown text. For example, you may provide the string '*city*' to render italic text in the grid.

• html: With this key, you may provide custom HTML code that will be rendered as cell value. This offers highly customized value rendering for complex use cases.

On top of the content, you may use the following object keys to apply value formatting:

• color: This property allows to provide a font-, background- and/or border-color for the particular cell. This mechanism is described in more detail in this section.

• alignment: This property allows to define the text alignment within the particular cell. Allowed values are 'left', 'center' and 'right'.

• weight: Using this property, you may adjust the font weight of the particular cell. Allowed values are the numbers 400, 500, 600 and 700.

Illustrating this structure with an example, the following object describes the italic text "Hello world", which is center-aligned and has a green background:

{
  html: '<i>Hello world</i>',
  alignment: 'center',
  color: 'green',
}

After understanding the definition of a single cell value, let us now dive into the three possible structure for defining the data of the entire grid:

1. Object with "headers" and "records" array

This structure is perfect for use cases where you would like to render data from SQL actions in the grid. It is described by the following structure:

interface ObjectGridData {
  headers: GridCellValue[];
  records: GridCellValue[][];
}

In this structure, the "headers" array will be used to populate the first row, while the arrays in the "records" array are populating the rest of the grid. This allows to funnel the result of data source actions directly into the grid without any further manipulation or transformation. An example of such structure could look as follows:

{
  headers: ['city', 'country', 'population'],
  records: [
    ['Tokyo', 'Japan', { text: '37,468,000', alignment: 'center' }],
    ['Delhi', 'India', { text: '28,514,000', alignment: 'center' }],
    ['Shanghai', 'China', { text: '25,582,000', alignment: 'center' }],
    ['Sao Paulo', 'Brazil', { text: '21,650,000', alignment: 'center' }],
    ['Mexico City', 'Mexico', { text: '21,581,000', alignment: 'center' }],
  ],
}

2. Array of objects

This structure is most human-readable, as cell values are directly associated with column headers. When providing an array of objects, the object keys will be interpreted as column headers, while the object values will be used as cell values. Using the same example of "city populations" from the previous section, an example of this structure could look as follows:

[
  {
    city: 'Tokyo',
    country: 'Japan',
    population: { text: '37,468,000', alignment: 'center' },
  },
  {
    city: 'Delhi',
    country: 'India',
    population: { text: '28,514,000', alignment: 'center' },
  },
  {
    city: 'Shanghai',
    country: 'China',
    population: { text: '25,582,000', alignment: 'center' },
  },
  {
    city: 'Sao Paulo',
    country: 'Brazil',
    population: { text: '21,650,000', alignment: 'center' },
  },
  {
    city: 'Mexico City',
    country: 'Mexico',
    population: { text: '21,581,000', alignment: 'center' },
  },
]

3. Array of arrays

The third accepted structure resembles the most with a data grid: an array of arrays. The first array element will be interpreted as header row, while all following arrays will be used as column values. The "array of arrays" version of the previous example will look as follows:

[
  ['city', 'country', 'population'],
  ['Tokyo', 'Japan', { text: '37,468,000', alignment: 'center' }],
  ['Delhi', 'India', { text: '28,514,000', alignment: 'center' }],
  ['Shanghai', 'China', { text: '25,582,000', alignment: 'center' }],
  ['Sao Paulo', 'Brazil', { text: '21,650,000', alignment: 'center' }],
  ['Mexico City', 'Mexico', { text: '21,581,000', alignment: 'center' }],
]

The Data Grid component is fairly lenient about missing cell values in the provided structure. For example, in case not all objects in an "array of objects" structure contain a specific key, it will be filled up with an empty cell. Same applies to an "array of arrays" structure, in which the individual array elements have different lengths. In this case, the longest array will be considered and all other rows will be filled up with empty cells.

Color highlights

The previous section already introduced the ability to apply formatting to a cell, by expressing the cell value as an object structure. With regards to coloring, you can choose between two alternatives:

1. Use one of the predefined color names

2. Provide custom color codes for background, border and/or font

The first option is simple: you just need to provide one of the color names listed below, and the Data Grid will color the background accordingly. An example of defining a cell value with green highlighting may look as follows:

{
  text: "Using the predefined 'green' color",
  color: 'green',
}

While this is usually enough for most use cases, you may however also define custom colors with the following structure:

interface DataGridCustomColors {
  background?: string;
  border?: string;
  text?: string;
}

This structure allows you to provide any valid CSS color code as background-, border- and/or text-color. An example of a cell value with white font on black background looks as follows:

{
  text: 'White text on black background',
  color: {
    background: '#000',
    text: 'white',
  },
}

The supported predefined color names are:

• gray or grey

• orange

• yellow

• green

• blue

• purple

• pink

• red

Legend

The legend in the footer of the grid allows to describe your color highlights. A legend entry always consists of two parts: a color code and a label. The color code is visualized with a small, colored square, while the label is rendered as text next to it. These entries must be provided in a dictionary that maps the label (i.e. value) to the color code (i.e. key).

The following example describes two legend entries that are based on the default color set:

{
  green: 'Green highlight',
  red: 'Red highlight',
}

You may however also use any valid CSS color, as follows:

{
  '#000': 'Black highlight',
  'rgb(0, 0, 0)': 'Another black highlight',
}

Properties

The Data Grid component offers the following configuration properties.

Property	Type	Default value	Behavior
Column widths	number | number[]	[240, 90]	Sets the widths in pixels of the grid columns. In case one number is provided, all columns will have the given width. An array of numbers will apply these numbers to the columns in order, and all following columns will use the last array element.
Data	GridData	Example data	Defines the data that is displayed in the grid. Please refer to the Data structure section for more details on accepted structures.
Data export	boolean	true	When set to true, the user will be able to export the displayed data to CSV or XLSX, by using the download-icon in the footer.
First row is header	boolean	true	When set to true, the first row is displayed with bold font, and behaves sticky when the grid is scrolled vertically.
Fixed column count	number	1	Defines the number of columns which are fixed and therefore behave sticky when the grid is scrolled horizontally.
Header background color	string	white	Background color of the header row. Only relevant when "First row is header" is set to true.
Header text color	string	black	Text color in the header row. Only relevant when "First row is header" is set to true.
Legend	Record<string, string>	Example legend	Defines the legend entries that will be displayed in the footer. Should be a mapping from "color code" to "color label". See more details in the Legend section.
Text color	string	black	Font color in the grid, except the header row.

Events

The Data Grid does not offer any events.

API

The Data Grid exposes the following API in the JavaScript runtime environment.

Property / Function	Type	Behavior
columnWidths	number | number[] | null	Current value of the "Column widths" property.
data	GridData | null	Current value of the "Data" property, please refer to the Data section for more details.
dataExport	boolean	Current value of the "Data export" property.
firstRowIsHeader	boolean	Current value of the "First row is header" property.
fixedColumnCount	number | null	Current value of the "Fixed column count" property.
legend	Record<string, string> | null	Current value of the "Legend" property.
setColumnWidths(value)	(value: number | number[] | null) => void	Sets the column widths to the provided number(s) in pixels.
setData(value)	(value: GridData) => void	Sets the displayed data to the provided structure. See the Data section for more details about the expected structures.
setDataExport(value)	(value: boolean) => void	Sets the data export flag to the provided value.
setFirstRowIsHeader(value)	(value: boolean) => void	Sets the first-row-is-header flag to the provided value.
setFixedColumnCount(value)	(value: number | null) => void	Sets the fixed column count to the provided value.
setLegend(value)	(value: Record<string, string> | null) => void	Sets the legend to the provided value. See the Legend section for more details.