Skip to content

fix(DataTable): sort rows on the first render with an initial sort - #8710

Open
junkerderprovinz wants to merge 2 commits into
primer:mainfrom
junkerderprovinz:datatable-initial-sort
Open

junkerderprovinz wants to merge 2 commits into
primer:mainfrom
junkerderprovinz:datatable-initial-sort

Conversation

@junkerderprovinz

Copy link
Copy Markdown

Closes #3951

Hi! This picks up #4602 by @bwittenberg, who found the cause and wrote the first version of this fix. Ben mentioned in the PR not being able to continue, so I finished it along the lines @TylerJDev chose there (option 1, sort the data when the row order state is created). Thank you, Ben, you are credited as co-author.

With initialSortColumn or initialSortDirection, the header shows the sort direction, but the rows stay in the order of data until data changes or a header is clicked. The row order is now sorted in its useState initializer, so there is no extra render. For that, getSortedRowOrder moves out of the hook and looks up the column in columns instead of headers, because the headers do not exist yet when the initial state is created. externalSorting still keeps the order as given. An initialSortColumn given as a column's field while the column also has an id now resolves to that column, so the header shows the sort too.

#3951 was closed by the stale bot, but the bug is still there on main.

Changelog

New

Changed

  • DataTable sorts the rows on the first render when initialSortColumn or initialSortDirection is set.

Removed

Rollout strategy

  • No changes needed in github/github-ui
  • Needs changes in github/github-ui
  • Ships with feature flag(s)
  • Not sure
  • None

Tables that pass initialSortColumn with unsorted data will now show sorted rows on the first render, which is what the header already claims. Ben raised that some consumers might rely on the old order, so you may want to check it with the integration workflow.

Testing & Reviewing

The existing test for "only initialSortDirection is provided" asserted the unsorted order and is updated. There are new tests for sorting on the first render with initialSortColumn, with initialSortDirection="DESC" and the alphanumeric strategy, and for externalSorting keeping the given order. The first-render tests fail on main, and all DataTable tests pass with the change.

AI was used as a helper for this change.

Thanks for maintaining Primer!

@junkerderprovinz
junkerderprovinz requested a review from a team as a code owner November 7, 2026 23:40
@changeset-bot

changeset-bot Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6ec7c2a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@primer/react Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@Ultroncn Ultroncn left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for fixing the first-render sort — the code change itself looks right to me: rowOrder is now initialised through getSortedRowOrder (useTable.ts), the column lookup uses the same column.id ?? column.field identity as the header derivation and the sortByColumn reset check, and the externalSorting path still keeps the given order (the new test covers it).

One doc gap from the behaviour change: the initialSortColumn docs still tell consumers to pre-sort their data, which this PR makes unnecessary:

  • packages/react/src/DataTable/DataTable.tsx (~line 56-60, JSDoc): "Provide the id or field of the column by which the table is sorted. When using this prop, the input data must be sorted by this column in ascending order"
  • packages/react/src/DataTable/DataTable.docs.json (~line 190-194): same sentence (it tracks the JSDoc — both files change in lockstep in the git history).

Since the table now sorts the rows itself on the first render (in initialSortDirection, default ascending), that sentence reads as a requirement that no longer exists. Would it make sense to reword it along the lines of: "Provide the id or field of the column by which the table is sorted. The rows are sorted by this column on the first render; the input data does not need to be pre-sorted." — with the externalSorting case kept in mind (there the table does not sort internally, so the input data still needs to arrive in the desired order)?

initialSortColumn and initialSortDirection set the header state, but the
rows kept the order of data until data changed or a header was clicked.
The row order is now sorted in its useState initializer, the approach
agreed on in primer#4602. getSortedRowOrder moves out of the hook and looks up
columns instead of headers so it can run before the headers exist.

Co-authored-by: Ben Wittenberg <394958+bwittenberg@users.noreply.github.com>
@junkerderprovinz

Copy link
Copy Markdown
Author

Hi @Ultroncn, thank you for checking the externalSorting path and the column id lookup so carefully. Good catch on the docs! I reworded initialSortColumn in DataTable.tsx and DataTable.docs.json together. They now say the rows are sorted by that column on the first render, so the data needs no pre-sorting. With externalSorting the table doesn't sort, so the data still has to arrive in order.

This branch was successfully deployed

1 active deployment
github-pages — 6ec7c2a7 Deployed Nov 21, 2026 by junkerderprovinz via deploy-preview #30810
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Alphanumeric sorting initial sort

2 participants