Data Grid
Last updated
Last updated
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.
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:
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:
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:
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:
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:
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:
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:
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.
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:
Use one of the predefined color names
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:
While this is usually enough for most use cases, you may however also define custom colors with the following structure:
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:
The supported predefined color names are:
gray or grey
orange
yellow
green
blue
purple
pink
red
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:
You may however also use any valid CSS color, as follows:
The Data Grid component offers the following configuration properties.
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
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
Text color
string
black
Font color in the grid, except the header row.
The Data Grid does not offer any events.
The Data Grid exposes the following API in the JavaScript runtime environment.
columnWidths
number | number[] | null
Current value of the "Column widths" property.
data
GridData | null
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
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
Defines the data that is displayed in the grid. Please refer to the section for more details on accepted structures.
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 section.
Current value of the "Data" property, please refer to the section for more details.
Sets the displayed data to the provided structure. See the section for more details about the expected structures.
Sets the legend to the provided value. See the section for more details.
