Data Table updates in Carbon React v5.22.0

The Carbon team has some exciting updates to share regarding updates to the DataTable component in the latest version of carbon-components-react 🎉🎉🎉 Starting in v5.22.0, we’re beginning to tackle more and more of the common state-related behavior that teams have added to the stateless functional components that already exist.

As a result, this new update includes added support for the most common of these patterns, namely:

  • Sorting by a table header
  • Filtering rows by search
  • Row selection for supporting the batch action menu bar
  • Row expansion to enable you to toggle additional row content

You can check out the component storybook and the new component documentation for the full API documentation on how to use DataTable.

Added Data Table behavior 🎉

For those about to dive into this brave new Data Table world, I wanted to offer some context as to why the team is approaching this state container in such a weird way versus just supporting a single component that works for all use-cases.

Render Props

DataTable is one of our first components that makes use of the render prop pattern. For those that aren’t used to this pattern, all this means is that DataTable doesn’t actually render any UI directly. Instead, it encapsulates all the behavior of the table and leaves the construction of the table markup for you to tackle.

In practice, this looks like:

Which, honestly, is a ton of markup! However, if you look closely I think you’ll find that the table is made up of components like TableHead, TableRow, or TableCell that directly correspond to the elements you’d typically use to construct a table.

The rationale behind this verbosity is to try and stay as flexible as possible. Ultimately, we realize that we can’t solve for every possible Data Table use-case, but we still want to try and provide the tools needed for both the visual representation and behavior of this component.

In terms of the visual representation of the table, that’s what we’re hoping the stateless functional components introduced in carbon-components-react@5.1 will help out with. With respect to the behavior of the table, that’s why we are introducing the idea of using render props and prop getters to wire up the state behavior for your table.

Prop Getters

For those taking a look at the above snippet and going 🤔 over this snippet:

<TableHeader {...getHeaderProps({ header })}>

This is how the DataTable coordinates its internal state behavior with the various pieces of the Table UI that you’re choosing to render.

In the case of headers, getHeaderProps allows you to get the props required for a specific header and apply them to the TableHeader directly. This could include things like onClick handlers for listening to when to sort by a given table header, key props for rendering in a list, or even WAI-ARIA related labels to help screen readers convey the sort state of a table.

If you want to attach additional event listeners, go for it! Just make sure to add them directly to the getHeaderProps call so that we can help coordinate any kind of conflicting event listeners that DataTable and you need to both use.

There are a variety of different prop getters for the different types of state you can wire up for DataTable, and you can read more about them in the DataTable readme file.


So if DataTable is one big state container, how do we actually read from the state that’s being updated? Thankfully, inside of the render prop function you also get access to all of the relevant state information that you would need for knowing which rows to header, or which rows are selected.

You can find a detailed list of all the state values passed into the render prop here.

Row expansion in the Carbon Data Table


For those wanting to programmatically update the internal state of DataTable, you’ll be pleased to here that the render prop also has actions to help control the state.

You can find a detailed list of all the actions available here, but at a high-level you can do the following with these actions:

  • Sort by a given header key
  • Toggle the selection state of all the rows in a table
  • Toggle the selection state of a single row in a table
  • Toggle the expansion state of a single row
  • Handle input change of a table search field

Wrapping up

Checkout the Carbon Design System site for more info on Data tables!

So what we’ve talked about above is what’s being introduced in the newest version of carbon-components-react today! 🎉🎉🎉 We are so excited to see how people use the new DataTable patterns that we’re adding in to our React library.

If you have any questions, concerns, or bug reports feel free to make an issue over on our GitHub repository and we’ll make sure to help out every way that we can. Look for more DataTable updates in the future!