Config and State

This page replaces TanStack Table's Table Instance Guide. That page is about the table object returned by useTable, createTable, or injectTable: the one place that holds the options, the state, the APIs, and the row models, and the thing every render function reaches back into.

There is no table instance here. Nothing is constructed, nothing is held, and no function reaches into a shared object. In its place are three values you pass around explicitly.

The Three Values#

Almost every function in the package has the shape Config row -> State -> ... -> a. Two tables therefore share nothing by accident, and every transition is a value you can inspect, log, or store.

Your Data#

Any type works, and it never enters the Config. It is passed to whichever pipeline function you call, so the same Config can process two different lists. See Data.

Your Columns#

Column definitions are the first argument to Table.config. See Column Definitions for the constructors and the full set of per-column options.

Building the Config#

Table.config takes the column list and fills in TanStack's default for every flag. The with* builders pipe onto it:

config : Table.Config Person
config =
    Table.config
        [ Table.column "firstName" (.firstName >> Value.String)
            |> Table.withHeader "First name"
        , Table.column "department" (.department >> Value.String)
            |> Table.withHeader "Department"
        , Table.column "salary" (.salary >> Value.Number)
            |> Table.withHeader "Salary"
        ]
        |> Table.withGetRowId (\person _ _ -> person.id)
        |> Table.withGlobalFilterFn FilterFn.includesString

Build it once at the top level. It holds no state, so there is nothing to recompute, and putting it in view rebuilds the column tree on every frame. A Config that depends on runtime data, a generated column list or a server-reported row count, is built where that data arrives, in init or update.

Config is a plain record, so any field without a builder is a record update:

noGlobalFilter : Table.Config Person
noGlobalFilter =
    { config | enableGlobalFilter = False, maxMultiSortColCount = 2 }

Later versions of the package may add fields. That breaks code which pattern matches on the record, and does not break a record update.

Config Builders#

Twelve options have a builder. They exist for the options whose values are functions, where a builder reads better than a record update.

Config Options#

Every field of Table.Config row, with the value Table.config gives it.

Core#

Manual (Server-Side) Flags#

See Client-Side vs Server-Side.

Sorting#

Filtering#

See Column Filtering and Global Filtering.

Grouping and Expanding#

See Grouping, Aggregation, and Expanding.

Pagination#

See Pagination.

Row Selection and Row Pinning#

These four take a Row row rather than a Bool, because TanStack accepts either a boolean or a per-row predicate; always True and always False cover the boolean cases. See Row Selection and Row Pinning.

Columns#

See Column Pinning, Column Visibility, and Column Sizing.

Cell Spanning and Cell Selection#

See Cell Spanning and Cell Selection.

State#

Table.State is one record with thirteen slices, one per feature. It is yours: you put it in your model, you pass it to every function, and you replace it with what a transition returns. Nothing in the package holds a copy, so what you store is the whole truth.

Table.initialState is every slice at its default.

State is a plain record too, so starting somewhere other than the default is a record update on initialState:

startingState : Table.State
startingState =
    let
        base : Table.State
        base =
            Table.initialState
    in
    { base
        | pagination = { pageIndex = 0, pageSize = 25 }
        , sorting = [ { id = "salary", desc = True } ]
    }

Transitions#

Every state change is a function ending in State -> State, so it composes with |> and returns a value you store. Table.toggleSort, Table.setColumnFilter, Table.setPage, Table.toggleRowSelected, and the rest are listed on the feature guides.

Three of them take a RowModel as well, because their answer depends on the data: toggleSort needs the automatic first sort direction, setColumnFilter needs to know whether the filter should auto-remove itself, and toggleExpanded needs the row tree. Pass the model you already have.

Each feature also has a resetX, which returns that slice to the package's default rather than to a starting state you chose. There is no instance carrying your initialState around. To go back to your own starting point, call the matching setX with it.

Queries#

The functions you call while rendering all take the Config, usually the State, and sometimes a RowModel:

Table.visibleLeafColumns : Config row -> State -> List (Column row)
Table.getIsSorted : State -> String -> Maybe SortDir
Table.getValue : Config row -> Row row -> String -> Value

They are the counterpart of TanStack's table.getVisibleLeafColumns(), column.getIsSorted(), and cell.getValue(), with the receiver passed in rather than captured. The full list is in the Table module reference, and the API reference pages group them the way TanStack's do: Table API, Column API, Row API, Cell API, and Header API.

Row Models#

Table.rowsFromList runs the whole pipeline: core, filtered, grouped, sorted, expanded, paginated. Each stage is also exposed on its own, so you can stop early or inspect what one stage did.

Nothing is memoized, so the row model is computed exactly when you call for it. That makes it the third thing worth keeping in your model, next to the State:

type alias Model =
    { state : Table.State
    , rowModel : Table.RowModel Person
    }

Recompute it in update, when the state or the data changes, rather than in view:

update : Msg -> Model -> Model
update msg model =
    case msg of
        SortBy columnId ->
            recompute
                (Table.toggleSort config
                    model.rowModel
                    columnId
                    { desc = Nothing, multi = False }
                    model.state
                )

        GoToNextPage ->
            recompute (Table.nextPage config model.state)

recompute : Table.State -> Model
recompute state =
    { state = state
    , rowModel = Table.rowsFromList config state people
    }

Row Models covers the stages themselves. Table State covers the ownership patterns: a table inside a larger model, two tables side by side, keeping the row model in step, and resetting a slice.