feat(admin): no way to control the order of nav groups in the sidebar

[dvnold]

Describe the Bug / Feature Gap

The admin sidebar renders nav groups in first-encounter order, determined by the order collections/globals are declared in payload.config.ts plus the seed array in groupNavItems. There is no config option to control the order of the groups themselves.

This means:

1. The implicit Collections group is always forced to the top (it's seeded first in the reducer), even if the user wants a custom group like System or Layout to appear first.
2. Custom groups appear in declaration order, which fights against logical file organization.
3. A globals-only group (e.g. Layout) is forced to the bottom because all collections are iterated before all globals.

Reproduction

Minimal config:

// payload.config.ts
collections: [
  { slug: 'zebra',    admin: { group: 'Animals' } },
  { slug: 'apple',    admin: { group: 'Food' } },
  { slug: 'settings', admin: { group: 'System' } },
  { slug: 'banana' },                              // no group -> default Collections
],
globals: [
  { slug: 'header', admin: { group: 'Layout' } },
]

Resulting sidebar order:

1. Collections → banana
2. Animals → zebra
3. Food → apple
4. System → settings
5. Layout → header

There is no way to make System or Layout appear at the top without prefix hacks (group: '1. System') that leak the digit into the rendered label, or swapping in a fully custom Nav component.

Root Cause

packages/ui/src/utilities/groupNavItems.ts seeds the reducer with [Collections, Globals] and appends custom groups in first-encounter order. No sort step, no order/weight/index field on collections or globals, and no admin.groups / admin.sortGroups on the top-level admin config.

Related

• Discussion Better ordering of groups of globals & collections #1277 — original request from Oct 2022, 26+ upvotes, maintainer proposed admin.sortGroups but never implemented.
• Discussion Customizable Order for Sidebar Navigation (Collections & Globals) #14528 — newer request with a workaround.
• Community plugin tatsuyaykari1203/payload-sidebar solves it externally.

Suggested API

Add an optional admin.groups array to the sanitized config that lets users declare group labels in the order they should render. Groups not listed fall back to first-encounter order, preserving backward compatibility.

admin: {
  groups: ['System', 'Animals', 'Food', 'Layout', 'Collections'],
}

Happy to open a PR for this — the change is small (a sort step in groupNavItems keyed off config.admin.groups).

[paulpopus]

Converted this to a discussion as it's a feature request, but yes we should support this in v4!

[ramiscaleai]

Hi @dvnold, it looks like #17098 was closed by accident, and this has since been confirmed for v4 in the reply above. Are you planning to reopen it, or to open a new PR against v4 main?

If you'd rather not, I have an implementation of the same admin.groups API you proposed, rebased on v4 main. It also orders the dashboard's groups, and it comes with unit tests, e2e tests and docs: main...ramiscaleai:payload:feat/admin-nav-group-order

If you're not taking it, I'll open it and credit your proposal. Either way is fine with me; I just don't want to step on your work.

(I'm using AI assistance (Claude Code); the tests were run locally.)