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.

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.

Events

The Data Grid does not offer any events.

API

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

Last updated