UserButton

<UserButton> renders the signed-in user’s initials as a button that opens a dropdown menu containing a “Manage profile” item, an optional language switcher, and sign-out. It’s the equivalent of the account menu in the top-right of most apps.

By default, “Manage profile” opens the full <UserProfile> widget in a modal, no wiring required. Switch to userProfileMode="navigation" if you’d rather route to your own account page.

The dropdown’s open/close state, the profile modal, click-outside, and keyboard navigation are handled inside the SDK runtime; you just place the component.

When to use

Place it inside <SignedIn>, since it requires an authenticated session.

Usage

import { SignedIn, UserButton } from '@torii-js/torii-react';

function Header({ profile }) {
  return (
    <SignedIn>
      {/* Default: clicking "Manage profile" opens the profile modal. */}
      <UserButton profile={profile} />
    </SignedIn>
  );
}

To route to your own account page instead of the modal:

<UserButton
  profile={profile}
  userProfileMode="navigation"
  onManageProfile={() => navigate('/account')}
/>

Props

Prop	Type	Default	Description
profile	UserProfileData | null	null	Used for the display name and initials. Falls back to the first 8 chars of the user ID when omitted.
userProfileMode	'modal' | 'navigation'	'modal'	'modal' opens <UserProfile> in a dialog. 'navigation' fires onManageProfile instead.
onManageProfile	() => void	n/a	Called when “Manage profile” is clicked, in 'navigation' mode only. The item is hidden when omitted and not in modal mode.
showLanguage	boolean	auto	Forwarded to the profile modal’s <UserProfile showLanguage> (modal mode only). Controls the Language row on the Profile section; defaults to auto (shown when more than one language is configured).
appearancePreference	'light' | 'dark' | 'system'	n/a	Forwarded to the profile modal’s Appearance preference; see <UserProfile>.
onAppearancePreferenceChange	(value) => void	n/a	Forwarded alongside appearancePreference.
variant	'icon' | 'expanded'	'icon'	'icon' shows just the avatar; 'expanded' shows an identity row (avatar plus display name and email) suited to sidebar footers and account bars.
className	string	n/a	Extra class names for the trigger button.

Language switching moved. Earlier versions had a language switcher in this dropdown. It now lives in the <UserProfile> Profile section as a Language row, shown automatically when <ToriiProvider> is configured with more than one languages entry. UserButton no longer takes languages / currentLanguage / onLanguageChange.

Behaviour

• Requires a provider: must be rendered within <ToriiProvider>; it reads signOut, user, and labels from context.
• Sign-out: the menu’s sign-out item calls the SDK’s own signOut. Drive any post-sign-out routing off useAuth().isSignedIn flipping to false, or events.onSessionExpired.
• Initials: derived from profile.name, then profile.email, then the fallback display name.
• Powered by Torii: the dropdown shows a brand ribbon at its bottom edge, with the same visibility gating as the auth-card footer (appearance.hideFooter, available on paid plans).

Theming

The trigger and menu slots (menuContent, menuItem, menuSeparator, destructiveButton) are themable via the appearance.elements prop on <ToriiProvider>. See elements.

TypeScript

import type { UserButtonProps } from '@torii-js/torii-react';