UserButton

The <UserButton> component displays the signed-in user's avatar and a dropdown menu with account actions. It supports modal and navigation modes for opening the user profile, plus a composition API for custom menu items.

Installation

pnpm add @wocha/ui @wocha/react

Or scaffold with the CLI

npx @wocha/cli init --framework nextjs

import { UserButton } from "@wocha/ui";
import "@wocha/ui/styles.css";

Basic usage

<UserButton
  variant="full"
  profileUrl="/account"
  organisationUrl="/settings/organisation"
/>

Use variant="compact" for avatar-only display in dense headers.

Props

Prop	Type	Default	Description
`variant`	`"compact" \| "full"`	`"full"`	Compact shows avatar only; full shows name and email
`profileUrl`	`string`	—	Profile link — navigates on click
`organisationUrl`	`string`	—	Organisation settings link
`userProfileMode`	`"modal" \| "navigation"`	`"modal"`	How the user profile opens when "Manage account" is selected
`userProfileUrl`	`string`	—	Destination when `userProfileMode` is `"navigation"`
`userProfileProps`	`UserProfileProps`	—	Props forwarded to embedded `UserProfile` in modal mode
`appearance`	`WochaAppearance`	—	Visual customisation
`className`	`string`	—	Additional class name
`menuItems`	`Array<{ label, icon?, onClick }>`	`[]`	Custom menu items appended before sign out
`children`	`ReactNode`	—	Composition children (`UserButton.MenuItems`, etc.)
`fallback`	`ReactNode`	—	Shown while auth context is loading

Open the profile in an overlay (default) or navigate to a dedicated page:

// Modal — opens UserProfile in an overlay
<UserButton userProfileMode="modal" />
 
// Navigation — routes to /account
<UserButton
  userProfileMode="navigation"
  userProfileUrl="/account"
/>

Composition API

Extend or reorder menu items with compound sub-components:

<UserButton>
  <UserButton.MenuItems>
    <UserButton.Action label="Help" onClick={openHelp} />
    <UserButton.Link label="Billing" href="/billing" />
    <UserButton.Action label="signOut" onClick={customSignOut} />
  </UserButton.MenuItems>
</UserButton>

Use default item keys (manageAccount, organisation, signOut) as label values to reorder or replace built-in entries.

Theming

<WochaThemeProvider
  appearance={{
    userButton: {
      variables: { "--wocha-color-primary": "#818cf8" },
    },
  }}
>
  <UserButton />
</WochaThemeProvider>

Framework notes

Framework	Notes
React SPA	Place in your app header inside `WochaProvider`
Next.js	Works in client components; use `userProfileUrl` for App Router pages

UserButton

On this page