--- title: Quick Start --- TanStack Table is a headless table library. It manages your table's state and logic (sorting, filtering, pagination, selection, and more) while you keep 100% control over the markup and styles. This page gets you from install to a rendering Ember table, then shows how to layer on your first feature. ## Installation ```bash npm install @tanstack/ember-table ``` `@tanstack/ember-table` is a v2 addon that requires Ember 5.8+ with Embroider (or ember-auto-import v2). It works with `.gts`/`.gjs` template tag components and Glint. ## How the Ember adapter works The adapter is built around two ideas: - **`useTable` returns a reactive table instance.** State lives in [TanStack Store](https://tanstack.com/store/latest) atoms that the adapter bridges into Glimmer's tracking system with an Ember-native reactivity feature. You pass options as a thunk (`useTable(() => ({ ... }))`); any tracked property the thunk reads (like `this.data`) re-runs the table when it changes, and any template or getter that reads a table API re-renders automatically. - **You render cells with the `FlexRenderCell`, `FlexRenderHeader`, and `FlexRenderFooter` components.** A column's `cell`/`header`/`footer` renderer can return a plain value or a component via `flexRenderComponent`, and the FlexRender components place it in your markup. > [!IMPORTANT] > TanStack Table v9 uses prototype-based methods that require `this` binding. Ember templates extract function references without binding them, so wrap table and column method calls in small helper functions (or getters) instead of calling them directly in templates. You will see this pattern in the sorting example below. ## Your First Table Define your table in a Glimmer component with the template tag format: ```gts import Component from '@glimmer/component' import { tracked } from '@glimmer/tracking' import { useTable, FlexRenderCell, FlexRenderHeader, tableFeatures, createColumnHelper, type Row, type Cell, } from '@tanstack/ember-table' // 1. Define the shape of your data interface Person { firstName: string lastName: string age: number } const data: Array = [ { firstName: 'Tanner', lastName: 'Linsley', age: 33 }, { firstName: 'Kevin', lastName: 'Vandy', age: 27 }, ] // 2. Opt in to the features you need (none yet) const features = tableFeatures({}) // 3. Define your columns with the column helper const columnHelper = createColumnHelper() const columns = columnHelper.columns([ columnHelper.accessor('firstName', { header: 'First Name', cell: (info) => info.getValue(), }), columnHelper.accessor('lastName', { header: 'Last Name', cell: (info) => info.getValue(), }), columnHelper.accessor('age', { header: 'Age', cell: (info) => info.renderValue(), }), ]) // 4. Template helpers: ember templates extract methods unbound, so wrap // table/row method calls that need `this` const getAllCells = ( row: Row, ): Array> => row.getAllCells() // 5. Create the table and render it export default class PersonTable extends Component { @tracked data = data table = useTable(() => ({ features, columns, data: this.data, })) get headerGroups() { return this.table.getHeaderGroups() } get rows() { return this.table.getRowModel().rows } } ``` Because `data` is `@tracked` and the options thunk reads `this.data`, assigning a new array re-runs the row model and re-renders the table. ## Adding a Feature: Sorting Features are opt-in. Import the feature and its row model, add them to `tableFeatures`, and wire up a click handler: ```gts import { on } from '@ember/modifier' import { useTable, FlexRenderCell, FlexRenderHeader, tableFeatures, createColumnHelper, rowSortingFeature, createSortedRowModel, sortFns, type Column, } from '@tanstack/ember-table' const features = tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel(), sortFns, }) // Helpers keep `this` bound correctly when called from templates const getCanSort = (column: Column): boolean => column.getCanSort() const toggleSort = (column: Column) => { return (event: Event) => { column.getToggleSortingHandler()?.(event) } } ``` Then attach the handler in your header markup: ```hbs {{#unless header.isPlaceholder}}
{{/unless}} ``` ## Rendering Components in Cells Return `flexRenderComponent` from a column's `cell` (or `header`/`footer`) definition to render a Glimmer component with custom arguments: ```gts import Component from '@glimmer/component' import { flexRenderComponent, type CellRenderableSignature, } from '@tanstack/ember-table' // Use `CellRenderableSignature` for a cell component: its `ctx` is a // `CellContext`, so `ctx.getValue()` is available directly with no cast. Use // `FlexRenderableSignature` only for a component rendered in both cell and // header slots; its `ctx` is a cell-or-header union. class StatusBadge extends Component< CellRenderableSignature > { get value(): string { return this.args.ctx.getValue() } } const columns = columnHelper.columns([ columnHelper.accessor('status', { header: 'Status', cell: () => flexRenderComponent(StatusBadge, { color: 'blue' }), }), ]) ``` ## Composable Tables When multiple tables in your app share the same features, row models, and default options, define them once with `createTableHook` instead of repeating them at every call site: ```ts const features = tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel(), sortFns, }) const { createAppTable, createAppColumnHelper } = createTableHook({ features }) ``` Then call `createAppTable(() => ({ columns, data: this.data }))` from your component instead of `useTable` (it takes the same options thunk, minus `features`), and define columns with `createAppColumnHelper`. See the [Composable Tables Guide](./guide/composable-tables.md) and the [Basic createAppTable example](./examples/basic-app-table) for the full pattern. ## What to Read Next - The [Table State](../../guide/tables.md) and [Row Models](../../guide/row-models.md) core guides explain how state and data flow work in v9. - Browse the Ember examples in the sidebar for working feature demos (sorting, filtering, pagination, row selection, column pinning, and more).