How to Create a Scrollable Table in shadcn/ui?

Creating a scrollable table with a fixed header is a common requirement in web applications for displaying large datasets effectively. In this guide, we will walk you through the process of implementing a scrollable table using shadcn/ui and Tailwind CSS. We will also resolve a common issue where the table body gets condensed in the first column.

Why Use Scrollable Tables?

Scrollable tables improve the user experience when dealing with large datasets by:

Enhancing Usability: Fixed headers allow users to understand the data even when scrolling.
Improving Aesthetics: Preventing tables from stretching beyond the visible area ensures a clean UI.
Boosting Performance: Keeping the header static and rendering a scrollable body minimizes reflows and repaints, especially for large data.

Step-by-Step Guide

Step 1: Modify the `Table` Component in `shadcn/ui`

To make the table scrollable while maintaining proper structure, update the Table component as follows:

// other code ...
const Table = React.forwardRef(({ className, containerClassname, ...props }, ref) => (
  <div className={cn('relative w-full', containerClassname)}>
    <table ref={ref} className={cn('w-full caption-bottom text-sm', className)} {...props} />
  </div>
))
// other code ...

Key Notes:

containerClassname: This prop allows additional container styles to be passed, making the table more customizable.
relative & w-full: Ensure the table stays within the container boundaries.

Step 2: Implement the Scrollable Table

Using the updated Table component, create the TransactionTable component. Here is the updated code:

export default function TransactionTable() {
  return (
    <Table className="" containerClassname="h-fit max-h-80 overflow-y-auto relative">
      <TableHeader className="">
        <TableRow>
          <TableHead className="w-1/5 px-2 py-1">Date</TableHead>
          <TableHead className="w-2/5 px-2 py-1">Title</TableHead>
          <TableHead className="w-1/5 px-2 py-1">Category</TableHead>
          <TableHead className="w-1/5 px-2 py-1">Amount</TableHead>
        </TableRow>
      </TableHeader>

      <TableBody className="block h-[500px] overflow-y-auto">
        {transactions.map((t) => (
          <TableRow key={t.id} className="">
            <TableCell className="px-2 py-1">{t.date}</TableCell>
            <TableCell className="px-2 py-1">{t.title}</TableCell>
            <TableCell className="px-2 py-1">{t.category}</TableCell>
            <TableCell className="px-2 py-1">{t.amount}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}

Highlights of the Code:

Fixed Header: The header remains static, providing context to users while scrolling.
Scrollable Body: The body is scrollable with a height limit (max-h-80) to ensure better usability.
Responsive Layout: Consistent column widths using Tailwind classes like w-1/5 and w-2/5 ensure proper alignment.

Best Practices for Scrollable Tables

Here are some tips to enhance the implementation:

1. Set Maximum Height

Always define a max-h-[value] for the table body to avoid stretching on larger screens.

2. Use Tailwind Utilities

Leverage Tailwind classes like overflow-y-auto, relative, and block to control scrolling behavior effectively.

3. Optimize Column Widths

Set widths for each column to maintain proper alignment between the header and body.

4. Test Responsiveness

Ensure the table is tested across devices and screen sizes for optimal performance.

Example Output

After implementing the steps, your table will:

Have a fixed header for easy navigation.
A scrollable body confined within a specific height.
Consistent column widths and responsive design.

Troubleshooting Common Issues

1. Condensed First Column

Ensure proper column widths are set using Tailwind's w-[percentage] classes.

2. Scrolling Doesn’t Work

Verify that overflow-y-auto is applied to the TableBody.

3. Header Misalignment

Use consistent padding (px-2 py-1) and width classes across header and body cells.

Conclusion

By following this guide, you can create a well-structured, responsive scrollable table using shadcn/ui and Tailwind CSS. This approach ensures a seamless user experience, especially for data-heavy applications.

If you encounter any issues or have suggestions, feel free to share them in the comments.