Migration Guide: v2 to v3

Simple Table v3 makes the core engine fully framework-agnostic. Each framework now has its own dedicated adapter package. This guide covers everything you need to update.

What's New in v3

  • Framework Adapter Packages — React, Vue, Angular, Svelte, and Solid each have their own npm package (e.g. @simple-table/react)
  • Framework-Agnostic Core — simple-table-core is now plain JavaScript/TypeScript with no framework dependencies
  • Column Virtualization — Only visible columns are rendered in the DOM, dramatically improving performance for wide tables

Breaking Changes

Import from your framework adapter, not simple-table-core

In v2, everything was imported from simple-table-core. In v3, simple-table-core is a plain JavaScript engine and no longer exports framework components. Import from your framework's adapter package instead.

v2 (before):

React TSX
1import { SimpleTable } from "simple-table-core";
2import type { HeaderObject, Row, CellRendererProps } from "simple-table-core";
3import "simple-table-core/styles.css";

v3 (after):

React TSX
1import { SimpleTable } from "@simple-table/react";
2import type { ReactHeaderObject, Row, CellRendererProps } from "@simple-table/react";
3import "@simple-table/react/styles.css";

Framework-Specific Type Names

Some types are now prefixed with the framework name since each adapter can have slightly different type signatures. For React:

v2v3 (React)
HeaderObjectReactHeaderObject
TableRefTypeTableAPI

Other frameworks follow the same pattern (e.g. VueHeaderObject, AngularHeaderObject). Types like Row and Theme remain the same.

Table Ref: tableRef prop replaced by standard React ref

SimpleTable now uses React's forwardRef, so you pass a ref using the standard ref prop instead of the custom tableRef prop. The ref type has also been renamed from TableRefType to TableAPI.

React TSX
1// v2
2const tableRef = useRef<TableRefType>(null);
3<SimpleTable tableRef={tableRef} ... />
4

5// v3
6const tableRef = useRef<TableAPI>(null);
7<SimpleTable ref={tableRef} ... />

Framework Adapter Packages

FrameworkPackageInstall
React@simple-table/reactnpm i @simple-table/react
Vue@simple-table/vuenpm i @simple-table/vue
Angular@simple-table/angularnpm i @simple-table/angular
Svelte@simple-table/sveltenpm i @simple-table/svelte
Solid@simple-table/solidnpm i @simple-table/solid

Each adapter package includes simple-table-core as a dependency — you do not need to install it separately. CSS styles are imported from your adapter package (e.g. @simple-table/react/styles.css).

Step-by-Step Migration

1. Install your framework adapter

Install the adapter package for your framework. For React:

Shell
1npm install @simple-table/react

2. Update your imports

Find and replace all imports from simple-table-core with your adapter package.

Find:

React TSX
1from "simple-table-core"

Replace with:

React TSX
1from "@simple-table/react"

Tip: Use your editor's global find-and-replace. This covers both component/type imports and the CSS import — all references to simple-table-core become @simple-table/react.

3. Rename framework-specific types

Rename HeaderObject to ReactHeaderObject (or your framework's equivalent), and rename TableRefType to TableAPI.

React TSX
1// v2
2const headers: HeaderObject[] = [...]
3const tableRef = useRef<TableRefType>(null);
4

5// v3
6const headers: ReactHeaderObject[] = [...]
7const tableRef = useRef<TableAPI>(null);

4. Update tableRef to ref

The custom tableRef prop has been replaced by the standard React ref prop.

React TSX
1// v2
2<SimpleTable tableRef={tableRef} ... />
3

4// v3
5<SimpleTable ref={tableRef} ... />

5. Remove simple-table-core from your dependencies

You no longer need simple-table-core as a direct dependency. The adapter package includes it automatically.

Shell
1npm uninstall simple-table-core

Complete Migration Example

v2:

React TSX
1import { SimpleTable } from "simple-table-core";
2import type { HeaderObject, Row } from "simple-table-core";
3import "simple-table-core/styles.css";
4

5const headers: HeaderObject[] = [
6  { accessor: "name", label: "Name", width: 200 },
7  { accessor: "age", label: "Age", width: 100 },
8];
9

10const rows: Row[] = [
11  { name: "Alice", age: 30 },
12  { name: "Bob", age: 25 },
13];
14

15export default function MyTable() {
16  return <SimpleTable defaultHeaders={headers} rows={rows} />;
17}

v3:

React TSX
1import { SimpleTable } from "@simple-table/react";
2import type { ReactHeaderObject, Row } from "@simple-table/react";
3import "@simple-table/react/styles.css";
4

5const headers: ReactHeaderObject[] = [
6  { accessor: "name", label: "Name", width: 200 },
7  { accessor: "age", label: "Age", width: 100 },
8];
9

10const rows: Row[] = [
11  { name: "Alice", age: 30 },
12  { name: "Bob", age: 25 },
13];
14

15export default function MyTable() {
16  return <SimpleTable defaultHeaders={headers} rows={rows} />;
17}

That's it — update the import path, rename HeaderObject to ReactHeaderObject, TableRefType to TableAPI, and tableRef to ref. All other props and behavior are the same.

New: Column Virtualization

v3 introduces column virtualization. Previously, Simple Table only virtualized rows. Now columns are also virtualized — only the columns visible in the viewport are rendered in the DOM. This dramatically improves performance for tables with a large number of columns.

No configuration needed. Column virtualization is enabled automatically when your table has a fixed height and horizontal scrolling. There is nothing to opt into — it just works.

Migration Checklist

  • ☐Install your framework adapter (e.g. npm i @simple-table/react)
  • ☐Replace all from "simple-table-core" with from "@simple-table/react" (or your framework)
  • ☐Rename HeaderObject to ReactHeaderObject
  • ☐Rename TableRefType to TableAPI
  • ☐Replace tableRef={tableRef} with ref={tableRef}
  • ☐Update CSS import to import "@simple-table/react/styles.css"
  • ☐Verify your table renders correctly

Need Help?

If you encounter any issues during migration, check out these resources: