User Menu

Live demo

UserMenu calls useShell(), which throws outside a provider, so the demo mounts a small ShellProvider holding one user and one logout handler. Open the menu: the identity block, three built-in rows, three app rows, and sign out in destructive red at the bottom. On a screen at md or wider you will not see Appearance — that is the default and it is explained below.

Composition order

The order is fixed by the component; the app chooses only what exists. Six slots, top to bottom:

1. Identity block. Avatar, name, then email and role if you supplied them. Always present, and not selectable — it is a DropdownMenuLabel, not an item.
2. A separator, whenever anything below it exists — with one wrinkle: the test counts showThemeSubmenu as an entry whenever it is not false, so the default "mobile" keeps the rule at every width. A menu with no routes and no items therefore shows a separator above an Appearance row that md:hidden has already taken away.
3. Profile · Settings · Help, in that order, each one only if you gave it a route.
4. Your items, in array order.
5. Appearance submenu, per showThemeSubmenu.
6. A separator and Sign out, only when a logout handler exists.

Two consequences worth knowing before you fight the component:

• There is no separator entry. UserMenuItem has no such variant, so a long items array renders as one unbroken run between the built-ins and Appearance. The two rules you see are structural: identity from entries, entries from sign out. A menu that needs visual grouping is a menu that is too long — the shell’s answer is the sidebar or a settings page, not more rules.
• Nothing can go below sign out, and nothing can go above the built-ins. If a row must lead, make it the first element of items and leave profileHref unset.

The avatar: initials, then colour

With avatarUrl you get the photo. Without one you get getVietnameseInitials(user.name) on a background from getAvatarToneClasses(user.name). The initials rule is first letter of the surname plus first letter of the given name — the first and last words, not the first two. Vietnamese speakers address each other by the last word of the name, so the Western “first two words” rule turns Nguyễn Đức Thành into “NĐ”, which is nobody.

One person, one colour

The tone is a hash of the display name into a table of eight, and that table is the only one in the package. The Tier 3 UserAvatar in the header, the Tier 2 LetterAvatar in a member list, and getAvatarToneColors() from @comitor/ui/tokens in a PDF or an HTML email all read it — each pair below is the two components side by side, on the same name.

• The seed is the name, never the email or the id. Every place that draws an avatar has a name in hand; not every place has an email. Seed two surfaces differently and the same colleague arrives in two colours on one screen.
• Trimmed and lower-cased, but diacritic-sensitive. “Phan Bình” and “phan bình” are one colour; “Phan Binh” is another. Store names one canonical way, or people change colour when a form strips their tones.
• Eight tones is decoration, not identity. Collisions are expected and fine — the colour helps you re-find a row you already know, it never encodes who someone is.
• Both palettes, both themes. Each tone is a token pair such as bg-teal/15 text-teal-ink — a tint for the background and the ink step for the letters, with a dark: branch where the tint needs one. That is why you cannot hand-roll a ninth tone from a raw scale step.

The three built-in rows

Profile, Settings and Help are the only rows the package proposes, and each appears only when the app hands it a route. That asymmetry is on purpose: the label is a shell concern (it must translate with the rest of the menu), the route is an app concern, and a menu row that leads somewhere unspecified is worse than no row.

import { UserMenu } from '@comitor/ui/shell'

// Each built-in row appears only when you hand it a route. No href, no row —
// the package will not invent /profile and send people to a 404.
<UserMenu
  profileHref="/account"
  settingsHref="/account/settings"
  helpHref="https://docs.acme.vn"
/>

// A single-purpose app can ship a menu that is nothing but the identity block,
// the appearance submenu and sign out.
<UserMenu />

Custom items

items is where the app’s own rows go. One field decides the element that is rendered: href makes a link, onSelect alone makes a button.

import { CreditCard, Keyboard, LogOut, UserPlus } from 'lucide-react'
import { UserMenu } from '@comitor/ui/shell'
import type { UserMenuItem } from '@comitor/ui/shell'

const items: UserMenuItem[] = [
  // href → a link, rendered through the shell's LinkComponent (next/link by
  // default), so onNavigate fires and the menu behaves like every other route
  // in the app. Cmd-click and middle-click still open a new tab.
  { id: 'billing', label: 'Billing', icon: CreditCard, href: '/account/billing' },

  // onSelect → a button. Use it for anything that opens a dialog or a panel.
  { id: 'invite', label: 'Invite teammates', icon: UserPlus, onSelect: () => openInvite() },

  // Both at once is legal: the link navigates AND onSelect fires — the hook
  // for analytics on a row that is genuinely a link.
  { id: 'plan', label: 'Upgrade plan', href: '/billing/plans', onSelect: () => track('upgrade') },

  // shortcut is a printed hint, nothing more. Register the key yourself.
  { id: 'shortcuts', label: 'Keyboard shortcuts', icon: Keyboard, shortcut: 'Ctrl /', onSelect: openHelp },

  // variant: 'destructive' paints the row with --destructive-ink.
  { id: 'leave', label: 'Leave workspace', icon: LogOut, variant: 'destructive', onSelect: confirmLeave },
]

<UserMenu items={items} />

• A link stays a link. With href the row renders as ShellNavLink inside the menu item, which means the app’s LinkComponent (next/link unless you swapped it), client-side navigation, a real href for ⌘-click, and a call to onNavigate.
• No external flag. NavItem has one; UserMenuItem does not. An off-domain href is handed to the router like any other. For a status page or external docs, either point helpHref at it (the built-in row has the same behaviour, so check your router forwards absolute URLs) or use onSelect and open the window yourself.
• shortcut prints, it does not bind. The string is a hint on the right of the row; the key handler is yours to register. Only the shell’s own four global keys (⌘K, ⌘⇧K, ⌘B, Alt+1…9) are wired, and they live on ShellProvider.
• variant: 'destructive' is red text, not a confirmation. It buys attention and nothing else. Anything genuinely irreversible should open a ConfirmDialog from its onSelect.

The appearance submenu

The menu carries one — and only one — of the four display axes: light / dark / system, written to the same next-themes store the standalone ThemeToggle writes to. The two are not identical controls: the header renders the toggle in its default variant="icon", one button that flips light ⇄ dark and never reaches “system”, while this submenu always offers all three — only variant="menu" matches it row for row. They are still two doors into one room, which is why the default is "mobile": AppHeader renders its ThemeToggle as hidden md:flex and the submenu trigger as md:hidden, so every width has exactly one entry point. Move one breakpoint without the other and you get a band of widths with two, or with none. The preview below forces the submenu on at every width.

• Hidden by CSS, not by a condition. "mobile" applies md:hidden. Deciding it in JavaScript would mean reading window during the first render, which is a hydration mismatch; and display: none takes the row out of the accessibility tree too, so a desktop screen-reader user is not offered a phantom row.
• It needs the provider that the toggle needs. The submenu calls useTheme() from next-themes, which — unlike useShell() — does not throw when the provider is missing: it returns a no-op setter. Without ThemeProvider at the root the three rows render and quietly do nothing, so pass showThemeSubmenu={false} in an app that has no theme provider.
• No mounted dance here. ThemeToggle holds an empty box until it mounts, because it is painted into the header on the first render and the real theme is only knowable on the client. The submenu needs nothing of the kind: menu content is mounted when the menu opens, which is always after hydration.
• The other three axes are not here. Colour palette, layout density and font size have their own providers and controls, documented on Display Axes. If your app exposes them, a settings page is the honest home — four submenus in a user menu is a preferences dialog wearing a disguise.

Signing out

The bottom row runs onLogout — the prop if you passed one, otherwise the handler on shell context. It is the app’s function: the package clears no session, calls no endpoint and knows no auth library.

import { ShellProvider, UserMenu } from '@comitor/ui/shell'

// Usual place: once on the provider, for every consumer of the shell.
<ShellProvider user={user} onLogout={() => signOut()}>
  <UserMenu />
</ShellProvider>

// Per-instance override — the prop wins over the context handler.
<UserMenu onLogout={() => signOutOfThisDeviceOnly()} />

// Neither one set? The row and the separator above it are not rendered at all,
// rather than rendering a dead "Sign out".
<ShellProvider user={user}>
  <UserMenu />
</ShellProvider>

• No handler, no row. The separator above it goes as well, so a read-only or SSO-managed surface ends cleanly at the last real entry instead of showing a button that cannot work.
• It fires on the first click. There is no confirmation step. If unsaved work is at stake, let onLogout open a ConfirmDialog and sign out from there.
• Red comes from the ink role. The row is --destructive-ink, not --destructive: the latter is the background role, the fill under white text on a delete button. In the default palette the ink token still points at it, so the two are one hex and the row measures 4.38:1 light, 4.06:1 dark. Writing the role token anyway is what lets data-contrast="high" move the row onto --red-ink and clear AA.

Inside AppShell

Apps rarely mount this component by hand. AppHeader puts it at the end of the right-hand cluster — app launcher, notifications, theme toggle, a hairline divider, then the menu — and forwards everything on this page through userMenuProps. The user itself comes from the provider, not from the header: with user null, both the divider and the menu are simply absent.

'use client'

import type { ReactNode } from 'react'
import { AppShell } from '@comitor/ui/shell'
import { signOut } from './auth'
import { NAV } from './nav'
import { USER_MENU_ITEMS } from './user-menu-items'

export function AppLayout({ children }: { children: ReactNode }) {
  return (
    <AppShell
      nav={NAV}
      user={{ id: 'u1', name: 'Nguyễn Đức Thành', email: '[email protected]', role: 'Quản trị viên' }}
      onLogout={signOut}
      headerProps={{
        // Everything here is forwarded straight to <UserMenu />.
        userMenuProps: {
          showName: true,
          profileHref: '/account',
          settingsHref: '/account/settings',
          items: USER_MENU_ITEMS,
        },
        // showUserMenu={false} drops the menu entirely — a kiosk or a public
        // read-only view. With no user in context it disappears on its own.
      }}
    >
      {children}
    </AppShell>
  )
}

The nine label keys it reads

Every string in the shell defaults to Vietnamese, screen-reader-only ones included, and every one is overridable key by key: labels on ShellProvider or AppShell is a Partial<ShellLabels> spread over DEFAULT_SHELL_LABELS. These nine are the ones this menu touches; the other 24 of the 33 belong to the sidebar, the switcher, the launcher and the standalone theme toggle.

Translate them as a set. An English account over Vietnamese visible rows gives a voice-control user a name they cannot see and a menu they cannot say — the same failure WCAG 2.5.3 is about, arriving from the other direction.

UserMenu props

UserAvatar props

ShellUser

The user contract of the whole shell — passed once to ShellProvider or AppShell and read from context by everything that needs it, including MobileMenu.

UserMenuItem

Accessibility

• The trigger is named by labels.account, always. It is a real <button type="button"> carrying aria-label, with aria-haspopup="menu" and aria-expanded supplied by Radix. The label overrides the initials inside it, so nobody hears “N T”.
• One caveat with showName. The visible text then reads “Nguyễn Đức Thành”, while the accessible name stays “Account”. The visible string is a value rather than a label, so the functional name is defensible — but if an audit reads it as WCAG 2.5.3 (Label in Name), the lever is showName={false}. Either way, keep labels.account a short word someone would actually say out loud.
• Menu semantics come from Radix. The popup is role="menu" with roving focus: arrow keys move, typeahead jumps, Esc closes and returns focus to the trigger, and focus is trapped while it is open. The appearance submenu opens with → or Enter and closes with ←.
• Rows suppress the page-wide focus ring on purpose. The base layer gives every focusable element a 2px --ring outline; menu items replace it with an --accent background, the convention for a list where focus moves under the arrow keys. The trigger keeps the standard ring.
• The identity block is not focusable. Rendered as a DropdownMenuLabel, it is read when the menu opens but never lands under an arrow key — arrowing down goes straight to the first row that does something.
• A link row is announced as a menu item. asChild puts role="menuitem" onto the anchor, so it loses the “link” announcement but keeps the real href — ⌘-click, middle-click and “copy link address” all still work.
• shortcut is read aloud. It is plain text in the row, not aria-hidden, so “Keyboard shortcuts Ctrl /” is the announced name. Keep the hint short and pronounceable; a wall of symbols is worse heard than seen.
• The selected theme is marked visually only. The current row in the appearance submenu gets an --accent background and no aria-checked, so a screen reader hears three equal choices. If your product needs the state announced, use a control of your own on a settings page and set showThemeSubmenu={false}.
• Sign out is not red alone. The label and the LogOut icon carry the meaning; the colour only raises it — which matters here, because the colour itself is short of the bar. In the default palette --destructive-ink resolves to --destructive (#D64545): 4.38:1 on the popover in light, 4.06:1 in dark. The remedy is the second palette — data-contrast="high" repoints the token at --red-ink and the row clears AA.
• Standalone UserAvatar names nobody. The photo is alt="" and the fallback is bare initials — correct inside a labelled trigger, silent or spelt out anywhere else. Outside the menu, either give the surrounding element the name, or use LetterAvatar, which carries an sr-only full name of its own.

Related