diff --git a/docs/customization/organization-profile.mdx b/docs/customization/organization-profile.mdx
index 07831d40a7..e3d1210f33 100644
--- a/docs/customization/organization-profile.mdx
+++ b/docs/customization/organization-profile.mdx
@@ -3,34 +3,22 @@ title: Add custom pages and links to the `` component
description: Learn how to add custom pages and include external links within the navigation sidebar of the component.
---
-The [``](/docs/components/organization/organization-profile) component supports the addition of custom pages and use of external links in the navigation sidebar.
+The [``](/docs/components/organization/organization-profile) component supports the addition of custom pages and external links to the component's sidenav.
-There are two ways to render the `` component:
+## Before you start
-- As a modal
-- As a dedicated page
-
-Both can be accessed when the user selects the [``](/docs/components/organization/organization-switcher), and then selects the **Manage Organization** option.
-
-This guide includes examples for both use cases. You can select one of the following two tabs on the code examples to see the implementation for your preferred use case:
+To access the `` component, the user must select the [``](/docs/components/organization/organization-switcher) component and then select the **Manage Organization** option. The `` will open as a modal by default. You can also render the component as a dedicated page. This guide includes examples for both use cases. On the code examples, you can select one of the following two tabs to see the implementation for your preferred use case:
- `` tab: By default, the `` sets `organizationProfileMode='modal'`. If you are using the default settings, then you should select this tab.
- `Dedicated page` tab: If you do not want the `` to open as a modal, then you should select this tab. For these examples, you need to set `organizationProfileMode='navigation'` and `organizationProfileUrl='/organization-profile'` on the `` component.
-For the sake of this guide, examples are written for Next.js App Router, but they are supported by any React meta framework, such as Remix.
-
-> [!IMPORTANT]
-> 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 ``.
-
-## Add a custom page to ``
-
-Custom pages can be rendered inside the `` component and provide a way to incorporate app-specific settings or additional functionality.
+## Add a custom page
To add a custom page to the `` component, use the `` component or the `` component, depending on your use case.
### Props
-`` and `` accept the following props, all of which are _required_:
+`` and `` accept the following props, all of which are **required**:
- `label`
@@ -50,176 +38,230 @@ To add a custom page to the `` component, use the `` component is rendered at `/organization`, then the custom page will be accessed at `/organization/{url}` when using path routing).
+ The path segment that will be used to navigate to the custom page. For example, if the `` component is rendered at `/organization`, then the custom page will be accessed at `/organization/{url}` when using [path routing](/docs/how-clerk-works/routing).
---
- `children`
- `React.ReactElement`
- The components to be rendered as content inside the custom page.
+ The content to be rendered inside the custom page.
### Example
-The following example demonstrates two ways that you can render content in the `` or `` component: as a component or as a direct child.
-
-", "Dedicated page"]}>
- ```tsx {{ filename: 'app/components/Header.tsx' }}
- 'use client'
-
- import { OrganizationSwitcher } from '@clerk/nextjs'
-
- const DotIcon = () => {
- return (
-
- )
- }
-
- const CustomPage = () => {
- return (
-
-
Custom Organization Profile Page
-
This is the custom organization profile page
-
- )
- }
-
- const Header = () => (
-
-
- {/* You can pass the content as a component */}
- }
- >
-
-
-
- {/* You can also pass the content as direct children */}
- }
- url="terms"
- >
+
+
+ The following example demonstrates two ways that you can render content in a custom page: as a component or as a direct child.
+
+ ", "Dedicated page"]}>
+ ```tsx {{ filename: 'app/components/Header.tsx' }}
+ 'use client'
+
+ import { OrganizationSwitcher } from '@clerk/nextjs'
+
+ const DotIcon = () => {
+ return (
+
+ )
+ }
+
+ const CustomPage = () => {
+ return (
- )
- }
-
- const OrganizationProfilePage = () => (
-
- {/* You can pass the content as a component */}
- } url="custom-page">
-
-
-
- {/* You can also pass the content as direct children */}
- } url="terms">
-
-
Custom Terms Page
-
This is the custom terms page
-
-
-
- )
-
- export default OrganizationProfilePage
- ```
-
-
-### JavaScript example
-
-To add custom pages to the `` component using the [JavaScript SDK](/docs/references/javascript/overview), you can pass the `customPages` property to the `mountOrganizationProfile()` or `openOrganizationProfile()` method, as shown in the following example:
-
-```js {{ filename: 'main.js' }}
-import { Clerk } from '@clerk/clerk-js'
-
-const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
-
-const clerk = new Clerk(pubKey)
-await clerk.load()
-
-document.getElementById('app').innerHTML = `
-
-`
-
-const orgProfileDiv = document.getElementById('organization-profile')
-
-clerk.openOrganizationProfile(orgProfileDiv, {
- customPages: [
- {
- url: 'custom-page',
- label: 'Custom Page',
- mountIcon: (el) => {
- el.innerHTML = 'π'
- },
- unmountIcon: (el) => {
- el.innerHTML = ''
- },
- mount: (el) => {
- el.innerHTML = `
-
Custom Page
-
This is the content of the custom page.
- `
- },
- unmount: (el) => {
- el.innerHTML = ''
- },
- },
- {
- url: '/other-page',
- label: 'Other Page',
- mountIcon: (el) => {
- el.innerHTML = 'π'
- },
- unmountIcon: (el) => {
- el.innerHTML = ''
- },
- },
- ],
-})
-```
-
-## Add a custom link to ``
-
-You can add external links to the `` navigation sidebar using the `` component or the `` component, depending on your use case.
+ )
+ }
+
+ const Header = () => (
+
+
+ {/* You can pass the content as a component */}
+ }
+ >
+
+
+
+ {/* You can also pass the content as direct children */}
+ }
+ url="terms"
+ >
+
+ )
+ }
+
+ const OrganizationProfilePage = () => (
+
+ {/* You can pass the content as a component */}
+ } url="custom-page">
+
+
+
+ {/* You can also pass the content as direct children */}
+ } url="terms">
+
+
Custom Terms Page
+
This is the content of the custom terms page.
+
+
+
+ )
+
+ export default OrganizationProfilePage
+ ```
+
+
+
+
+ To add custom pages to the `` component using the [JavaScript SDK](/docs/references/javascript/overview), pass the `customPages` property to the `mountOrganizationProfile()` or `openOrganizationProfile()` method, as shown in the following example:
+
+ ```js {{ filename: 'main.js' }}
+ import { Clerk } from '@clerk/clerk-js'
+
+ const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+
+ const clerk = new Clerk(pubKey)
+ await clerk.load()
+
+ document.getElementById('app').innerHTML = `
+
+ `
+
+ const orgProfileDiv = document.getElementById('organization-profile')
+
+ clerk.openOrganizationProfile(orgProfileDiv, {
+ customPages: [
+ {
+ url: 'custom-page',
+ label: 'Custom Page',
+ mountIcon: (el) => {
+ el.innerHTML = 'π'
+ },
+ unmountIcon: (el) => {
+ el.innerHTML = ''
+ },
+ mount: (el) => {
+ el.innerHTML = `
+
+
+
+
+ ```
+
+
+
+
+## Add a custom link
+
+To add an external link to the `` navigation sidebar, use the `` component or the `` component, depending on your use case.
### Props
-`` and `` accept the following props, all of which are _required_:
+`` and `` accept the following props, all of which are **required**:
- `label`
@@ -239,162 +281,271 @@ You can add external links to the `` navigation sidebar u
- `url`
- `string`
- The absolute or relative url to navigate to.
+ The full URL or path that will be used to navigate to the external link. For path segments, if the `` component is rendered at `/organization`, then the external link will be accessed at `/organization/{url}` when using [path routing](/docs/how-clerk-works/routing).
### Example
-The following example adds a link to the homepage in the navigation sidebar of the `` component.
-
-", "Dedicated page"]}>
- ```tsx {{ filename: 'app/components/Header.tsx' }}
- 'use client'
-
- import { OrganizationSwitcher } from '@clerk/nextjs'
-
- const DotIcon = () => {
- return (
-
- )
- }
-
- const Header = () => (
-
-
- }
- />
-
-
- )
-
- export default Header
- ```
-
- ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }}
- 'use client'
-
- import { OrganizationProfile } from '@clerk/nextjs'
-
- const DotIcon = () => {
- return (
-
- )
- }
-
- const OrganizationProfilePage = () => (
-
- } url="/" />
-
- )
-
- export default OrganizationProfilePage
- ```
-
+The following example adds a custom link to the `` sidenav that navigates to the homepage.
-## Reordering default routes
+
+
+ ", "Dedicated page"]}>
+ ```tsx {{ filename: 'app/components/Header.tsx' }}
+ 'use client'
+
+ import { OrganizationSwitcher } from '@clerk/nextjs'
+
+ const DotIcon = () => {
+ return (
+
+ )
+ }
+
+ const Header = () => (
+
+
+ }
+ />
+
+
+ )
-If you want to reorder the default routes, `Members` and `General`, set the `label` prop to `'members'` or `'general'`. This will target the existing default page and allow you to rearrange it.
+ export default Header
+ ```
-Note that when reordering default routes, the first item in the navigation sidebar cannot be a `` or `` component.
+ ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }}
+ 'use client'
-", "Dedicated Page"]}>
-
- ```tsx {{ filename: 'app/components/Header.tsx' }}
- 'use client'
+ import { OrganizationProfile } from '@clerk/nextjs'
- import { OrganizationSwitcher } from '@clerk/nextjs'
+ const DotIcon = () => {
+ return (
+
+ )
+ }
- const DotIcon = () => {
- return (
-
- )
- }
-
- const CustomPage = () => {
- return (
-
-
Custom Organization Profile Page
-
This is the custom organization profile page
-
+ const OrganizationProfilePage = () => (
+
+ } url="/" />
+
)
- }
-
- const Header = () => (
-
-
- }
- >
-
-
- }
- />
-
-
-
-
- )
-
- export default Header
- ```
+
+ export default OrganizationProfilePage
+ ```
+
- ```tsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }}
- 'use client'
+ ", "Dedicated page"]}>
+ ```vue {{ filename: 'App.vue' }}
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ ```vue {{ filename: 'pages/organization-profile.vue' }}
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+
+
+
+## Reordering default routes
+
+The `` component includes two default menu items: `Members` and `General`, in that order. You can reorder these default items by setting the `label` prop to `'members'` or `'general'`. This will target the existing default item and allow you to rearrange it.
- import { OrganizationProfile } from '@clerk/nextjs'
+Note that when reordering default routes, the first item in the navigation sidebar cannot be a custom link.
- const DotIcon = () => {
- return (
-
+The following example adds a custom page as the first item in the sidenav, followed by a custom link to the homepage, and then the default members and general pages.
+
+
+
+ ", "Dedicated Page"]}>
+ ```tsx {{ filename: 'app/components/Header.tsx' }}
+ 'use client'
+
+ import { OrganizationSwitcher } from '@clerk/nextjs'
+
+ const DotIcon = () => {
+ return (
+
+ )
+ }
+
+ const CustomPage = () => {
+ return (
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+
+
diff --git a/docs/customization/user-profile.mdx b/docs/customization/user-profile.mdx
index 4595ba6a87..5147eceb9e 100644
--- a/docs/customization/user-profile.mdx
+++ b/docs/customization/user-profile.mdx
@@ -3,32 +3,22 @@ title: Add custom pages and links to the `` component
description: Learn how to add custom pages and include external links within the navigation sidebar of the component.
---
-The [``](/docs/components/user/user-profile) component supports the addition of custom pages and use of external links in the navigation sidebar.
+The [``](/docs/components/user/user-profile) component supports the addition of custom pages and external links to the component's sidenav.
-There are two ways to render the `` component:
+## Before you start
-- As a modal
-- As a dedicated page
-
-Both can be accessed when the user selects the [``](/docs/components/user/user-button), and then selects the **Manage account** option.
-
-This guide includes examples for both use cases. You can select one of the following two tabs on the code examples to see the implementation for your preferred use case:
+To access the `` component, the user must select the [``](/docs/components/user/user-button) component and then select the **Manage account** menu item. The `` will open as a modal by default. You can also render the component as a dedicated page. This guide includes examples for both use cases. On the code examples, you can select one of the following two tabs to see the implementation for your preferred use case:
- `` tab: By default, the `` sets `userProfileMode='modal'`. If you are using the default settings, then you should select this tab.
- `Dedicated page` tab: If you do not want the `` to open as a modal, then you should select this tab. For these examples, you need to set `userProfileMode='navigation'` and `userProfileUrl='/user-profile'` on the `` component.
-> [!IMPORTANT]
-> 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 ``.
-
-## Add a custom page to ``
-
-Custom pages can be rendered inside the `` component and provide a way to incorporate app-specific settings or additional functionality.
+## Add a custom page
To add a custom page to the `` component, use the `` component or the `` component, depending on your use case.
### Props
-`` and `` accept the following props, all of which are _required_:
+`` and `` accept the following props, all of which are **required**:
- `label`
@@ -55,15 +45,15 @@ To add a custom page to the `` component, use the `
### Example
-The following example demonstrates two ways that you can render content in the `` or `` component: as a component or as a direct child.
-
-
+
+ The following example demonstrates two ways that you can render content in a custom page: as a component or as a direct child.
+
", "Dedicated page"]}>
```tsx {{ filename: 'app/page.tsx' }}
'use client'
@@ -81,8 +71,8 @@ The following example demonstrates two ways that you can render content in the `
const CustomPage = () => {
return (
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
)
}
@@ -100,7 +90,7 @@ The following example demonstrates two ways that you can render content in the `
} url="terms">
Custom Terms Page
-
This is the custom terms page
+
This is the content of the custom terms page.
@@ -125,8 +115,8 @@ The following example demonstrates two ways that you can render content in the `
const CustomPage = () => {
return (
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
)
}
@@ -142,7 +132,7 @@ The following example demonstrates two ways that you can render content in the `
} url="terms">
Custom Terms Page
-
This is the custom terms page
+
This is the content of the custom terms page.
@@ -153,6 +143,59 @@ The following example demonstrates two ways that you can render content in the `
+
+ To add custom pages to the `` component using the [JavaScript SDK](/docs/references/javascript/overview), pass the `customPages` property to the `mountUserProfile()` method, as shown in the following example:
+
+ ```js {{ filename: 'main.js' }}
+ import { Clerk } from '@clerk/clerk-js'
+
+ const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
+
+ const clerk = new Clerk(pubKey)
+ await clerk.load()
+
+ document.getElementById('app').innerHTML = `
+
+ `
+
+ const userProfileDiv = document.getElementById('user-profile')
+
+ clerk.mountUserProfile(userProfileDiv, {
+ customPages: [
+ {
+ url: 'custom-page',
+ label: 'Custom Page',
+ mountIcon: (el) => {
+ el.innerHTML = 'π'
+ },
+ unmountIcon: (el) => {
+ el.innerHTML = ''
+ },
+ mount: (el) => {
+ el.innerHTML = `
+
Custom Page
+
This is the content of the custom page.
+ `
+ },
+ unmount: (el) => {
+ el.innerHTML = ''
+ },
+ },
+ {
+ url: '/other-page',
+ label: 'Other Page',
+ mountIcon: (el) => {
+ el.innerHTML = 'π'
+ },
+ unmountIcon: (el) => {
+ el.innerHTML = ''
+ },
+ },
+ ],
+ })
+ ```
+
+
", "Dedicated page"]}>
```astro {{ filename: 'pages/index.astro' }}
@@ -172,8 +215,8 @@ The following example demonstrates two ways that you can render content in the `
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
@@ -196,76 +239,73 @@ The following example demonstrates two ways that you can render content in the `
+
+
+
+ ```
+
+
-### JavaScript example
-
-To add custom pages to the `` component using the [JavaScript SDK](/docs/references/javascript/overview), you can pass the `customPages` property to the `mountUserProfile()` method, as shown in the following example:
-
-```js {{ filename: 'main.js' }}
-import { Clerk } from '@clerk/clerk-js'
-
-const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
-
-const clerk = new Clerk(pubKey)
-await clerk.load()
-
-document.getElementById('app').innerHTML = `
-
-`
-
-const userProfileDiv = document.getElementById('user-profile')
-
-clerk.mountUserProfile(userProfileDiv, {
- customPages: [
- {
- url: 'custom-page',
- label: 'Custom Page',
- mountIcon: (el) => {
- el.innerHTML = 'π'
- },
- unmountIcon: (el) => {
- el.innerHTML = ''
- },
- mount: (el) => {
- el.innerHTML = `
-
Custom Page
-
This is the content of the custom page.
- `
- },
- unmount: (el) => {
- el.innerHTML = ''
- },
- },
- {
- url: '/other-page',
- label: 'Other Page',
- mountIcon: (el) => {
- el.innerHTML = 'π'
- },
- unmountIcon: (el) => {
- el.innerHTML = ''
- },
- },
- ],
-})
-```
-
-## Add a custom link to \
-
-You can add external links to the `` navigation sidebar using the `` component or the `` component, depending on your use case.
+## Add a custom link
+
+To add a custom link to the `` component, use the `` component or the `` component, depending on your use case.
### Props
-`` and `` accept the following props, all of which are _required_:
+`` and `` accept the following props, all of which are **required**:
- `label`
@@ -285,14 +325,14 @@ You can add external links to the `` navigation sidebar using the
- `url`
- `string`
- The absolute or relative url to navigate to
+ The path segment that will be used to navigate to the custom page. For example, if the `` component is rendered at `/user`, then the custom link will be navigate to `/user/{url}` when using [path routing](/docs/how-clerk-works/routing).
### Example
-The following example adds a link to the homepage in the navigation sidebar of the `` component.
+The following example adds a custom link to the `` sidenav that navigates to the homepage.
-
+", "Dedicated page"]}>
```tsx {{ filename: 'app/page.tsx' }}
@@ -386,15 +426,59 @@ The following example adds a link to the homepage in the navigation sidebar of t
```
+
+
+ ", "Dedicated page"]}>
+ ```vue {{ filename: 'App.vue' }}
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ ```vue {{ filename: 'pages/user-profile.vue' }}
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+
## Reorder default routes
-If you want to reorder the default routes, `Account` and `Security`, set the `label` prop to `'account'` or `'security'`. This will target the existing default page and allow you to rearrange it.
+The `` component includes two default menu items: `Account` and `Security`, in that order. You can reorder these default items by setting the `label` prop to `'account'` or `'security'`. This will target the existing default item and allow you to rearrange it.
+
+Note that when reordering default routes, the first item in the navigation sidebar cannot be a custom link.
-Note that when reordering default routes, the first item in the navigation sidebar cannot be a `` or `` component.
+The following example adds a custom page as the first item in the sidenav, followed by a custom link to the homepage, and then the default account and security pages.
-
+", "Dedicated page"]}>
@@ -414,8 +498,8 @@ Note that when reordering default routes, the first item in the navigation sideb
const CustomPage = () => {
return (
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
)
}
@@ -454,8 +538,8 @@ Note that when reordering default routes, the first item in the navigation sideb
const CustomPage = () => {
return (
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
)
}
@@ -497,8 +581,8 @@ Note that when reordering default routes, the first item in the navigation sideb
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
@@ -535,8 +619,8 @@ Note that when reordering default routes, the first item in the navigation sideb
-
Custom Profile Page
-
This is the custom profile page
+
Custom page
+
This is the content of the custom page.
@@ -556,11 +640,70 @@ Note that when reordering default routes, the first item in the navigation sideb
-
-With the above example, the `` navigation sidebar will be in the following order:
+
+ ", "Dedicated page"]}>
+ ```vue {{ filename: 'App.vue' }}
+
-1. Custom Page
-1. Homepage
-1. Account
-1. Security
+
+
+
+
+
+
+