Columns in React Data Grid

The Syncfusion® React Data Grid component organizes data in a table using columns. Each column requires a valid field name to support key grid features such as sorting, filtering, and editing. Organizing data into columns allows efficient interaction and manipulation within the grid.

Defining columns

Columns can be manually configured by setting properties such as width, header text, alignment, formatting, and more, or they can be generated automatically from the data source without requiring manual setup.

Manually define columns

Columns are configured using the Columns component, where each column defines attributes such as field, headerText, type, width, and more. The headerText property specifies the title of the column header cell. When header text is not provided, the grid defaults to displaying the corresponding field name as the column title.

Auto generated columns

When the columns are not defined in the Columns property, the grid automatically generates columns by extracting field names from the data source. Each field becomes a column, with the header text set to the corresponding field name.

Custom auto generated columns

Auto-generated columns can be customized at runtime using the grid onDataLoad event to modify properties such as format, textAlign, width, and headerText. In the example below, specific fields are customized as follows:

• Book ID: Right-aligned, width: 95px.
• Title: Width: 170px.
• Author: Width: 150px.
• Genre: Width: 125px.
• Published Year: Right-aligned, width: 140px.
• Rating: Right-aligned, width: 85px.

Complex binding

The Data Grid component supports nested data structures from local arrays and remote APIs. To bind and display hierarchical properties, use dot (.) notation within the field property.

Local data

For local datasets with nested objects, use dot (.) notation in the field property to access inner-level properties.

<Column field='Name.FirstName' headerText='First Name' width='70' />
<Column field='Name.LastName' headerText='Last Name' width='70' />

Remote data

To bind nested data from remote APIs (e.g., OData), use DataManager with a Query method to fetch expanded entities. Columns can access nested fields using dot (.) notation (e.g., Employee.City) for direct binding.

const data = new DataManager({
    adaptor: new ODataV4Adaptor(),
    crossDomain: true,
    url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Orders/'
});
const query = new Query().expand('Customer');

...

<Column field='Customer.CustomerID' headerText='Customer ID' width='100' />

To bind columns from related entities such as Employee and Customer (e.g., Employee.Name, Customer.CustomerID) when using DataManager, apply the expand method to include those entities in the query: new Query().expand('Employee').expand('Customer').

Rendering deeply nested columns

The Data Grid component supports traversal through deeply nested data structures using extended dot (.) notation in the field property. This allows direct access to multi-level properties, such as customer profiles or geo-location mappings.

<Column field="Customer.Details.Name" headerText="Customer Name" width="110" />
<Column field="Customer.Details.Address.City" headerText=" Ship City" width="90" />
<Column field="Customer.Details.Address.Country" headerText="Ship Country" width="100" />

Width

The width property sets column width using auto, pixel (px), or percentage (%) values. It helps optimize layout and readability by adjusting columns based on container size.

Auto width

Automatically adjusts each column’s width based on its content. When content exceeds available space, it is truncated with an ellipsis (...).

• Single column: A single column that dynamically adjusts its width to accommodate its content.

• Multiple columns: When widths are unspecified, space is allocated equally. Each column adjusts to its content's width, and the grid expands to accommodate all columns without scrollbars.

In this example, the "Ship Address" column width set as "auto".

Pixel width

Sets a column’s width to a fixed pixel value, ensuring consistent sizing regardless of content or layout changes.

• Single column: Maintains a fixed width, which may lead to content truncation or unused space.

• Multiple columns: Each column retains its defined size, creating a structured and predictable layout.

Percentage width

Defines column width as a percentage of the available grid space, allowing dynamic scaling across different screen sizes or container dimensions.

• Single column: Adjusts with layout changes, maintaining its proportional width.

• Multiple columns: Percentage values are distributed across columns. In mixed setups (with pixel or auto widths), remaining space is allocated proportionally to percentage based columns.

In this example, the "Item" column width set as "25%".

Adjusting column widths externally

This example shows how to dynamically adjust column widths using auto, pixel, or percentage values, with each column styled for clarity.

• Columns without a set width automatically divide the available grid space equally.
• A horizontal scrollbar appears when the total column width exceeds the grid container.

Text alignment

The textAlign property adjusts text positioning within column cells, enhancing visual clarity and consistency. By default, text aligns to the left, but alternative alignments can be applied to meet specific layout requirements.

Visibility

By default, all columns in the grid are visible. To hide a specific column, set its visible property to false in the Column configuration. For example, the "Protein" column can be hidden by setting visible property to false.