Custom application navigation
Provide access to legal or help pages from the account menu.
Clerk · Component
UserButton.Link
UserButton.Link adds a custom navigational item to Clerk’s UserButton menu. It requires a destination, visible label, and icon, and supports links to custom pages or external URLs.
How it works
UserButton.Link is a required-prop menu-item component placed inside UserButton.MenuItems. It renders a labeled entry with an icon and navigates to the supplied path or external URL when selected.
Syntax
<UserButton.Link href="..." label="..." labelIcon={<Icon />} />Parameters
| Name | Type | Description |
|---|---|---|
href | string | Destination path or URL used for navigation. |
label | string | Text displayed for the menu item. |
labelIcon | React.ReactElement | React element displayed beside the label. |
Returns
A custom navigational menu item rendered inside UserButton.
Key points
- Use UserButton.Link to expose custom destinations directly from the UserButton menu.
- The destination may represent an application page or an external web address.
- Selecting the entry performs navigation rather than invoking a custom click handler.
- label controls the text shown to users in the menu.
- labelIcon provides the visual icon rendered beside the label.
Common mistakes
- Provide href, label, and labelIcon; the documentation marks every UserButton.Link prop as required.
Example: Add a custom UserButton link
import { UserButton } from "@clerk/nextjs";
export default function AccountMenu() {
return (
<UserButton>
<UserButton.MenuItems>
<UserButton.Link
label="Terms"
labelIcon={<span aria-hidden="true">📄</span>}
href="/terms"
/>
</UserButton.MenuItems>
</UserButton>
);
}Adds a Terms entry to the UserButton menu that navigates to the app's /terms route.
When to use it
External resources
Send users to a destination outside the current application.
Interview questions
QWhat is UserButton.Link used for?
UserButton.Link adds a navigation item to UserButton. It is intended for custom pages or external URLs and is placed within UserButton.MenuItems.
Follow-up: How would you add behavior instead of navigation? Use UserButton.Action, which is the other custom menu-item type documented on the page.
QWhich props must be supplied?
The link requires href, label, and labelIcon. href supplies the destination, label supplies the visible menu name, and labelIcon supplies the adjacent React element.
Follow-up: What must be changed to invoke application logic rather than navigate? Replace the link with UserButton.Action and configure its action-related props.
QWhat happens when a user clicks the item?
The component navigates when the user selects the menu item. Its destination can be an app path, such as /terms, or an external URL.
Follow-up: How can the menu contain both navigation and commands? Add multiple children under UserButton.MenuItems, mixing UserButton.Link and UserButton.Action entries.
Related
UserButtonUserButton.MenuItemsUserButton.Action