feat(userlist): add sortable columns to User List

[0xSysR3ll]

Description

Added sortable columns to the User List table.

• Clicking on any column header (Users, Requests, Type, Role, Joined) sorts the table by that column.
• Clicking the same column again toggles between ascending and descending order.
• Column headers display an arrow indicating the current sort direction.

Screenshot (if UI-related)

Example with username sorting (ASC)

Example with username sorting (DESC)

To-Dos

• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Issues Fixed or Closed

• Fixes [Feature Request] Make Columns Sortable on the Users Tab #1562

Summary by CodeRabbit

• New Features

  • User list: bidirectional sorting with direction indicators, header toggle, persisted choice; added account type and user role as sortable fields and updated header labels/accessibility.

• Tests

  • Added end-to-end tests for column header sorting, direction toggling, request params, and row order; adjusted intercept patterns.

• Chores

  • API docs updated to accept a sortDirection parameter and additional sort keys (usertype, role).

[0xSysR3ll]

Oops, think I broke the cypress test ? I looked at the videos/screenshots and tests seem OK (visually speaking) though.

[fallenbagel]

Oops, think I broke the cypress test ? I looked at the videos/screenshots and tests seem OK (visually speaking) though.

It's okay, it was just a hitch (It's passing now). Don't worry about it ;)

[fallenbagel]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.

Wdyt @gauthier-th?

[0xSysR3ll]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.

Wdyt @gauthier-th?

Yes you're right about the mobile view. I didn't consider how this would be less user-friendly on small screens.
Should we restore the dropdown as it was before, or should we enhance it to include the new sort options (usertype, role) that I added to the column headers?​​​​​​​​​​​​​​​​
Default sort direction would be DESC I think.

[gauthier-th]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.

Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

[fallenbagel]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.

Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

I think you misread @0xSysR3ll .
They are saying we should keep it because its user-friendly and mobile-friendly. The dropdown along with the sort column. Because the sort column thing is not mobile-friendly per se

[gauthier-th]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.
Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

I think you misread @0xSysR3ll . They are saying we should keep it because its user-friendly and mobile-friendly. The dropdown along with the sort column. Because the sort column thing is not mobile-friendly per se

I think i read it properly. I guess I don't understand why would clicking on a column would be not mobile-friendly?

[fallenbagel]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.
Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

I think you misread @0xSysR3ll . They are saying we should keep it because its user-friendly and mobile-friendly. The dropdown along with the sort column. Because the sort column thing is not mobile-friendly per se

I think i read it properly. I guess I don't understand why would clicking on a column would be not mobile-friendly?

I would prefer having two options. And its not mobile-friendly because column does not fit the mobile already. Meaning to change the sorting you have to scroll sideways whereas its much easier to just choose from a dropdown the minute the page loads instead of waiting for page to load then scroll to the right to find the column you want

[gauthier-th]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.
Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

I think you misread @0xSysR3ll . They are saying we should keep it because its user-friendly and mobile-friendly. The dropdown along with the sort column. Because the sort column thing is not mobile-friendly per se

I think i read it properly. I guess I don't understand why would clicking on a column would be not mobile-friendly?

I would prefer having two options. And its not mobile-friendly because column does not fit the mobile already. Meaning to change the sorting you have to scroll sideways whereas its much easier to just choose from a dropdown the minute the page loads instead of waiting for page to load then scroll to the right to find the column you want

Yeah i don't totally agree but i get your point. Let's make 2 different things for desktop and mobile then?

[fallenbagel]

I removed the old dropdown sorting menu to simplify the UI since column sorting is more intuitive.

I would say it's more preferable that, that is kept too. It's especially useful on mobile view than using the column to do so imho.
Wdyt @gauthier-th?

If it's enough user-friendly and mobile-friendly why would we keep it?

I think you misread @0xSysR3ll . They are saying we should keep it because its user-friendly and mobile-friendly. The dropdown along with the sort column. Because the sort column thing is not mobile-friendly per se

I think i read it properly. I guess I don't understand why would clicking on a column would be not mobile-friendly?

I would prefer having two options. And its not mobile-friendly because column does not fit the mobile already. Meaning to change the sorting you have to scroll sideways whereas its much easier to just choose from a dropdown the minute the page loads instead of waiting for page to load then scroll to the right to find the column you want

Yeah i don't totally agree but i get your point. Let's make 2 different things for desktop and mobile then?

Or why not keep both. It doesn't make it less friendly? You get both options then

[0xSysR3ll]

I actually agree with both of you. I should have checked the mobile version earlier.
For now, let’s keep both options available, and we can revisit this later, especially when the mobile app is introduced.

[gauthier-th]

@0xSysR3ll please fix the cypress tests, as they are failing

[0xSysR3ll]

@0xSysR3ll please fix the cypress tests, as they are failing

Could the cypress error be just a fluke? It has happened before. I reviewed the video of the failing test but couldn’t find anything in my latest commit that would have triggered it.

[fallenbagel]

@0xSysR3ll please fix the cypress tests, as they are failing

Could the cypress error be just a fluke? It has happened before. I reviewed the video of the failing test but couldn’t find anything in my latest commit that would have triggered it.

Yes dont worry

[0xSysR3ll]

Btw, this might not be the best place to mention it - and not that I necessarily live up to it - but I think I wasn’t added to the contributor list as part of my first PR.

[gauthier-th]

@all-contributors please add @0xSysR3ll for code

[allcontributors]

@gauthier-th

I've put up a pull request to add @0xSysR3ll! 🎉

[gauthier-th]

@0xSysR3ll sorry about that, you were right to ask :)

[Gauvino]

Hello, can a preview-tag can be created for this please ?

[gauthier-th]

Hello, can a preview-tag can be created for this please ?

preview-sort-userlist available in ~30min

[Gauvino]

Works really well, only thing I'm saying is why is it refreshing when clicking on a column for now I'm having like 25 users and on the bottom I've selected to show 50 items

[0xSysR3ll]

Works really well, only thing I'm saying is why is it refreshing when clicking on a column for now I'm having like 25 users and on the bottom I've selected to show 50 items

Not sure to understand your concern but yeah, the table refreshes on sort because we’re fetching sorted data from the backend every time you click a column. Even if there are fewer users than the page size, it always does a new API call to keep things consistent and scalable. For small lists it’s a bit overkill, but that’s just how it’s set up right now. If we wanted to avoid the reload for small datasets, I guess we’d have to add some client-side sorting logic.

[Gauvino]

As you want, just a little review on my user side !

[0xSysR3ll]

As you want, just a little review on my user side !

Well, I’ll have to wait for the bosses’ opinion 🫡
But thanks for your review anyway!

[Gauvino]

Would love to see this implemented

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/components/UserList/index.tsx (1)

165-172: ⚠️ Potential issue | 🟡 Minor

Harden localStorage hydration for sort settings.

Parsing and applying persisted filter state is not guarded. A malformed or stale payload can throw or hydrate invalid currentSort/sortDirection, which can break requests.

🛡️ Suggested fix

   useEffect(() => {
     const filterString = window.localStorage.getItem('ul-filter-settings');

     if (filterString) {
-      const filterSettings = JSON.parse(filterString);
-
-      setCurrentSort(filterSettings.currentSort);
-      setCurrentPageSize(filterSettings.currentPageSize);
-      if (filterSettings.sortDirection) {
-        setSortDirection(filterSettings.sortDirection);
-      }
+      try {
+        const filterSettings = JSON.parse(filterString);
+        const validSorts: Sort[] = [
+          'created',
+          'updated',
+          'requests',
+          'displayname',
+          'usertype',
+          'role',
+        ];
+        const validDirections: SortDirection[] = ['asc', 'desc'];
+
+        if (validSorts.includes(filterSettings.currentSort)) {
+          setCurrentSort(filterSettings.currentSort);
+        }
+        if (typeof filterSettings.currentPageSize === 'number') {
+          setCurrentPageSize(filterSettings.currentPageSize);
+        }
+        if (validDirections.includes(filterSettings.sortDirection)) {
+          setSortDirection(filterSettings.sortDirection);
+        }
+      } catch {
+        window.localStorage.removeItem('ul-filter-settings');
+      }
     }
   }, []);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/UserList/index.tsx` around lines 165 - 172, The hydration
block that reads filterString and calls JSON.parse is unguarded and can throw or
set invalid state; wrap the JSON.parse in a try/catch and validate fields before
applying them: parse filterString safely, ensure currentSort is one of your
allowed sort keys (or fallback), currentPageSize is a valid number within
allowed page sizes, and sortDirection is either 'asc' or 'desc' before calling
setCurrentSort, setCurrentPageSize, and setSortDirection; if validation fails or
parse throws, use safe defaults instead. Ensure you reference the same variables
(filterString, currentSort, currentPageSize, sortDirection) and functions
(setCurrentSort, setCurrentPageSize, setSortDirection) in the hydration code so
malformed or stale payloads do not break requests.

♻️ Duplicate comments (2)

server/routes/user/index.ts (1)

101-104: ⚠️ Potential issue | 🟡 Minor

Lowercase the email fallback in displayname_sort_key.

At Line [103], the fallback returns raw email, while other branches are normalized via LOWER(...). This can still cause case-sensitive sort inconsistencies.

🔧 Proposed fix

-                  CASE WHEN (user.jellyfinUsername IS NULL OR user.jellyfinUsername = '') THEN
-                    "user"."email"
+                  CASE WHEN (user.jellyfinUsername IS NULL OR user.jellyfinUsername = '') THEN
+                    LOWER(user.email)
                   ELSE
                     LOWER(user.jellyfinUsername)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@server/routes/user/index.ts` around lines 101 - 104, The CASE expression
building displayname_sort_key returns raw "user"."email" in the fallback branch
causing case-sensitive sort differences; update the fallback to use
LOWER("user"."email") so all branches (plexUsername, jellyfinUsername, and
email) are normalized consistently. Locate the CASE that references
user.plexUsername, user.jellyfinUsername and "user"."email" in
displayname_sort_key and replace the raw email return with
LOWER("user"."email").

src/components/UserList/index.tsx (1)

229-247: ⚠️ Potential issue | 🟠 Major

Make sortable headers keyboard-operable and expose sort semantics.

Sorting is bound to clickable header cells, which are not keyboard-focusable controls and do not expose aria-sort state.

🔧 Suggested fix

-      <Table.TH
-        className="cursor-pointer"
-        onClick={() => onSortChange(sortKey)}
-        data-testid={`column-header-${sortKey}`}
-        title={getTooltip()}
-      >
-        <div className="flex items-center">
+      <Table.TH
+        aria-sort={
+          currentSort === sortKey
+            ? sortDirection === 'asc'
+              ? 'ascending'
+              : 'descending'
+            : 'none'
+        }
+      >
+        <button
+          type="button"
+          className="flex items-center cursor-pointer"
+          onClick={() => onSortChange(sortKey)}
+          data-testid={`column-header-${sortKey}`}
+          title={getTooltip()}
+          aria-label={getTooltip()}
+        >
           <span>{children}</span>
           {currentSort === sortKey && (
             <span className="ml-1">
               {sortDirection === 'asc' ? (
                 <ChevronUpIcon className="h-4 w-4" />
               ) : (
                 <ChevronDownIcon className="h-4 w-4" />
               )}
             </span>
           )}
-        </div>
+        </button>
       </Table.TH>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/UserList/index.tsx` around lines 229 - 247, The header cell
currently uses Table.TH with only an onClick (onSortChange) and is not
keyboard-focusable or exposing sort semantics; make it keyboard-operable by
adding role="button" and tabIndex={0} to the Table.TH (or replace the header
content with a real <button>) and implement an onKeyDown handler that calls
onSortChange(sortKey) when Enter or Space is pressed; also add aria-sort with
values 'none' | 'ascending' | 'descending' derived from currentSort and
sortDirection for the given sortKey so assistive tech can read the sort state,
and keep existing props like data-testid, title/getTooltip, children, and the
chevron indicator (currentSort, sortDirection) intact.

🧹 Nitpick comments (3)

cypress/e2e/user/user-list.cy.ts (3)

39-39: Use method-scoped intercepts to avoid nondeterministic waits.

Line 39 and Line 59 intercept all /api/v1/user* requests regardless of method. That can make cy.wait('@user') resolve on an unintended request and create flakiness.

Proposed hardening

-    cy.intercept('/api/v1/user*').as('user');
+    cy.intercept('POST', '/api/v1/user').as('createUser');
+    cy.intercept('GET', '/api/v1/user*').as('userListRefresh');

@@
-    cy.wait('@user');
+    cy.wait('@createUser');
+    cy.wait('@userListRefresh');

@@
-    cy.intercept('/api/v1/user*').as('user');
+    cy.intercept('DELETE', '/api/v1/user*').as('deleteUser');
+    cy.intercept('GET', '/api/v1/user*').as('userListRefresh');

@@
-    cy.wait('@user');
+    cy.wait('@deleteUser');
+    cy.wait('@userListRefresh');

Also applies to: 59-59

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cypress/e2e/user/user-list.cy.ts` at line 39, The intercepts currently use a
URL-only pattern (cy.intercept('/api/v1/user*').as('user')) which can match any
HTTP method and cause cy.wait('@user') to resolve on the wrong request; update
the intercept calls to be method-scoped (e.g. include { method: 'GET', url:
'/api/v1/user*' } or { method: 'POST', url: '/api/v1/user*' }) and give distinct
aliases (e.g. 'getUser' / 'createUser') so waits target the intended request;
update both occurrences of cy.intercept that use the 'user' alias.

---

77-83: Add explicit same-column toggle coverage.

Line 77 currently validates only the first click state. The feature requirement includes toggling direction on repeated clicks of the same header, so this should assert the second click flips sortDirection.

Proposed test extension

     cy.get('[data-testid=column-header-displayname]').click();
     cy.wait('@userListFetch').then((interception) => {
       const url = interception.request.url;
       expect(url).to.include('sort=displayname');
       expect(url).to.include('sortDirection=asc');
     });
+
+    cy.get('[data-testid=column-header-displayname]').click();
+    cy.wait('@userListFetch').then((interception) => {
+      const url = interception.request.url;
+      expect(url).to.include('sort=displayname');
+      expect(url).to.include('sortDirection=desc');
+    });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cypress/e2e/user/user-list.cy.ts` around lines 77 - 83, Add an explicit
second-click assertion to cover same-column toggle: after the existing check on
cy.get('[data-testid=column-header-displayname]').click() and its interception,
perform another click on the same selector
(cy.get('[data-testid=column-header-displayname]').click()), wait for the
'@userListFetch' interception again, and assert the request URL still includes
'sort=displayname' but now includes 'sortDirection=desc' (or the opposite
direction value expected by the app) to verify the header toggles sort direction
on repeated clicks.

---

94-101: Verify created-sort effect on ordering, not just query params.

Line 95-Line 99 checks request params, but Line 101 only checks row presence. This can pass even if UI ordering is wrong after created sort. Add one ordering assertion (e.g., compare rendered first row with first item from intercepted sorted response).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@cypress/e2e/user/user-list.cy.ts` around lines 94 - 101, The test only
asserts query params after clicking the created column but doesn't verify the UI
ordering; capture the intercepted response from the '@userListFetch'
interception after clicking '[data-testid=column-header-created]' and assert
that the first rendered row ('[data-testid=user-list-row]') matches the first
item in the intercepted (sorted) response (e.g., compare displayed
identifier/text in the first row to interception.response.body[0]'s
corresponding field) so the UI ordering actually reflects the server-sorted
data.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@src/components/UserList/index.tsx`:
- Around line 165-172: The hydration block that reads filterString and calls
JSON.parse is unguarded and can throw or set invalid state; wrap the JSON.parse
in a try/catch and validate fields before applying them: parse filterString
safely, ensure currentSort is one of your allowed sort keys (or fallback),
currentPageSize is a valid number within allowed page sizes, and sortDirection
is either 'asc' or 'desc' before calling setCurrentSort, setCurrentPageSize, and
setSortDirection; if validation fails or parse throws, use safe defaults
instead. Ensure you reference the same variables (filterString, currentSort,
currentPageSize, sortDirection) and functions (setCurrentSort,
setCurrentPageSize, setSortDirection) in the hydration code so malformed or
stale payloads do not break requests.

---

Duplicate comments:
In `@server/routes/user/index.ts`:
- Around line 101-104: The CASE expression building displayname_sort_key returns
raw "user"."email" in the fallback branch causing case-sensitive sort
differences; update the fallback to use LOWER("user"."email") so all branches
(plexUsername, jellyfinUsername, and email) are normalized consistently. Locate
the CASE that references user.plexUsername, user.jellyfinUsername and
"user"."email" in displayname_sort_key and replace the raw email return with
LOWER("user"."email").

In `@src/components/UserList/index.tsx`:
- Around line 229-247: The header cell currently uses Table.TH with only an
onClick (onSortChange) and is not keyboard-focusable or exposing sort semantics;
make it keyboard-operable by adding role="button" and tabIndex={0} to the
Table.TH (or replace the header content with a real <button>) and implement an
onKeyDown handler that calls onSortChange(sortKey) when Enter or Space is
pressed; also add aria-sort with values 'none' | 'ascending' | 'descending'
derived from currentSort and sortDirection for the given sortKey so assistive
tech can read the sort state, and keep existing props like data-testid,
title/getTooltip, children, and the chevron indicator (currentSort,
sortDirection) intact.

---

Nitpick comments:
In `@cypress/e2e/user/user-list.cy.ts`:
- Line 39: The intercepts currently use a URL-only pattern
(cy.intercept('/api/v1/user*').as('user')) which can match any HTTP method and
cause cy.wait('@user') to resolve on the wrong request; update the intercept
calls to be method-scoped (e.g. include { method: 'GET', url: '/api/v1/user*' }
or { method: 'POST', url: '/api/v1/user*' }) and give distinct aliases (e.g.
'getUser' / 'createUser') so waits target the intended request; update both
occurrences of cy.intercept that use the 'user' alias.
- Around line 77-83: Add an explicit second-click assertion to cover same-column
toggle: after the existing check on
cy.get('[data-testid=column-header-displayname]').click() and its interception,
perform another click on the same selector
(cy.get('[data-testid=column-header-displayname]').click()), wait for the
'@userListFetch' interception again, and assert the request URL still includes
'sort=displayname' but now includes 'sortDirection=desc' (or the opposite
direction value expected by the app) to verify the header toggles sort direction
on repeated clicks.
- Around line 94-101: The test only asserts query params after clicking the
created column but doesn't verify the UI ordering; capture the intercepted
response from the '@userListFetch' interception after clicking
'[data-testid=column-header-created]' and assert that the first rendered row
('[data-testid=user-list-row]') matches the first item in the intercepted
(sorted) response (e.g., compare displayed identifier/text in the first row to
interception.response.body[0]'s corresponding field) so the UI ordering actually
reflects the server-sorted data.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 18144fa and a83bd6e.

📒 Files selected for processing (5)

• cypress/e2e/user/user-list.cy.ts
• seerr-api.yml
• server/routes/user/index.ts
• src/components/UserList/index.tsx
• src/i18n/locale/en.json

[Gauvino]

I'm very excited for this to be merged, it's very important in my case!
I already reviewed it; if you need anything from me, like testing the preview, or so tell me!