Migrating from svelte-headless-table 0.17.x

The original svelte-headless-table package (bryanmylee/svelte-headless-table) is unmaintained — its last npm publish was version 0.18.3 on 2024-10-28, and it targets Svelte 3/4. @humanspeak/svelte-headless-table is the actively maintained successor, rebuilt for Svelte 5.

The good news: the public API matches the final original releases (0.17.7 through 0.18.3). createTable, createColumns, createViewModel, Subscribe, Render, createRender, and every original plugin keep their names and signatures. For most projects the migration is two changes: the package name in your imports, and your Svelte version.

1. Upgrade to Svelte 5

@humanspeak/svelte-headless-table requires Svelte 5 (peer dependency svelte: ^5.30.0) because the internals use runes. If your app is still on Svelte 4, follow the official Svelte 5 migration guide first — npx sv migrate svelte-5 automates most of it.

Your existing table code uses Svelte stores (writable, $store subscriptions), and that keeps working in Svelte 5 — you do not need to rewrite table state as runes.

2. Swap the package

npm uninstall svelte-headless-table
npm install @humanspeak/svelte-headless-table

npm uninstall svelte-headless-table
npm install @humanspeak/svelte-headless-table

3. Rename your imports

For most apps the only code change is the import specifier — including the /plugins entry point:

// Before (0.17.x / 0.18.x)
import { createTable, Render, Subscribe, createRender } from 'svelte-headless-table'
import { addSortBy, addPagination } from 'svelte-headless-table/plugins'

// After
import { createTable, Render, Subscribe, createRender } from '@humanspeak/svelte-headless-table'
import { addSortBy, addPagination } from '@humanspeak/svelte-headless-table/plugins'

// Before (0.17.x / 0.18.x)
import { createTable, Render, Subscribe, createRender } from 'svelte-headless-table'
import { addSortBy, addPagination } from 'svelte-headless-table/plugins'

// After
import { createTable, Render, Subscribe, createRender } from '@humanspeak/svelte-headless-table'
import { addSortBy, addPagination } from '@humanspeak/svelte-headless-table/plugins'

A project-wide find-and-replace of 'svelte-headless-table → '@humanspeak/svelte-headless-table covers both entry points.

Column definitions, view models, plugin configuration, and Subscribe/Render markup compile unchanged:

const table = createTable(data, {
    sort: addSortBy(),
    page: addPagination()
})

const columns = table.createColumns([
    table.column({ header: 'Name', accessor: 'name' }),
    table.column({ header: 'Age', accessor: 'age' })
])

const { headerRows, pageRows, tableAttrs, tableBodyAttrs } = table.createViewModel(columns)

const table = createTable(data, {
    sort: addSortBy(),
    page: addPagination()
})

const columns = table.createColumns([
    table.column({ header: 'Name', accessor: 'name' }),
    table.column({ header: 'Age', accessor: 'age' })
])

const { headerRows, pageRows, tableAttrs, tableBodyAttrs } = table.createViewModel(columns)

Server-side pagination on 0.17.6 or earlier

The one API change in the 0.17.x range predates this package: original versions 0.17.0–0.17.6 configured server-side pagination with addPagination({ serverSide: true }) and exposed a writable item-count store on plugin state (serverItemsCount up to 0.17.5, renamed serverItemCount in 0.17.6) that your app set after each server response. Starting with original 0.17.7 — and in this package — you create that store yourself and pass it in as serverItemCount: Readable<number>:

// Before (0.17.0–0.17.6)
const table = createTable(data, {
    page: addPagination({ serverSide: true })
})
const { pageIndex, pageSize, serverItemCount } = table.createViewModel(columns).pluginStates.page

const res = await fetchPage($pageIndex, $pageSize)
serverItemCount.set(res.totalItems) // plugin-state store

// After (0.17.7+ and @humanspeak/svelte-headless-table)
import { writable } from 'svelte/store'

const serverItemCount = writable(0) // your own store
const table = createTable(data, {
    page: addPagination({ serverSide: true, serverItemCount })
})
const { pageIndex, pageSize } = table.createViewModel(columns).pluginStates.page

const res = await fetchPage($pageIndex, $pageSize)
serverItemCount.set(res.totalItems)

// Before (0.17.0–0.17.6)
const table = createTable(data, {
    page: addPagination({ serverSide: true })
})
const { pageIndex, pageSize, serverItemCount } = table.createViewModel(columns).pluginStates.page

const res = await fetchPage($pageIndex, $pageSize)
serverItemCount.set(res.totalItems) // plugin-state store

// After (0.17.7+ and @humanspeak/svelte-headless-table)
import { writable } from 'svelte/store'

const serverItemCount = writable(0) // your own store
const table = createTable(data, {
    page: addPagination({ serverSide: true, serverItemCount })
})
const { pageIndex, pageSize } = table.createViewModel(columns).pluginStates.page

const res = await fetchPage($pageIndex, $pageSize)
serverItemCount.set(res.totalItems)

pageCount, hasPreviousPage, and hasNextPage still derive from the item count automatically. If you upgraded through 0.17.7 or 0.18.x before switching packages, you already made this change. Client-side pagination is unaffected.

4. Verify

• Type-check: svelte-check should pass with no new table-related errors.
• If you use TypeScript, types now come from the same import paths — no separate @types package.
• Run your table pages; sorting, filtering, pagination, and selection state behave as before.

What you gain

Beyond an actively maintained package with Svelte 5 support, three plugins ship that the original never did:

• addDataExport — export table data as JSON, CSV, or plain objects
• addFlatten — flatten nested row structures
• addVirtualScroll — virtualized rendering for large datasets

All 12 original plugins are here too — see the plugin overview.

Troubleshooting

Cannot find module 'svelte-headless-table'

A stray import still references the old package — search for from 'svelte-headless-table and rename it.

Peer dependency warning on install

Your svelte version is below 5.30.0. Upgrade Svelte (step 1) before installing.

Both packages installed at once

Nothing breaks at runtime, but two copies of the table types will confuse TypeScript. Remove the original: npm uninstall svelte-headless-table.