Troubleshooting

First-run issues almost always fall into one of three categories: no measurable height, missing wrapper installs, or scroll container mode mismatches.

Minimum known-good table

import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader } from '@/components/ui/data-table'
import { localModel } from '@virtuoso.dev/data-table'

const rows = [
  { name: 'Standing Desk', category: 'Office' },
  { name: 'USB-C Dock', category: 'Peripherals' },
  { name: 'Mechanical Keyboard', category: 'Peripherals' },
]

const model = localModel({ data: rows })

export default function App() {
  return (
    <div className="space-y-3">
      <p className="text-sm text-muted-foreground">
        This is the minimum known-good layout: explicit height, installed wrapper import, and plain data.
      </p>

      <DataTable className="rounded-xl" model={model} style={{ height: 240 }}>
        <DataTableColumn field="name">
          <DataTableColumnHeader>Product</DataTableColumnHeader>
          <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
        </DataTableColumn>
        <DataTableColumn field="category">
          <DataTableColumnHeader>Category</DataTableColumnHeader>
          <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
        </DataTableColumn>
      </DataTable>
    </div>
  )
}

If this table renders but yours doesn’t, compare layout, imports, scroll mode, and model setup one piece at a time.

Symptom checklist

Symptom	Likely cause	Fix
The table is blank or only the header appears	The table has no measurable height	Set style={{ height: 400 }}, a fixed-height class, or give the custom scroll parent a real height
The shadcn imports fail	The registry wrapper has not been installed	Run the shadcn install command or import headless components directly from @virtuoso.dev/data-table
Rows do not scroll	The table is attached to the wrong scroll element	Remove customScrollParent, or pass the actual element with overflow: auto
The page scrolls and the table also scrolls	Two scroll modes are active	Choose the default table scroller, useWindowScroll, or customScrollParent, not multiple modes
Sticky columns look clipped	A wrapper has incompatible overflow or missing width	Check parent overflow, table width, and column min-width classes
Remote rows never appear	The fetch result shape is wrong or a request was aborted without retry	Return { rows, totalCount } for offset mode and pass the provided signal to your client

Import checks

The docs examples import from the shadcn wrapper:

import { DataTable } from '@/components/ui/data-table'

That path exists only after running the registry install. Without the wrapper, import VirtuosoDataTable, Column, ColumnHeader, and Cell from @virtuoso.dev/data-table directly.

Scroll checks

Give the table or its scroll parent a real height. Percent heights only work when every parent in the chain has a defined height too.

Pick exactly one scroll mode:

• Default internal scroller — for most tables
• useWindowScroll — when the document viewport scrolls the table
• customScrollParent — when an existing element provides scrolling