Skip to content

Commit 03b31d0

Browse files
wobsorianoalexisintech
wobsoriano
and
alexisintech
authored
(/customization/user-button) Add Vue examples; update copy (#1999)
Co-authored-by: Alexis Aguilar <[email protected]>
1 parent 61b8663 commit 03b31d0

File tree

1 file changed

+166
-30
lines changed

1 file changed

+166
-30
lines changed

‎docs/customization/user-button.mdx

Lines changed: 166 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,16 @@ description: Learn how to add custom items and include external links within the
55

66
The [`<UserButton />`](/docs/components/user/user-button) component supports _custom_ menu items, allowing the incorporation of app-specific settings or additional functionality.
77

8-
To add a custom menu item to the `<UserButton />` component, use the `<UserButton.MenuItems />` component.
9-
108
There are two types of custom menu items available:
119

12-
- `<UserButton.Action>` - A menu item that triggers an action when clicked.
13-
- `<UserButton.Link>` - A menu item that navigates to a page when clicked.
10+
- [`<UserButton.Action>`](#user-button-action) - A menu item that triggers an action when clicked.
11+
- [`<UserButton.Link>`](#user-button-link) - A menu item that navigates to a page when clicked.
1412

15-
> [!IMPORTANT]
16-
> If your app is rendered with [React Server Components](https://react.dev/reference/rsc/server-components) by default, you'll need to add the [`use client` directive](https://react.dev/reference/rsc/use-client) when using `<UserButton />`.
13+
You can also [reorder default items](#reorder-default-items) and [conditionally render menu items](#conditionally-render-menu-items).
1714

1815
## `<UserButton.Action>`
1916

20-
Custom actions can be rendered inside the `<UserButton />` component using the `<UserButton.Action />` component. This component is useful for adding actions like opening a chat or triggering a modal.
21-
22-
The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` component to render the custom action.
17+
`<UserButton.Action />` allows you to add actions to the `<UserButton />` component, like opening a chat or triggering a modal.
2318

2419
### Props
2520

@@ -53,11 +48,13 @@ The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` c
5348
A function to be called when the menu item is clicked.
5449
</Properties>
5550

56-
### Example
51+
### Examples
5752

58-
The following example demonstrates how to add an action to the `<UserButton />` component.
53+
#### Add an action
5954

60-
<Tabs items={["Next.js", "Astro", "JavaScript"]}>
55+
The following example adds an "Open chat" action to the `<UserButton />` component. When a user selects the `<UserButton />`, there will be an "Open chat" menu item.
56+
57+
<Tabs items={["Next.js", "Astro", "JavaScript", "Vue"]}>
6158
<Tab>
6259
```tsx filename="/app/page.tsx"
6360
'use client'
@@ -172,11 +169,41 @@ The following example demonstrates how to add an action to the `<UserButton />`
172169
})
173170
```
174171
</Tab>
172+
173+
<Tab>
174+
```vue filename="App.vue"
175+
<script setup lang="ts">
176+
import { UserButton } from '@clerk/vue'
177+
178+
function openChat() {
179+
alert('init chat')
180+
}
181+
</script>
182+
183+
<template>
184+
<header>
185+
<UserButton>
186+
<UserButton.MenuItems>
187+
<UserButton.Action label="Open chat" @click="openChat">
188+
<template #labelIcon>
189+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
190+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
191+
</svg>
192+
</template>
193+
</UserButton.Action>
194+
</UserButton.MenuItems>
195+
</UserButton>
196+
</header>
197+
</template>
198+
```
199+
</Tab>
175200
</Tabs>
176201

177-
The following example demonstrates how to add an action, as well as a [custom page](/docs/customization/user-profile), to the `<UserButton />` component.
202+
#### Add an action and a custom page
203+
204+
The following example adds an "Open chat" action to the `<UserButton />` component, as well as a [custom page](/docs/customization/user-profile) titled "Help". When a user selects the `<UserButton />`, there will be "Open chat" and "Help" menu items.
178205

179-
<Tabs items={["Next.js", "Astro"]}>
206+
<Tabs items={["Next.js", "Astro", "Vue"]}>
180207
<Tab>
181208
```tsx filename="/app/page.tsx"
182209
'use client'
@@ -255,13 +282,47 @@ The following example demonstrates how to add an action, as well as a [custom pa
255282
</header>
256283
```
257284
</Tab>
285+
286+
<Tab>
287+
```vue filename="App.vue"
288+
<script setup lang="ts">
289+
import { UserButton } from '@clerk/vue'
290+
</script>
291+
292+
<template>
293+
<header>
294+
<UserButton>
295+
<UserButton.MenuItems>
296+
<UserButton.Action label="Help" open="help">
297+
<template #labelIcon>
298+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
299+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
300+
</svg>
301+
</template>
302+
</UserButton.Action>
303+
</UserButton.MenuItems>
304+
305+
<UserButton.UserProfilePage label="Help" url="help">
306+
<template #labelIcon>
307+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
308+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
309+
</svg>
310+
</template>
311+
<div>
312+
<h1>Help Page</h1>
313+
<p>This is the custom help page</p>
314+
</div>
315+
</UserButton.UserProfilePage>
316+
</UserButton>
317+
</header>
318+
</template>
319+
```
320+
</Tab>
258321
</Tabs>
259322

260323
## `<UserButton.Link>`
261324

262-
Custom links can be rendered inside the `<UserButton />` component using the `<UserButton.Link />` component. This component is useful for adding links to custom pages or external URLs.
263-
264-
The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` component to render the custom link.
325+
`<UserButton.Link />` allows you to add links to the `<UserButton />` component, like custom pages or external URLs.
265326

266327
### Props
267328

@@ -290,9 +351,9 @@ The `<UserButton />` component must be wrapped in a `<UserButton.MenuItems />` c
290351

291352
### Example
292353

293-
The following example demonstrates how to add a link to the `<UserButton />` component.
354+
The following example adds a "Create organization" link to the `<UserButton />` component. When a user selects the `<UserButton />`, there will be a "Create organization" menu item.
294355

295-
<Tabs items={["Next.js", "Astro", "JavaScript"]}>
356+
<Tabs items={["Next.js", "Astro", "JavaScript", "Vue"]}>
296357
<Tab>
297358
```tsx filename="/app/page.tsx"
298359
'use client'
@@ -380,13 +441,39 @@ The following example demonstrates how to add a link to the `<UserButton />` com
380441
})
381442
```
382443
</Tab>
444+
445+
<Tab>
446+
```vue filename="App.vue"
447+
<script setup lang="ts">
448+
import { UserButton } from '@clerk/vue'
449+
</script>
450+
451+
<template>
452+
<header>
453+
<UserButton>
454+
<UserButton.MenuItems>
455+
<UserButton.Link label="Create organization" href="/create-organization">
456+
<template #labelIcon>
457+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
458+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
459+
</svg>
460+
</template>
461+
</UserButton.Link>
462+
</UserButton.MenuItems>
463+
</UserButton>
464+
</header>
465+
</template>
466+
```
467+
</Tab>
383468
</Tabs>
384469

385470
## Reorder default items
386471

387-
The `<UserButton />` component includes two default menu items: `Manage account` and `Sign out`. You can reorder these default items by setting the `label` prop to `'manageAccount'` or `'signOut'`. This will target the existing default item and allow you to rearrange it, as shown in the following example:
472+
The `<UserButton />` component includes two default menu items: `Manage account` and `Sign out`, in that order. You can reorder these default items by setting the `label` prop to `'manageAccount'` or `'signOut'`. This will target the existing default item and allow you to rearrange it.
473+
474+
In the following example, the "Sign out" menu item is moved to the top of the menu, a custom "Create organization" link is added as the second menu item, and the "Manage account" menu item is moved to the bottom of the menu.
388475

389-
<Tabs items={["Next.js", "Astro"]}>
476+
<Tabs items={["Next.js", "Astro", "Vue"]}>
390477
<Tab>
391478
```tsx filename="/app/page.tsx"
392479
'use client'
@@ -447,19 +534,41 @@ The `<UserButton />` component includes two default menu items: `Manage account`
447534
</header>
448535
```
449536
</Tab>
450-
</Tabs>
451537

452-
With the above example, the `<UserButton />` menu items will be in the following order:
538+
<Tab>
539+
```vue filename="App.vue"
540+
<script setup lang="ts">
541+
import { UserButton } from '@clerk/vue'
542+
</script>
453543
454-
1. Sign out
455-
1. Create organization
456-
1. Manage account
544+
<template>
545+
<header>
546+
<UserButton>
547+
<UserButton.MenuItems>
548+
<UserButton.Action label="signOut" />
549+
<UserButton.Link label="Create organization" href="/create-organization">
550+
<template #labelIcon>
551+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
552+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
553+
</svg>
554+
</template>
555+
</UserButton.Link>
556+
<UserButton.Action label="manageAccount" />
557+
</UserButton.MenuItems>
558+
</UserButton>
559+
</header>
560+
</template>
561+
```
562+
</Tab>
563+
</Tabs>
457564

458565
## Conditionally render menu items
459566

460-
To conditionally render menu items based on a user's role or custom permissions, you can use the [`has()`](/docs/references/backend/types/auth-object#has) helper function:
567+
To conditionally render menu items based on a user's role or custom permissions, you can use the [`has()`](/docs/references/backend/types/auth-object#has) helper function.
568+
569+
In the following example, the "Create organization" menu item will only render if the current user has the `org:app:admin` permission.
461570

462-
<Tabs items={["Next.js", "Astro"]}>
571+
<Tabs items={["Next.js", "Astro", "Vue"]}>
463572
<Tab>
464573
```tsx filename="/app/page.tsx"
465574
'use client'
@@ -534,6 +643,33 @@ To conditionally render menu items based on a user's role or custom permissions,
534643
</header>
535644
```
536645
</Tab>
537-
</Tabs>
538646

539-
With the above example, the "Create organization" menu item will only render if the current user has the `org:app:admin` permission.
647+
<Tab>
648+
```vue filename="App.vue"
649+
<script setup lang="ts">
650+
import { UserButton, useAuth } from '@clerk/vue'
651+
import { computed } from 'vue'
652+
653+
const { has, isLoaded } = useAuth()
654+
655+
const isAdmin = computed(() => has.value?.({ permission: 'org:app:admin' }))
656+
</script>
657+
658+
<template>
659+
<header v-if="isLoaded && isAdmin">
660+
<UserButton>
661+
<UserButton.MenuItems>
662+
<UserButton.Link label="Create organization" href="/create-organization">
663+
<template #labelIcon>
664+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
665+
<path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"></path>
666+
</svg>
667+
</template>
668+
</UserButton.Link>
669+
</UserButton.MenuItems>
670+
</UserButton>
671+
</header>
672+
</template>
673+
```
674+
</Tab>
675+
</Tabs>

0 commit comments

Comments
 (0)