Trigger app actions
A user menu needs to open an application modal, such as chat or help.
Clerk · Component
UserButton.MenuItems
UserButton.MenuItems is the Clerk container for adding custom actions and navigation links to a UserButton menu. It also supports arranging default entries and conditionally displaying menu items.
How it works
UserButton.MenuItems is the container for extending Clerk's user menu. Place UserButton.Action children inside it for click-driven behavior and UserButton.Link children for navigation; the same area can also contain reordered built-in items and conditionally rendered entries.
Syntax
<UserButton><UserButton.MenuItems>...</UserButton.MenuItems></UserButton>Parameters
| Name | Type | Description |
|---|---|---|
children | React nodes | Container for custom UserButton.Action and UserButton.Link children; the page does not specify standalone parameters for MenuItems. |
Returns
A customized UserButton menu containing the supplied custom entries.
Key points
- Use the container to add application-specific settings and other functionality to Clerk's user menu.
- The documented extension types are UserButton.Action and UserButton.Link.
- Choose Action when selecting the entry should invoke application behavior.
- Choose Link when selecting the entry should navigate to a destination.
- Besides adding entries, the menu supports changing built-in ordering and rendering entries conditionally.
- Use Clerk's has() helper to gate entries by role or custom permission.
Common mistakes
- The built-in menu starts with Manage account and Sign out, so custom ordering should account for those existing entries.
- Use the special labels manageAccount and signOut when repositioning the default items; ordinary display labels do not reorder them.
Example: Add custom UserButton menu items
import { UserButton } from '@clerk/nextjs';
export function AccountMenu() {
return (
<UserButton>
<UserButton.MenuItems>
<UserButton.Link label="Terms" href="/terms" />
<UserButton.Action
label="Open chat"
clickIdentifier="open_chat"
onClick={() => alert('Chat opened')}
/>
</UserButton.MenuItems>
</UserButton>
);
}This adds an internal navigation link and a custom action to the user menu.
When to use it
Add navigation links
Users need quick access to an internal settings route or an external resource.
Reorder account controls
Account controls must appear in a deliberate order alongside custom entries.
Gate entries by permissions
Administrative menu entries should appear only for authorized users.
Interview questions
QWhen should UserButton.Action and UserButton.Link be used?
Use UserButton.Action for behavior such as opening a chat or modal, and UserButton.Link when selecting the item should navigate to a page. Both are placed inside UserButton.MenuItems.
Follow-up: How would you make an entry available only to authorized users? Render the menu item conditionally using Clerk's has() helper with the user's role or custom permission.
QHow can the default UserButton entries be reordered?
The component provides Manage account and Sign out by default. Their positions can be changed by adding entries with labels manageAccount and signOut.
Follow-up: What additional menu behavior does the page describe? Custom entries can be conditionally rendered based on a user's role or custom permissions.
QWhat is the purpose of UserButton.MenuItems?
UserButton.MenuItems is the extension point inside UserButton for custom menu entries. It accepts action items for click handlers and link items for internal or external navigation.
Follow-up: How would you represent an app-specific settings destination? Use UserButton.Link with a label and an appropriate relative internal path or external URL.
Related
UserButtonUserButton.ActionUserButton.Linkhas()