Troubleshooting

The grid is designed to work out of the box with minimal setup. If you’re hitting issues with basic configuration — TypeScript types, framework imports, or event handling — check the Getting Started guide first, which covers setup for all frameworks.

This page covers the few genuine gotchas that can’t be solved in code.

---

Height & Virtualization

The grid virtualizes rows for performance, which requires a constrained height. This is the most common setup issue.

Grid appears empty or collapsed

The grid needs an explicit height. Without one, the container collapses to zero and nothing renders.

/* ✅ Fixed height */
tbw-grid {
  height: 500px;
}

/* ✅ Flex layout */
.container {
  display: flex;
  flex-direction: column;
  height: 100vh;
}
tbw-grid {
  flex: 1;
  min-height: 0; /* Required for flex children to shrink */
}

If you don’t need virtual scrolling (small datasets), set height: auto so the grid sizes to its content:

tbw-grid {
  height: auto;
}

Rows appear in wrong positions after scroll

Variable row heights can cause position drift. Use a fixed rowHeight for best accuracy:

grid.gridConfig = { rowHeight: 36 };

If you need auto-measured heights, call forceLayout() after content changes:

await grid.forceLayout();

Blank rows or flickering during fast scroll

The grid renders a buffer of extra rows (overscan) above and below the viewport. During very fast scrolling, the buffer can be exhausted before new rows paint. Setting rowHeight explicitly lets the grid calculate positions without measuring, which keeps up better:

grid.gridConfig = { rowHeight: 32 };

---

Performance

Use formatters over renderers for simple values

format returns a string — significantly faster than creating DOM elements in a renderer:

// ✅ Fast — string formatter
{ field: 'salary', format: (v) => `$${v.toLocaleString()}` }

// ⚠️ Slower — DOM renderer (use only when you need rich content)
{ field: 'salary', renderer: (ctx) => {
  const el = document.createElement('span');
  el.textContent = `$${ctx.value.toLocaleString()}`;
  return el;
}}

Column virtualization for wide grids

For 50+ columns, enable the columnVirtualization feature so off-screen columns aren’t rendered:

import '@toolbox-web/grid/features/column-virtualization';

grid.gridConfig = {
  features: { columnVirtualization: true },
};

Disable animations during initial load

If first paint feels slow, disable animations:

grid.gridConfig = { animation: { mode: 'off' } };

See the Performance Guide for profiling techniques and detailed tuning.

---

For Plugin & Adapter Developers

The sections below cover issues specific to custom plugin and framework adapter development.

Plugin dependency errors

A plugin requires another plugin that isn’t loaded:

UndoRedoPlugin requires EditingPlugin

Fix with features API (auto-resolves dependencies):

import '@toolbox-web/grid/features/undo-redo';
// EditingPlugin is loaded automatically

Fix with plugins API (manual ordering):

plugins: [
  new EditingPlugin(),     // Must come first
  new UndoRedoPlugin(),    // Depends on EditingPlugin
]

Two plugins modifying the same columns/rows

Symptoms: Unexpected column order, missing columns, or data appearing twice.

Plugins process columns and rows in registration order. If two plugins manipulate the same columns, they may conflict. When using the features API, try reordering the features entries. When using the plugins API, reorder the array — the last plugin to process wins.

Known plugin incompatibilities

Plugin A	Plugin B	Issue
PinnedColumnsPlugin	GroupingColumnsPlugin	Pinning moves columns to edges, breaking group layouts
ResponsivePlugin	GroupingRowsPlugin	Card mode doesn’t support group rows

See the Plugins Overview → Known Incompatibilities for the full list.

Styles not applying (CSP)

The grid injects plugin styles via adoptedStyleSheets. If your CSP blocks this, styles fail silently.

Required CSP header:

style-src 'self';

adoptedStyleSheets does not require 'unsafe-inline' — it’s treated as a programmatic stylesheet. Check the browser console for CSP violation messages.

CSS cascade layer specificity

The grid’s built-in styles use CSS @layer. Your custom CSS may not be specific enough to override them.

Use CSS custom properties (recommended):

tbw-grid {
  --tbw-color-row-hover: #e0f7fa;
  --tbw-cell-padding: 12px 16px;
}

Since the grid uses Light DOM, normal CSS selectors also work — just ensure your selectors are specific enough to beat the @layer defaults.

---

Still Stuck?

1. Check the console — The grid logs configuration errors with actionable import hints
2. Inspect the DOM — Light DOM means standard browser DevTools work directly
3. Minimal reproduction — Isolate the issue in a standalone example
4. Check GitHub Issues — Someone may have encountered the same problem
5. Open an issue — Include a reproduction for fastest help

See Also

Getting Started Installation and setup for all frameworks

Performance Guide Profiling, virtualization tuning, and bundle optimization

Production Checklist Security, performance, and deployment readiness

Custom Plugins Plugin development guide — hooks, styles, lifecycle

Plugins Overview Plugin compatibility, dependencies, and known conflicts