diff --git a/docs/_partials/expo/web-only-callout.mdx b/docs/_partials/expo/web-only-callout.mdx index 95a2eec5aa..c2225f14d9 100644 --- a/docs/_partials/expo/web-only-callout.mdx +++ b/docs/_partials/expo/web-only-callout.mdx @@ -1,2 +1,2 @@ > [!NOTE] -> This component can be used in Expo Web projects, but won't work in native environments (iOS or Android). For native apps, use the supported native components instead. +> This component can be used in Expo Web projects, but it isn't available in native environments (iOS or Android). For native apps, build a custom UI using Clerk hooks. See [custom flows guides](/docs/guides/development/custom-flows/overview) for details. diff --git a/docs/_partials/javascript/clerk-options.mdx b/docs/_partials/javascript/clerk-options.mdx new file mode 100644 index 0000000000..4eead510fc --- /dev/null +++ b/docs/_partials/javascript/clerk-options.mdx @@ -0,0 +1,141 @@ +The `load()` method accepts an optional object that accepts the following props. All props are optional. + + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect \[Clerk components]\[components-ref] and not \[Account Portal]\[ap-ref] pages. + + --- + + - `localization` + - [Localization](/docs/guides/customizing-clerk/localization) | undefined + + Optional object to localize your components. Will only affect \[Clerk components]\[components-ref] and not \[Account Portal]\[ap-ref] pages. + + --- + + - `routerPush?` + - `(to: string) => Promise | void` + + A function which takes the destination path as an argument and performs a "push" navigation. + + --- + + - `routerReplace?` + - `(to: string) => Promise | void` + + A function which takes the destination path as an argument and performs a "replace" navigation. + + --- + + - `polling` + - `boolean | undefined` + + Dictates if we should poll against Clerk's backend every 5 minutes. Defaults to `true`. + + --- + + - `selectInitialSession` + - ((client: \[Client]\[client-ref]) => Session | null) | undefined + + An optional function which allows you to control which active session is the initial session to base a user's state off of. Defaults to the first session in the client's sessions array. + + --- + + - `standardBrowser` + - `boolean | undefined` + + Controls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to `true`. + + --- + + - `supportEmail` + - `string | undefined` + + Optional support email for display in authentication screens. + + --- + + - `touchSession` + - `boolean | undefined` + + Indicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to `true`. + + --- + + - `signInUrl` + - `string | undefined` + + The default URL to use to direct to when the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpUrl` + - `string | undefined` + + The default URL to use to direct to when the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signInForceRedirectUrl?` + - `string` + + If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpForceRedirectUrl?` + - `string` + + If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signInFallbackRedirectUrl?` + - `string` + + The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpFallbackRedirectUrl?` + - `string` + + The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `afterSignOutUrl?` + - `string` + + The full URL or path to navigate to after a successful sign-out. + + --- + + - `allowedRedirectOrigins?` + - `Array` + + An optional array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console. + + --- + + - `allowedRedirectProtocols?` + - `Array` + + An optional array of protocols to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console. + + --- + + - `isSatellite` + - `boolean | ((url: URL) => boolean) | undefined` + + Clerk flag for satellite apps. Experimental. + + --- + + - `telemetry?` + - `false | { disabled?: boolean; debug?: boolean } | undefined` + + Controls whether or not Clerk will collect [telemetry data](/docs/guides/how-clerk-works/security/clerk-telemetry). + diff --git a/docs/guides/configure/auth-strategies/web3/metamask.mdx b/docs/guides/configure/auth-strategies/web3/metamask.mdx index 238f697ee8..ea27842c3e 100644 --- a/docs/guides/configure/auth-strategies/web3/metamask.mdx +++ b/docs/guides/configure/auth-strategies/web3/metamask.mdx @@ -15,6 +15,9 @@ description: Learn how to set up Web3 authentication with MetaMask. Enabling [MetaMask](https://metamask.io/) as a Web3 provider allows your users to sign in and up to your Clerk application with their MetaMask wallet. +> [!IMPORTANT] +> MetaMask authentication is not supported when using the **Clerk Chrome Extension SDK**, as it cannot load third-party code per Chrome Web Store policies. + ## Enable MetaMask as a Web3 provider 1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page. diff --git a/docs/guides/development/upgrading/upgrade-guides/core-2/react.mdx b/docs/guides/development/upgrading/upgrade-guides/core-2/react.mdx index f5df83c8ed..a58b86c449 100644 --- a/docs/guides/development/upgrading/upgrade-guides/core-2/react.mdx +++ b/docs/guides/development/upgrading/upgrade-guides/core-2/react.mdx @@ -596,7 +596,7 @@ As part of this major version, a number of previously deprecated props, argument - The `membershipList` param from the `useOrganization` hook has been removed. Instead, [use the `memberships` param](/docs/reference/hooks/use-organization#parameters). Examples of each can be seen here: + The `membershipList` param from the `useOrganization` hook has been removed. Instead, [use the `memberships` param](/docs/reference/hooks/use-organization#properties). Examples of each can be seen here: ```js // before diff --git a/docs/guides/secure/reverification.mdx b/docs/guides/secure/reverification.mdx index cc704c7065..cc56a0e0d4 100644 --- a/docs/guides/secure/reverification.mdx +++ b/docs/guides/secure/reverification.mdx @@ -221,7 +221,7 @@ The following example demonstrates how to use the [`useReverification()`](/docs/ ```tsx {{ filename: '/src/components/TransferButton.js' }} - import { useReverification } from '@clerk/react' + import { useReverification } from '@clerk/clerk-react' export function TransferButton({ amount_in_cents }: { amount_in_cents: number }) { const transferMoney = useReverification(() => diff --git a/docs/reference/components/authentication/google-one-tap.mdx b/docs/reference/components/authentication/google-one-tap.mdx index 9e8b8617f1..5638feb5a5 100644 --- a/docs/reference/components/authentication/google-one-tap.mdx +++ b/docs/reference/components/authentication/google-one-tap.mdx @@ -9,54 +9,17 @@ sdk: astro, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start The `` component renders the [Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) UI so that users can use a single button to sign-up or sign-in to your Clerk application with their Google accounts. -By default, this component will redirect users back to the page where the authentication flow started. However, you can override this with [force redirect URL props](#google-one-tap-props) or [force redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). +By default, this component will redirect users back to the page where the authentication flow started. However, you can override this with [force redirect URL props](#properties) or [force redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). -## `GoogleOneTapProps` - - - - `cancelOnTapOutside?` - - `boolean` - - If `true`, the One Tap prompt closes automatically if the user clicks outside of the prompt. Default: `true`. - - --- - - - `itpSupport?` - - `boolean` - - If `true`, enables the [ITP-specific UX](https://developers.google.com/identity/gsi/web/guides/itp) when One Tap is rendered on ITP browsers such as Chrome on iOS, Safari, and FireFox. Default: `true`. - - --- - - - `fedCmSupport?` - - `boolean` - - If `true`, enables Google One Tap to use [the FedCM API](https://developers.google.com/privacy-sandbox/3pcd/fedcm) to sign users in. See Google's docs on [best practices when disabling FedCM support](https://developers.google.com/identity/gsi/web/guides/display-google-one-tap#do_not_cover_google_one_tap). Default: `true` - - --- - - - `signInForceRedirectUrl?` - - `string` - - Useful if you want to redirect to a path specific to Google One Tap users. If provided, this URL will **always** be redirected to after the user signs in, overriding any [`` redirect URL props](/docs/reference/components/clerk-provider#properties) or [redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). - - --- - - - `signUpForceRedirectUrl?` - - `string` - - Useful if you want to redirect to a path specific to Google One Tap users. If provided, this URL will **always** be redirected to after the user signs up, overriding any [`` redirect URL props](/docs/reference/components/clerk-provider#properties) or [redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). - - -## Usage with frameworks +> [!TIP] +> `` does not render if the user is already signed into your Clerk application, so there's no need to manually check if a user is signed in yourself before rendering it. -The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. + + ## Example -> [!NOTE] -> `` does not render if the user is already signed into your Clerk application, so there's no need to manually check if a user is signed in yourself before rendering it. + The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. - - + ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx' }} import { GoogleOneTap } from '@clerk/nextjs' @@ -64,19 +27,31 @@ The following example includes basic implementation of the `` co return } ``` - + - - ```jsx {{ filename: 'src/sign-in.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { GoogleOneTap } from '@clerk/clerk-react' - const SignInPage = () => + function App() { + return + } + + export default App + ``` + - export default SignInPage + + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} + import { GoogleOneTap } from '@clerk/react-router' + + export default function Page() { + return + } ``` - + - + ```astro {{ filename: 'pages/sign-in.astro' }} --- import { GoogleOneTap } from '@clerk/astro/components' @@ -84,9 +59,9 @@ The following example includes basic implementation of the `` co ``` - + - + ```jsx {{ filename: '/app/sign-in-google.web.tsx' }} @@ -96,19 +71,19 @@ The following example includes basic implementation of the `` co return } ``` - + - - ```jsx {{ filename: 'app/routes/sign-in/$.tsx' }} + + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} import { GoogleOneTap } from '@clerk/remix' export default function Page() { return } ``` - + - + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} import { GoogleOneTap } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -121,9 +96,9 @@ The following example includes basic implementation of the `` co return } ``` - + - + ```vue {{ filename: 'sign-in.vue' }} -The methods in this section are available on instances of the [`Clerk`](/docs/reference/javascript/clerk) class and are used to render and control the `` component. + + ``` + + -> [!NOTE] -> The examples in this section assume you have completed the [JavaScript quickstart](/docs/js-frontend/getting-started/quickstart) to set up the ClerkJS SDK in your project. + + ## Usage with JavaScript -### `openGoogleOneTap()` + The methods in this section are available on instances of the [`Clerk`](/docs/reference/javascript/clerk) class and are used to render and control the `` component. -Opens the `` component. + ### `openGoogleOneTap()` -```typescript -function openGoogleOneTap(params: GoogleOneTapProps): void -``` + Opens the `` component. -- See [`GoogleOneTapProps`](#google-one-tap-props) + ```typescript + function openGoogleOneTap(params: GoogleOneTapProps): void + ``` -#### `openGoogleOneTap()` usage + - See [`GoogleOneTapProps`](#properties) -```js {{ filename: 'main.js', mark: [[9, 14]] }} -import { Clerk } from '@clerk/clerk-js' + #### `openGoogleOneTap()` usage -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + ```js {{ filename: 'main.js', mark: [[9, 14]] }} + import { Clerk } from '@clerk/clerk-js' -const clerk = new Clerk(clerkPubKey) -await clerk.load() + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY -const params = { - cancelOnTapOutside: false, - itpSupport: false, - fedCmSupport: false, -} -clerk.openGoogleOneTap(params) -``` + const clerk = new Clerk(clerkPubKey) + await clerk.load() -### `closeGoogleOneTap()` + const params = { + cancelOnTapOutside: false, + itpSupport: false, + fedCmSupport: false, + } + clerk.openGoogleOneTap(params) + ``` -Closes the `` component. + ### `closeGoogleOneTap()` -```typescript -function closeGoogleOneTap(): void -``` + Closes the `` component. -#### `closeGoogleOneTap()` usage + ```typescript + function closeGoogleOneTap(): void + ``` -```js {{ filename: 'main.js', mark: [18] }} -import { Clerk } from '@clerk/clerk-js' + #### `closeGoogleOneTap()` usage -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + ```js {{ filename: 'main.js', mark: [18] }} + import { Clerk } from '@clerk/clerk-js' -const clerk = new Clerk(clerkPubKey) -await clerk.load() + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY -const params = { - cancelOnTapOutside: false, - itpSupport: false, - fedCmSupport: false, -} -clerk.openGoogleOneTap(params) + const clerk = new Clerk(clerkPubKey) + await clerk.load() -// Do something else + const params = { + cancelOnTapOutside: false, + itpSupport: false, + fedCmSupport: false, + } + clerk.openGoogleOneTap(params) -clerk.closeGoogleOneTap() -``` + // Do something else -### `authenticateWithGoogleOneTap()` + clerk.closeGoogleOneTap() + ``` -Authenticates the user with a token generated from Google identity services. Also sets the user's current session to active. + ### `authenticateWithGoogleOneTap()` -```typescript -function authenticateWithGoogleOneTap( - props?: AuthenticateWithGoogleOneTapParams, -): Promise -``` + Authenticates the user with a token generated from Google identity services. Also sets the user's current session to active. -#### `AuthenticateWithGoogleOneTapParams` + ```typescript + function authenticateWithGoogleOneTap( + props?: AuthenticateWithGoogleOneTapParams, + ): Promise + ``` - - - `token?` - - `string` + #### `AuthenticateWithGoogleOneTapParams` - A Google authentication token from Google identity services. - + + - `token?` + - `string` -#### `authenticateWithGoogleOneTap()` usage + A Google authentication token from Google identity services. + -```js {{ filename: 'main.js', mark: [[9, 17]] }} -import { Clerk } from '@clerk/clerk-js' + #### `authenticateWithGoogleOneTap()` usage -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + ```js {{ filename: 'main.js', mark: [[9, 17]] }} + import { Clerk } from '@clerk/clerk-js' -const clerk = new Clerk(clerkPubKey) -await clerk.load() + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY -// Optionally, you can set redirect URLs. -const customUrls = { - signInUrl: '/sign-in', - signUpUrl: '/sign-up', -} -// Initiate the authentication flow. -const signInOrUp = await clerk.authenticateWithGoogleOneTap({ token: 'xxxx' }) -// Set the session as active, and handle any navigation or redirects -await clerk.handleGoogleOneTapCallback(signInOrUp, customUrls) -``` + const clerk = new Clerk(clerkPubKey) + await clerk.load() -### `handleGoogleOneTapCallback()` + // Optionally, you can set redirect URLs. + const customUrls = { + signInUrl: '/sign-in', + signUpUrl: '/sign-up', + } + // Initiate the authentication flow. + const signInOrUp = await clerk.authenticateWithGoogleOneTap({ token: 'xxxx' }) + // Set the session as active, and handle any navigation or redirects + await clerk.handleGoogleOneTapCallback(signInOrUp, customUrls) + ``` -Completes a Google One Tap redirection flow started by [`authenticateWithGoogleOneTap()`](#authenticate-with-google-one-tap). Also calls [`Clerk.setActive()`](/docs/reference/javascript/clerk#set-active) and performs a custom navigation if given a custom navigation function. + ### `handleGoogleOneTapCallback()` -```typescript -function handleGoogleOneTapCallback( - signInOrUp: SignInResource | SignUpResource, - params: HandleOAuthCallbackParams, - customNavigate?: (to: string) => Promise, -): Promise -``` + Completes a Google One Tap redirection flow started by [`authenticateWithGoogleOneTap()`](#authenticate-with-google-one-tap). Also calls [`Clerk.setActive()`](/docs/reference/javascript/clerk#set-active) and performs a custom navigation if given a custom navigation function. + + ```typescript + function handleGoogleOneTapCallback( + signInOrUp: SignInResource | SignUpResource, + params: HandleOAuthCallbackParams, + customNavigate?: (to: string) => Promise, + ): Promise + ``` + + See [`authenticateWithGoogleOneTap()` usage](#authenticate-with-google-one-tap-usage) for an example of how to use `handleGoogleOneTapCallback()`. + + #### `handleGoogleOneTapCallback()` params + + + - `signInOrUp` + - [SignInResource](/docs/reference/javascript/sign-in) | [SignUpResource](/docs/reference/javascript/sign-up) + + The `SignIn` or `SignUp` object returned from `authenticateWithGoogleOneTap()`. + + --- + + - `params` + - [`HandleOAuthCallbackParams`](/docs/reference/javascript/clerk#handle-o-auth-callback-params) + + An object containing redirect URLs. Useful if you want to set URLs specific to Google One Tap. Otherwise, consider using [environment variables](/docs/guides/development/clerk-environment-variables) to set redirect URLs. + + --- -See [`authenticateWithGoogleOneTap()` usage](#authenticate-with-google-one-tap-usage) for an example of how to use `handleGoogleOneTapCallback()`. + - `customNavigate?` + - `(to: string) => Promise` -#### `handleGoogleOneTapCallback()` params + A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. + + + +## Properties - - `signInOrUp` - - [SignInResource](/docs/reference/javascript/sign-in) | [SignUpResource](/docs/reference/javascript/sign-up) + - `cancelOnTapOutside?` + - `boolean` - The `SignIn` or `SignUp` object returned from `authenticateWithGoogleOneTap()`. + If `true`, the One Tap prompt closes automatically if the user clicks outside of the prompt. Defaults to `true`. --- - - `params` - - [`HandleOAuthCallbackParams`](/docs/reference/javascript/clerk#handle-o-auth-callback-params) + - `itpSupport?` + - `boolean` - An object containing redirect URLs. Useful if you want to set URLs specific to Google One Tap. Otherwise, consider using [environment variables](/docs/guides/development/clerk-environment-variables) to set redirect URLs. + If `true`, enables the [ITP-specific UX](https://developers.google.com/identity/gsi/web/guides/itp) when One Tap is rendered on ITP browsers such as Chrome on iOS, Safari, and FireFox. Defaults to `true`. --- - - `customNavigate?` - - `(to: string) => Promise` + - `fedCmSupport?` + - `boolean` + + If `true`, enables Google One Tap to use [the FedCM API](https://developers.google.com/privacy-sandbox/3pcd/fedcm) to sign users in. See Google's docs on [best practices when disabling FedCM support](https://developers.google.com/identity/gsi/web/guides/display-google-one-tap#do_not_cover_google_one_tap). Defaults to `true` - A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. + --- + + - `signInForceRedirectUrl?` + - `string` + + Useful if you want to redirect to a path specific to Google One Tap users. If provided, this URL will **always** be redirected to after the user signs in, overriding any [`` redirect URL props](/docs/reference/components/clerk-provider#properties) or [redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). + + --- + + - `signUpForceRedirectUrl?` + - `string` + + Useful if you want to redirect to a path specific to Google One Tap users. If provided, this URL will **always** be redirected to after the user signs up, overriding any [`` redirect URL props](/docs/reference/components/clerk-provider#properties) or [redirect URL environment variables](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects). ## Limitations diff --git a/docs/reference/components/authentication/sign-in.mdx b/docs/reference/components/authentication/sign-in.mdx index 6e3b19bfca..8b0ff39d53 100644 --- a/docs/reference/components/authentication/sign-in.mdx +++ b/docs/reference/components/authentication/sign-in.mdx @@ -11,122 +11,14 @@ The `` component renders a UI to allow users to sign in or sign up by > [!NOTE] > The `` and `` components cannot render when a user is already signed in, unless the application allows multiple sessions. If a user is already signed in and the application only allows a single session, Clerk will redirect the user to the Home URL instead. -## Properties - -All props are optional. - - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `fallback` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - --- - - - `fallbackRedirectUrl` - - `string` - - The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `forceRedirectUrl` - - `string` - - If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `initialValues` - - [`SignInInitialValues`](/docs/reference/javascript/types/sign-in-initial-values) - - The values used to prefill the sign-in fields with. - - --- - - - `oauthFlow` - - `"redirect" | "popup" | "auto"` - - Determines how OAuth authentication is performed. Accepts the following properties: - - - `"redirect"`: Redirect to the OAuth provider on the current page. - - `"popup"`: Open a popup window. - - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication. - - Defaults to `"auto"`. - - --- - - - `path` - - `string` - - The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/sign-in`. - - --- + + ## Example - - `routing` - - `'hash' | 'path'` - - The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. - - --- - - - `signUpFallbackRedirectUrl` - - `string` - - The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Used for the 'Don't have an account? Sign up' link that's rendered. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signUpForceRedirectUrl` - - `string` - - If provided, this URL will always used as the redirect destination after the user signs up. Used for the 'Don't have an account? Sign up' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signUpUrl` - - `string` - - The full URL or path to the sign-up page. Used for the 'Don't have an account? Sign up' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `transferable` - - `boolean` - - Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to `true`. When set to `false`, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. - - --- - - - `waitlistUrl` - - `string` - - Full URL or path to the waitlist page. Use this property to provide the target of the 'Waitlist' link that's rendered. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/guides/customizing-clerk/account-portal#waitlist). If you've passed the `waitlistUrl` prop to the [``](/docs/reference/components/clerk-provider) component, it will infer from that, and you can omit this prop. - - --- - - - `withSignUp` - - `boolean` - - Opt into sign-in-or-up flow by setting this prop to `true`. When `true`, if a user does not exist, they will be prompted to sign up. If a user exists, they will be prompted to sign in. Defaults to `true` if the `CLERK_SIGN_IN_URL` environment variable is set. Otherwise, defaults to `false`. - - -## Usage with frameworks - -The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. - - - - The following example demonstrates how you can use the `` component on a public page. + The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. + If you would like to create a dedicated `/sign-in` page in your Next.js application, there are a few requirements you must follow. See the [dedicated guide](/docs/nextjs/guides/development/custom-sign-in-or-up-page) for more information. ```tsx {{ filename: 'app/page.tsx' }} @@ -144,9 +36,9 @@ The following example includes basic implementation of the `` componen return
Welcome!
} ``` - + - + ```astro {{ filename: 'pages/signin.astro' }} --- import { SignIn } from '@clerk/astro/components' @@ -154,9 +46,9 @@ The following example includes basic implementation of the `` componen ``` - + - + If you would like to create a dedicated `/sign-in` page in your Expo application, there are a few requirements you must follow. See the [dedicated guide](/docs/guides/development/web-support/custom-sign-in-or-up-page) for more information. @@ -168,19 +60,21 @@ The following example includes basic implementation of the `` componen return } ``` - + - - ```jsx {{ filename: 'src/sign-in.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { SignIn } from '@clerk/clerk-react' - const SignInPage = () => + function App() { + return + } - export default SignInPage + export default App ``` - + - + If you would like to create a dedicated `/sign-in` page in your React Router application, there are a few requirements you must follow. See the [dedicated guide](/docs/react-router/guides/development/custom-sign-in-or-up-page) for more information. ```tsx {{ filename: 'app/routes/sign-in.tsx' }} @@ -190,24 +84,34 @@ The following example includes basic implementation of the `` componen return } ``` - + - + + ```jsx {{ filename: 'src/routes/sign-in.tsx' }} + import { SignIn } from '@clerk/chrome-extension' + + export default function SignInPage() { + return + } + ``` + + + If you would like to create a dedicated `/sign-in` page in your Remix application, there are a few requirements you must follow. See the [dedicated guide](/docs/remix/guides/development/custom-sign-in-or-up-page) for more information. - ```tsx {{ filename: 'app/routes/sign-in/$.tsx' }} + ```tsx {{ filename: 'app/routes/sign-in.$.tsx' }} import { SignIn } from '@clerk/remix' export default function SignInPage() { return } ``` - + - + If you would like to create a dedicated `/sign-in` page in your TanStack React Start application, there are a few requirements you must follow. See the [dedicated guide](/docs/tanstack-react-start/guides/development/custom-sign-in-or-up-page) for more information. - ```tsx {{ filename: 'app/routes/sign-in.tsx' }} + ```tsx {{ filename: 'app/routes/sign-in.$.tsx' }} import { SignIn } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -219,9 +123,9 @@ The following example includes basic implementation of the `` componen return } ``` - + - + ```vue {{ filename: 'sign-in.vue' }} + + + ``` + + ## Usage with JavaScript @@ -389,6 +305,114 @@ The following example includes basic implementation of the `` componen ``` +## Properties + +All props are optional. + + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `fallback` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + --- + + - `fallbackRedirectUrl` + - `string` + + The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `forceRedirectUrl` + - `string` + + If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `initialValues` + - [`SignInInitialValues`](/docs/reference/javascript/types/sign-in-initial-values) + + The values used to prefill the sign-in fields with. + + --- + + - `oauthFlow` + - `"redirect" | "popup" | "auto"` + + Determines how OAuth authentication is performed. Accepts the following properties: + + - `"redirect"`: Redirect to the OAuth provider on the current page. + - `"popup"`: Open a popup window. + - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication. + + Defaults to `"auto"`. + + --- + + - `path` + - `string` + + The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/sign-in`. + + --- + + - `routing` + - `'hash' | 'path'` + + The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. + + --- + + - `signUpFallbackRedirectUrl` + - `string` + + The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Used for the 'Don't have an account? Sign up' link that's rendered. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpForceRedirectUrl` + - `string` + + If provided, this URL will always used as the redirect destination after the user signs up. Used for the 'Don't have an account? Sign up' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signUpUrl` + - `string` + + The full URL or path to the sign-up page. Used for the 'Don't have an account? Sign up' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `transferable` + - `boolean` + + Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to `true`. When set to `false`, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. + + --- + + - `waitlistUrl` + - `string` + + Full URL or path to the waitlist page. Use this property to provide the target of the 'Waitlist' link that's rendered. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/guides/customizing-clerk/account-portal#waitlist). If you've passed the `waitlistUrl` prop to the [``](/docs/reference/components/clerk-provider) component, it will infer from that, and you can omit this prop. + + --- + + - `withSignUp` + - `boolean` + + Opt into sign-in-or-up flow by setting this prop to `true`. When `true`, if a user does not exist, they will be prompted to sign up. If a user exists, they will be prompted to sign in. Defaults to `true` if the `CLERK_SIGN_IN_URL` environment variable is set. Otherwise, defaults to `false`. + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/authentication/sign-up.mdx b/docs/reference/components/authentication/sign-up.mdx index d605228471..e641cb48e8 100644 --- a/docs/reference/components/authentication/sign-up.mdx +++ b/docs/reference/components/authentication/sign-up.mdx @@ -11,108 +11,14 @@ The `` component renders a UI for signing up users. The functionality > [!NOTE] > The `` and `` components cannot render when a user is already signed in, unless the application allows multiple sessions. If a user is already signed in and the application only allows a single session, Clerk will redirect the user to the Home URL instead. -## Properties - -All props are optional. - - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `fallback` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - --- - - - `fallbackRedirectUrl` - - `string` - - The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `forceRedirectUrl` - - `string` - - If provided, this URL will always be used as the redirect destination after the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `initialValues` - - [`SignUpInitialValues`](/docs/reference/javascript/types/sign-up-initial-values) - - The values used to prefill the sign-up fields with. - - --- - - - `oauthFlow` - - `"redirect" | "popup" | "auto"` - - Determines how OAuth authentication is performed. Accepts the following properties: - - - `"redirect"`: Redirect to the OAuth provider on the current page. - - `"popup"`: Open a popup window. - - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication. - - Defaults to `"auto"`. - - --- + + ## Example - - `path` - - `string` - - The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/sign-up`. - - --- - - - `routing` - - `'hash' | 'path'` - - The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. - - --- - - - `signInFallbackRedirectUrl` - - `string` - - The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Used for the 'Already have an account? Sign in' link that's rendered. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signInForceRedirectUrl?` - - `string` - - If provided, this URL will always be redirected to after the user signs in. Used for the 'Already have an account? Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signInUrl` - - `string` - - The full URL or path to the sign-in page. Used for the 'Already have an account? Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `unsafeMetadata` - - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) - - Metadata that can be read and set from the frontend and the backend. Once the sign-up is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the sign-up process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). - - -## Usage with frameworks - -The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. - - - - The following example demonstrates how you can use the `` component on a public page. + The following example includes basic implementation of the `` component. You can use this as a starting point for your own implementation. + If you would like to create a dedicated `/sign-up` page in your Next.js application, there are a few requirements you must follow. See the [dedicated guide](/docs/nextjs/guides/development/custom-sign-up-page) for more information. ```tsx {{ filename: 'app/page.tsx' }} @@ -130,9 +36,9 @@ The following example includes basic implementation of the `` componen return
Welcome!
} ``` - + - + ```astro {{ filename: 'pages/signup.astro' }} --- import { SignUp } from '@clerk/astro/components' @@ -140,9 +46,9 @@ The following example includes basic implementation of the `` componen ``` - + - + ```jsx {{ filename: '/app/sign-up.web.tsx' }} @@ -152,19 +58,21 @@ The following example includes basic implementation of the `` componen return } ``` - + - - ```jsx {{ filename: 'src/sign-up.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { SignUp } from '@clerk/clerk-react' - const SignUpPage = () => + function App() { + return + } - export default SignUpPage + export default App ``` - + - + If you would like to create a dedicated `/sign-up` page in your React Router application, there are a few requirements you must follow. See the [dedicated guide](/docs/react-router/guides/development/custom-sign-up-page) for more information. ```tsx {{ filename: 'app/routes/sign-up.tsx' }} @@ -174,24 +82,34 @@ The following example includes basic implementation of the `` componen return } ``` - + + + + ```jsx {{ filename: 'src/routes/sign-up.tsx' }} + import { SignUp } from '@clerk/chrome-extension' - + export default function SignUpPage() { + return + } + ``` + + + If you would like to create a dedicated `/sign-up` page in your Remix application, there are a few requirements you must follow. See the [dedicated guide](/docs/remix/guides/development/custom-sign-up-page) for more information. - ```jsx {{ filename: 'app/routes/sign-up/$.tsx' }} + ```tsx {{ filename: 'app/routes/sign-up.$.tsx' }} import { SignUp } from '@clerk/remix' export default function SignUpPage() { return } ``` - + - + If you would like to create a dedicated `/sign-up` page in your Tanstack React Start application, there are a few requirements you must follow. See the [dedicated guide](/docs/tanstack-react-start/guides/development/custom-sign-up-page) for more information. - ```tsx {{ filename: 'app/routes/sign-up.tsx' }} + ```tsx {{ filename: 'app/routes/sign-up.$.tsx' }} import { SignUp } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -203,9 +121,9 @@ The following example includes basic implementation of the `` componen return } ``` - + - + ```vue {{ filename: 'sign-up.vue' }} + + + ``` + + ## Usage with JavaScript @@ -373,6 +303,100 @@ The following example includes basic implementation of the `` componen ``` +## Properties + +All props are optional. + + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `fallback` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + --- + + - `fallbackRedirectUrl` + - `string` + + The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `forceRedirectUrl` + - `string` + + If provided, this URL will always be used as the redirect destination after the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `initialValues` + - [`SignUpInitialValues`](/docs/reference/javascript/types/sign-up-initial-values) + + The values used to prefill the sign-up fields with. + + --- + + - `oauthFlow` + - `"redirect" | "popup" | "auto"` + + Determines how OAuth authentication is performed. Accepts the following properties: + + - `"redirect"`: Redirect to the OAuth provider on the current page. + - `"popup"`: Open a popup window. + - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication. + + Defaults to `"auto"`. + + --- + + - `path` + - `string` + + The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/sign-up`. + + --- + + - `routing` + - `'hash' | 'path'` + + The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. + + --- + + - `signInFallbackRedirectUrl` + - `string` + + The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Used for the 'Already have an account? Sign in' link that's rendered. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signInForceRedirectUrl?` + - `string` + + If provided, this URL will always be redirected to after the user signs in. Used for the 'Already have an account? Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `signInUrl` + - `string` + + The full URL or path to the sign-in page. Used for the 'Already have an account? Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + --- + + - `unsafeMetadata` + - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) + + Metadata that can be read and set from the frontend and the backend. Once the sign-up is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the sign-up process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/authentication/task-choose-organization.mdx b/docs/reference/components/authentication/task-choose-organization.mdx index 715f12e756..e54f5fa546 100644 --- a/docs/reference/components/authentication/task-choose-organization.mdx +++ b/docs/reference/components/authentication/task-choose-organization.mdx @@ -11,30 +11,12 @@ The `` component renders a UI for resolving the `choos > [!IMPORTANT] > The `` component cannot render when a user doesn't have current session tasks. -## Properties - -All props are optional. - - - - `redirectUrlComplete` - - `string` - - The full URL or path to navigate to after successfully completing all tasks. - - --- - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + ## Example - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - + The following example demonstrates how to host the `` component on a custom page. -## Usage with frameworks - -The following example demonstrates how to host the `` component on a custom page. - - - + ```tsx {{ filename: 'app/layout.tsx', mark: [7] }} import { ClerkProvider } from '@clerk/nextjs' @@ -60,9 +42,9 @@ The following example demonstrates how to host the `` return } ``` - + - + ```tsx {{ filename: 'index.tsx', mark: [17] }} import React from 'react' import ReactDOM from 'react-dom/client' @@ -95,8 +77,133 @@ The following example demonstrates how to host the `` export default ChooseOrganizationPage ``` - - + + + + > [!NOTE] + > To see the full `root.tsx` setup you need for Clerk with React Router, see the [React Router quickstart](/docs/react-router/getting-started/quickstart). + + ```tsx {{ filename: 'app/root.tsx', mark: [6] }} + import { ClerkProvider } from '@clerk/react-router' + import { Outlet } from 'react-router' + + export default function App() { + return ( + + + + ) + } + ``` + + The `` component must be used in conjunction with the `` component. See the [dedicated guide on how to self-host the `` component](/docs/react-router/guides/development/custom-sign-in-or-up-page). + + ```tsx {{ filename: 'app/routes/onboarding/choose-organization.tsx' }} + import { TaskChooseOrganization } from '@clerk/react-router' + + export default function ChooseOrganizationPage() { + return + } + ``` + + + + ```tsx {{ filename: 'app/root.tsx', fold: [[1, 37]], mark: [39] }} + import type { MetaFunction, LoaderFunction } from '@remix-run/node' + + import { Links, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react' + + import { rootAuthLoader } from '@clerk/remix/ssr.server' + import { ClerkApp } from '@clerk/remix' + + export const meta: MetaFunction = () => [ + { + charset: 'utf-8', + title: 'New Remix App', + viewport: 'width=device-width,initial-scale=1', + }, + ] + + export const loader: LoaderFunction = (args) => rootAuthLoader(args) + + export function Layout({ children }: { children: React.ReactNode }) { + return ( + + + + + + + {children} + + + + + ) + } + + function App() { + return + } + + export default ClerkApp(App, { + taskUrls: { 'choose-organization': '/onboarding/choose-organization' }, + }) + ``` + + The `` component must be used in conjunction with the `` component. See the [dedicated guide on how to self-host the `` component](/docs/remix/guides/development/custom-sign-in-or-up-page). + + ```tsx {{ filename: 'app/routes/onboarding.choose-organization.tsx' }} + import { TaskChooseOrganization } from '@clerk/remix' + + export default function ChooseOrganizationPage() { + return + } + ``` + + + + > [!NOTE] + > To see the full `__root.tsx` setup you need for Clerk with TanStack React Start, see the [TanStack React Start quickstart](/docs/tanstack-react-start/getting-started/quickstart). + + ```tsx {{ filename: 'src/routes/__root.tsx', mark: [7] }} + import * as React from 'react' + import { HeadContent, Scripts } from '@tanstack/react-router' + import { ClerkProvider } from '@clerk/tanstack-react-start' + + function RootDocument({ children }: { children: React.ReactNode }) { + return ( + + + + + + + {children} + + + + + ) + } + ``` + + The `` component must be used in conjunction with the `` component. See the [dedicated guide on how to self-host the `` component](/docs/tanstack-react-start/guides/development/custom-sign-in-or-up-page). + + ```tsx {{ filename: 'src/routes/onboarding/choose-organization.tsx' }} + import { TaskChooseOrganization } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/onboarding/choose-organization')({ + component: ChooseOrganizationPage, + }) + + function ChooseOrganizationPage() { + return + } + ``` + + ## Usage with JavaScript @@ -185,8 +292,64 @@ The following example demonstrates how to host the `` The container `
` element with a rendered `` component instance + + #### `unmountTaskChooseOrganization()` usage + + ```typescript {{ filename: 'main.ts', mark: [30] }} + import { Clerk } from '@clerk/clerk-js' + + const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(pubKey) + await clerk.load() + + if (clerk.isSignedIn) { + // Mount user button component + document.getElementById('signed-in').innerHTML = ` +
+ ` + + const userbuttonDiv = document.getElementById('user-button') + + clerk.mountUserButton(userbuttonDiv) + } else if (clerk.session?.currentTask) { + switch (clerk.session.currentTask.key) { + case 'choose-organization': { + document.getElementById('app').innerHTML = ` +
+ ` + + const taskChooseOrganizationDiv = document.getElementById('task-choose-organization') + + clerk.mountTaskChooseOrganization(taskChooseOrganizationDiv) + + // ... + + clerk.unmountTaskChooseOrganization(taskChooseOrganizationDiv) + } + } + } + ``` +## Properties + +All props are optional. + + + - `redirectUrlComplete` + - `string` + + The full URL or path to navigate to after successfully completing all tasks. + + --- + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/authentication/waitlist.mdx b/docs/reference/components/authentication/waitlist.mdx index 75719b4236..9868e2172a 100644 --- a/docs/reference/components/authentication/waitlist.mdx +++ b/docs/reference/components/authentication/waitlist.mdx @@ -10,8 +10,10 @@ In **Waitlist** mode, users can register their interest in your app by joining a The `` component renders a form that allows users to join for early access to your app. -> [!NOTE] -> If you're using Next.js, the`` component is available in `@clerk/nextjs@6.2.0` and above. + + > [!NOTE] + > If you're using Next.js, the`` component is available in `@clerk/nextjs@6.2.0` and above. + ## Enable Waitlist mode @@ -20,47 +22,17 @@ Before using the `` component, you must enable **Waitlist** mode in 1. In the Clerk Dashboard, navigate to the [**Restrictions**](https://dashboard.clerk.com/last-active?path=user-authentication/restrictions) page. 1. Under the **Sign-up modes** section, enable **Waitlist**. -## Properties - -All props are optional. - - - - `afterJoinWaitlistUrl` - - `string` - - The full URL or path to navigate to after joining the waitlist. - - --- - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + ## Example - --- - - - `fallback?` - - `ReactNode` + > [!WARNING] + > Before using the `` component, you must provide the `waitlistUrl` prop either in the [``](/docs/reference/components/clerk-provider#properties) or [``](/docs/reference/components/authentication/sign-in#properties) component to ensure proper functionality. - An optional element to be rendered while the component is mounting. - - --- - - - `signInUrl` - - `string` + The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - The full URL or path to the sign in page. Used for the 'Already have an account? Sign in' link that's rendered. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - -## Usage with frameworks - -> [!WARNING] -> Before using the `` component, you must provide the `waitlistUrl` prop either in the [``](/docs/reference/components/clerk-provider#properties) or [``](/docs/reference/components/authentication/sign-in#properties) component to ensure proper functionality. - -The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - - - + ```tsx {{ filename: 'app/waitlist/[[...waitlist]]/page.tsx' }} import { Waitlist } from '@clerk/nextjs' @@ -68,19 +40,21 @@ The following example includes a basic implementation of the `` comp return } ``` - + - - ```tsx {{ filename: 'src/waitlist.tsx' }} + + ```tsx {{ filename: 'src/App.tsx' }} import { Waitlist } from '@clerk/clerk-react' - export default function WaitlistPage() { + function App() { return } + + export default App ``` - + - + ```astro {{ filename: 'pages/waitlist.astro' }} --- import { Waitlist as WaitlistAstro } from '@clerk/astro/components' @@ -88,9 +62,9 @@ The following example includes a basic implementation of the `` comp ``` - + - + ```jsx {{ filename: '/app/waitlist.web.tsx' }} @@ -100,9 +74,39 @@ The following example includes a basic implementation of the `` comp return } ``` - + + + + ```jsx {{ filename: 'src/routes/waitlist.tsx' }} + import { Waitlist } from '@clerk/chrome-extension' - + export default function WaitlistPage() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/waitlist.tsx' }} + import { Waitlist } from '@clerk/react-router' + + export default function WaitlistPage() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/waitlist.tsx' }} + import { Waitlist } from '@clerk/remix' + + export default function WaitlistPage() { + return + } + ``` + + + ```tsx {{ filename: 'app/routes/waitlist.tsx' }} import { Waitlist } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -115,9 +119,21 @@ The following example includes a basic implementation of the `` comp return } ``` - + - + + ```vue {{ filename: 'pages/waitlist.vue' }} + + + + ``` + + + ```vue {{ filename: 'waitlist.vue' }} - - - ``` - - + ) + } + + export default PricingSection + ``` + + + + ```vue {{ filename: 'pricing.vue' }} + + + + ``` + + +## Properties + + + - `planId` + - `string` + + The ID of the plan to subscribe to. + + --- + + - `planPeriod?` + - `'month' | 'annual'` + + The billing period for the subscription. + + --- + + - `for?` + - `'user' | 'organization'` + + Determines whether the subscription is for the current user or organization. Defaults to `'user'`. + + --- + + - `children?` + - `React.ReactNode` + + A custom button element. If not provided, defaults to a button with the text "Checkout". + + --- + + - `onSubscriptionComplete?` + - `() => void` + + A callback function that is called when a subscription is successfully completed. + + --- + + - `newSubscriptionRedirectUrl?` + - `string` + + The URL to redirect to after a successful subscription. + + --- + + - `checkoutProps?` + - `{ appearance: Appearance }` + + Options for the checkout drawer. Accepts the following properties: + + - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. For example: ``. + diff --git a/docs/reference/components/billing/plan-details-button.mdx b/docs/reference/components/billing/plan-details-button.mdx index e63f2f4003..57f2bd5acb 100644 --- a/docs/reference/components/billing/plan-details-button.mdx +++ b/docs/reference/components/billing/plan-details-button.mdx @@ -10,45 +10,6 @@ The `` component renders a button that opens the plan detai -## Properties - - - - `planId?` - - `string` - - The ID of the plan to display details for. It is required if `plan` is not provided. - - --- - - - `plan?` - - [CommercePlanResource](/docs/reference/javascript/types/commerce-plan-resource) - - The plan to display details for. It is used as initial data until the plan is fetched from the server. - - --- - - - `children?` - - `React.ReactNode` - - Optional custom button element. If not provided, defaults to a button with the text "Plan details". - - --- - - - `initialPlanPeriod?` - - `'month' | 'annual'` - - Optional prop to set the initial billing period view when the plan details drawer opens. - - --- - - - `planDetailsProps?` - - `{ appearance: Appearance }` - - Options for the plan details drawer. Accepts the following properties: - - - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. For example: ``. - - ## Usage `` preserves any click handlers attached to custom button elements, while maintaining the plan details drawer functionality. @@ -77,107 +38,144 @@ const portalRoot = document.getElementById('custom-portal') ### Examples - - - ```tsx {{ filename: 'app/pricing/page.tsx' }} - 'use client' - - import { PlanDetailsButton } from '@clerk/nextjs/experimental' - - export default function PricingPage() { - return ( -
- {/* Basic usage with plan ID */} - - - {/* Customizes the appearance of the plan details drawer */} - - - {/* Custom button */} - - - -
- ) - } - ``` - - - - ```tsx {{ filename: 'src/components/PricingSection.tsx' }} - import { PlanDetailsButton } from '@clerk/clerk-react' - - const PricingSection = () => { - return ( -
- {/* Basic usage with plan ID */} - - - {/* Customizes the appearance of the plan details drawer */} - - - {/* Custom button */} - - - -
- ) - } - - export default PricingSection - ``` - - - - ```vue {{ filename: 'pricing.vue' }} - - - - ``` - - + ) + } + + export default PricingSection + ``` + + + + ```vue {{ filename: 'pricing.vue' }} + + + + ``` + + +## Properties + + + - `planId?` + - `string` + + The ID of the plan to display details for. It is required if `plan` is not provided. + + --- + + - `plan?` + - [CommercePlanResource](/docs/reference/javascript/types/commerce-plan-resource) + + The plan to display details for. It is used as initial data until the plan is fetched from the server. + + --- + + - `children?` + - `React.ReactNode` + + Optional custom button element. If not provided, defaults to a button with the text "Plan details". + + --- + + - `initialPlanPeriod?` + - `'month' | 'annual'` + + Optional prop to set the initial billing period view when the plan details drawer opens. + + --- + + - `planDetailsProps?` + - `{ appearance: Appearance }` + + Options for the plan details drawer. Accepts the following properties: + + - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. For example: ``. + diff --git a/docs/reference/components/billing/pricing-table.mdx b/docs/reference/components/billing/pricing-table.mdx index a9210a14e2..4f6a01cacc 100644 --- a/docs/reference/components/billing/pricing-table.mdx +++ b/docs/reference/components/billing/pricing-table.mdx @@ -8,67 +8,14 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component displays a table of Plans and Features that users can subscribe to. -## Properties - -All props are optional. - - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `checkoutProps` - - `{ appearance: Appearance }` - - Options for the checkout drawer. Accepts the following properties: - - - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- + + ## Example - - `collapseFeatures` - - `boolean` - - A boolean that indicates whether the features are collapsed. **Requires `layout` to be set to `'default'`**. Defaults to `false`. - - --- + The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - - `ctaPosition` - - `'top' | 'bottom'` - - The placement of the CTA button. **Requires `layout` to be set to `'default'`**. Defaults to `'bottom'`. - - --- - - - `fallback` - - `JSX` - - An optional UI to show when the pricing table is loading. - - --- - - - `forOrganizations` - - `boolean` - - A boolean that indicates whether the pricing table is for [organizations](/docs/guides/organizations/overview). If `false`, the pricing table will display a list of plans and features that **users** can subscribe to. If `true`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `false`. - - --- - - - `newSubscriptionRedirectUrl` - - `string` - - The URL to navigate to after the user completes the checkout and selects the "Continue" button. - - -## Usage with frameworks - -The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - - - + ```tsx {{ filename: 'app/pricing/page.tsx' }} import { PricingTable } from '@clerk/nextjs' @@ -76,19 +23,21 @@ The following example includes a basic implementation of the `` return } ``` - + - - ```tsx {{ filename: 'src/pricing.tsx' }} + + ```tsx {{ filename: 'src/App.tsx' }} import { PricingTable } from '@clerk/clerk-react' - export default function PricingPage() { + function App() { return } + + export default App ``` - + - + ```astro {{ filename: 'pages/pricing.astro' }} --- import { PricingTable } from '@clerk/astro/components' @@ -96,9 +45,9 @@ The following example includes a basic implementation of the `` ``` - + - + ```jsx {{ filename: '/app/pricing.web.tsx' }} @@ -108,9 +57,19 @@ The following example includes a basic implementation of the `` return } ``` - + + + + ```jsx {{ filename: 'src/routes/pricing.tsx' }} + import { PricingTable } from '@clerk/chrome-extension' + + export default function PricingPage() { + return + } + ``` + - + ```tsx {{ filename: 'app/routes/pricing.tsx' }} import { PricingTable } from '@clerk/react-router' @@ -118,9 +77,19 @@ The following example includes a basic implementation of the `` return } ``` - + + + + ```tsx {{ filename: 'app/routes/pricing.tsx' }} + import { PricingTable } from '@clerk/remix' + + export default function PricingPage() { + return + } + ``` + - + ```tsx {{ filename: 'app/routes/pricing.tsx' }} import { PricingTable } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -133,9 +102,9 @@ The following example includes a basic implementation of the `` return } ``` - + - + ```vue {{ filename: 'pricing.vue' }} + + + ``` + + ## Usage with JavaScript @@ -239,3 +220,58 @@ The following example includes a basic implementation of the `` clerk.unmountPricingTable(pricingTableDiv) ``` + +## Properties + +All props are optional. + + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `checkoutProps` + - `{ appearance: Appearance }` + + Options for the checkout drawer. Accepts the following properties: + + - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `collapseFeatures` + - `boolean` + + A boolean that indicates whether the features are collapsed. **Requires `layout` to be set to `'default'`**. Defaults to `false`. + + --- + + - `ctaPosition` + - `'top' | 'bottom'` + + The placement of the CTA button. **Requires `layout` to be set to `'default'`**. Defaults to `'bottom'`. + + --- + + - `fallback` + - `JSX` + + An optional UI to show when the pricing table is loading. + + --- + + - `forOrganizations` + - `boolean` + + A boolean that indicates whether the pricing table is for [organizations](/docs/guides/organizations/overview). If `false`, the pricing table will display a list of plans and features that **users** can subscribe to. If `true`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `false`. + + --- + + - `newSubscriptionRedirectUrl` + - `string` + + The URL to navigate to after the user completes the checkout and selects the "Continue" button. + diff --git a/docs/reference/components/billing/subscription-details-button.mdx b/docs/reference/components/billing/subscription-details-button.mdx index aba534d579..31e403dc90 100644 --- a/docs/reference/components/billing/subscription-details-button.mdx +++ b/docs/reference/components/billing/subscription-details-button.mdx @@ -10,40 +10,6 @@ The `` component renders a button that opens the su -## Properties - -All props are optional. - - - - `for?` - - `'user' | 'organization'` - - Determines whether to show subscription details for the current user or organization. Defaults to `'user'`. - - --- - - - `children?` - - `React.ReactNode` - - Optional custom button element. If not provided, defaults to a button with the text "Subscription details". - - --- - - - `onSubscriptionCancel?` - - `() => void` - - A callback function that is called when a subscription is cancelled. - - --- - - - `subscriptionDetailsProps?` - - `{ appearance: Appearance }` - - Options for the subscription details drawer. Accepts the following properties: - - - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. For example: ``. - - ## Usage `` must be wrapped inside a [``](/docs/reference/components/control/signed-in) component to ensure the user is authenticated. @@ -72,104 +38,136 @@ All props are optional. ### Examples - - - ```tsx {{ filename: 'app/billing/page.tsx' }} - 'use client' - - import { SignedIn } from '@clerk/nextjs' - import { SubscriptionDetailsButton } from '@clerk/nextjs/experimental' - - export default function BillingPage() { - return ( - - {/* Basic usage */} - - - {/* Customizes the appearance of the subscription details drawer */} - - - {/* Custom button */} - console.log('Subscription canceled')}> - - - - ) - } - ``` - - - - ```tsx {{ filename: 'src/components/BillingSection.tsx' }} - import { SignedIn } from '@clerk/clerk-react' - import { SubscriptionDetailsButton } from '@clerk/clerk-react/experimental' - - const BillingSection = () => { - return ( - - {/* Basic usage */} - - - {/* Customizes the appearance of the subscription details drawer */} - - - {/* Custom button */} - console.log('Subscription canceled')}> - - - - ) - } - - export default BillingSection - ``` - - - - ```vue {{ filename: 'billing.vue' }} - - - - ``` - - + ) + } + ``` + + + + ```tsx {{ filename: 'src/components/BillingSection.tsx' }} + import { SignedIn } from '@clerk/clerk-react' + import { SubscriptionDetailsButton } from '@clerk/clerk-react/experimental' + + const BillingSection = () => { + return ( + + {/* Basic usage */} + + + {/* Customizes the appearance of the subscription details drawer */} + + + {/* Custom button */} + console.log('Subscription canceled')}> + + + + ) + } + + export default BillingSection + ``` + + + + ```vue {{ filename: 'billing.vue' }} + + + + ``` + + +## Properties + +All props are optional. + + + - `for?` + - `'user' | 'organization'` + + Determines whether to show subscription details for the current user or organization. Defaults to `'user'`. + + --- + + - `children?` + - `React.ReactNode` + + Optional custom button element. If not provided, defaults to a button with the text "Subscription details". + + --- + + - `onSubscriptionCancel?` + - `() => void` + + A callback function that is called when a subscription is cancelled. + + --- + + - `subscriptionDetailsProps?` + - `{ appearance: Appearance }` + + Options for the subscription details drawer. Accepts the following properties: + + - [`appearance`](/docs/guides/customizing-clerk/appearance-prop/overview): an object used to style your components. For example: ``. + diff --git a/docs/reference/components/clerk-provider.mdx b/docs/reference/components/clerk-provider.mdx index e1eebf6db2..b17c1b9315 100644 --- a/docs/reference/components/clerk-provider.mdx +++ b/docs/reference/components/clerk-provider.mdx @@ -1,155 +1,192 @@ --- title: '``' description: The component provides session and user context to Clerk's hooks and components. -sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start +sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start --- The `` component is required to integrate Clerk into your React application, providing session and user context to Clerk's hooks and components. The recommended approach is to wrap your entire app with `` at the entry point to make authentication globally accessible. If you only need authentication for specific routes or pieces of your application, render `` deeper in the component tree. This allows you to implement Clerk's functionality precisely where required without impacting the rest of your app. -## Usage - - - - - ```tsx {{ filename: 'app/layout.tsx' }} - import React from 'react' - import { ClerkProvider } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - {children} - - - ) - } - ``` - - ```tsx {{ filename: '_app.tsx' }} - import { ClerkProvider } from '@clerk/nextjs' - import type { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - ) - } - - export default MyApp - ``` - - - - - ```tsx {{ filename: 'index.tsx' }} - import React from 'react' - import ReactDOM from 'react-dom/client' - import App from './App.tsx' - import { ClerkProvider } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - ReactDOM.createRoot(document.getElementById('root')!).render( - - - - - , - ) - ``` - +## Example - - ```tsx {{ filename: 'app/_layout.tsx' }} - import { ClerkProvider } from '@clerk/clerk-expo' - import { Slot } from 'expo-router' + + + ```tsx {{ filename: 'app/layout.tsx' }} + import React from 'react' + import { ClerkProvider } from '@clerk/nextjs' - export default function Layout() { + export default function RootLayout({ children }: { children: React.ReactNode }) { return ( - + + {children} + ) } ``` - - - ```tsx {{ filename: 'app/root.tsx' }} - // Other imports + ```tsx {{ filename: '_app.tsx' }} + import { ClerkProvider } from '@clerk/nextjs' + import type { AppProps } from 'next/app' - import { ClerkProvider, SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/react-router' - - export default function App({ loaderData }: Route.ComponentProps) { + function MyApp({ Component, pageProps }: AppProps) { return ( - -
- - - - - - -
-
- -
+ + ) } - // Rest of the root.tsx code + export default MyApp ``` - - - - ```tsx {{ filename: 'src/routes/__root.tsx', ins: [3, 17, 27] }} - import * as React from 'react' - import { HeadContent, Outlet, Scripts, createRootRoute } from '@tanstack/react-router' - import { ClerkProvider } from '@clerk/tanstack-react-start' - - export const Route = createRootRoute({ - component: () => { - return ( - - - - ) - }, - }) - - function RootDocument({ children }: { children: React.ReactNode }) { + + + + + ```tsx {{ filename: 'index.tsx' }} + import React from 'react' + import ReactDOM from 'react-dom/client' + import App from './App.tsx' + import { ClerkProvider } from '@clerk/clerk-react' + + // Import your Publishable Key + const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + if (!PUBLISHABLE_KEY) { + throw new Error('Add your Clerk Publishable Key to the .env file') + } + + ReactDOM.createRoot(document.getElementById('root')!).render( + + + + + , + ) + ``` + + + + ```tsx {{ filename: 'app/_layout.tsx' }} + import { ClerkProvider } from '@clerk/clerk-expo' + import { Slot } from 'expo-router' + + export default function Layout() { + return ( + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/root.tsx' }} + // Other imports + + import { ClerkProvider, SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/react-router' + + export default function App({ loaderData }: Route.ComponentProps) { + return ( + +
+ + + + + + +
+
+ +
+ + ) + } + + // Rest of the root.tsx code + ``` + + + + ```jsx {{ filename: 'src/routes/index.tsx' }} + import { + ClerkProvider, + SignedIn, + SignedOut, + UserButton, + SignInButton, + } from '@clerk/chrome-extension' + + const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY + const EXTENSION_URL = chrome.runtime.getURL('.') + + if (!PUBLISHABLE_KEY) { + throw new Error('Please add the PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY to the .env.development file') + } + + export default function Index() { + return ( + +
+ + + + + + +
+ + ) + } + ``` + + + + ```tsx {{ filename: 'src/routes/__root.tsx', ins: [3, 17, 27] }} + import * as React from 'react' + import { HeadContent, Outlet, Scripts, createRootRoute } from '@tanstack/react-router' + import { ClerkProvider } from '@clerk/tanstack-react-start' + + export const Route = createRootRoute({ + component: () => { return ( - - - - - - - {children} - - - - + + + ) - } - ``` - - + }, + }) + + function RootDocument({ children }: { children: React.ReactNode }) { + return ( + + + + + + + {children} + + + + + ) + } + ``` + diff --git a/docs/reference/components/control/authenticate-with-redirect-callback.mdx b/docs/reference/components/control/authenticate-with-redirect-callback.mdx index 7b2fc2d1ae..63981d05ca 100644 --- a/docs/reference/components/control/authenticate-with-redirect-callback.mdx +++ b/docs/reference/components/control/authenticate-with-redirect-callback.mdx @@ -8,6 +8,10 @@ The `` component is a crucial part of implem This component automatically handles the OAuth callback, completing the authentication process and managing the user's session. It uses the [`handleRedirectCallback()`](/docs/reference/javascript/clerk#handle-redirect-callback) method under the hood. +## Example + +For an example of how to use the `` component, see the [custom flow](/docs/guides/development/custom-flows/authentication/oauth-connections) guide. + ## Properties All props are optional. @@ -102,7 +106,3 @@ All props are optional. The full URL or path to navigate to after requesting phone verification. - -## Usage - -For an example of how to use the `` component, see the [custom flow](/docs/guides/development/custom-flows/authentication/oauth-connections) guide. diff --git a/docs/reference/components/control/clerk-loaded.mdx b/docs/reference/components/control/clerk-loaded.mdx index 2fb7d6a315..e78695ad49 100644 --- a/docs/reference/components/control/clerk-loaded.mdx +++ b/docs/reference/components/control/clerk-loaded.mdx @@ -6,55 +6,47 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component guarantees that the Clerk object has loaded and will be available under `window.Clerk`. This allows you to wrap child components to access the `Clerk` object without the need to check it exists. -## Usage - -It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. - - - - - - ```tsx {{ filename: 'app/page.tsx' }} - import { ClerkLoaded } from '@clerk/nextjs' - - export default function Page() { - return ( - -

Clerk has loaded

- - - ) - } - ``` - - - - ```tsx {{ filename: 'pages/index.tsx' }} - import { ClerkLoaded } from '@clerk/nextjs' - - export default function Page() { - return ( - -

Clerk has loaded

- - - ) - } - ``` - - - - - - ```tsx {{ filename: 'example.tsx' }} + + ## Example + + It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. + + + ```tsx {{ filename: 'app/page.tsx' }} + import { ClerkLoaded } from '@clerk/nextjs' + + export default function Page() { + return ( + +

Clerk has loaded

+ + ) + } + ``` + + + + ```tsx {{ filename: 'src/App.tsx' }} import { ClerkLoaded } from '@clerk/clerk-react' - declare global { - interface Window { - Clerk: any - } + function App() { + return ( + +

Clerk has loaded

+ + ) } + export default App + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoaded } from '@clerk/react-router' + export default function Example() { return ( @@ -63,17 +55,25 @@ It's not recommended to wrap the entire app in the `` component; in ) } ``` - + - - ```tsx {{ filename: 'routes/index.tsx' }} - import { ClerkLoaded } from '@clerk/remix' + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { ClerkLoaded } from '@clerk/chrome-extension' - declare global { - interface Window { - Clerk: any - } + export default function Home() { + return ( + +

Clerk has loaded

+ + ) } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { ClerkLoaded } from '@clerk/remix' export default function Index() { return ( @@ -85,9 +85,24 @@ It's not recommended to wrap the entire app in the `` component; in ) } ``` - + + + + > [!NOTE] + > Unlike other Clerk components for Astro, `` must be imported from `@clerk/astro/react`. This requires that your Astro app is set up with React. See [Use Clerk with Astro and React](/docs/reference/astro/react) for guidance. + + ```astro {{ filename: 'index.astro' }} + --- + import { ClerkLoaded } from '@clerk/astro/react' + --- + + +

Clerk has loaded

+ + ``` + - + ```tsx {{ filename: 'app/index.tsx' }} import { ClerkLoaded } from '@clerk/clerk-expo' import { Text, View } from 'react-native' @@ -102,5 +117,88 @@ It's not recommended to wrap the entire app in the `` component; in ) } ``` - - + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { ClerkLoaded } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ +

Clerk has loaded

+ +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + + ## Usage with JavaScript + + The following methods available on an instance of the [`Clerk`](/docs/reference/javascript/clerk) class is used to render and control the `` component: + + - [`load()`](#load) + + The following examples assume that you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application. + + ### `load()` + + Render the `` component to an HTML `
` element. + + ```typescript + function load(options?: ClerkOptions): Promise + ``` + + #### `ClerkOptions` + + + + #### `load()` usage + + ```js {{ filename: 'main.js', mark: [7] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + ``` + diff --git a/docs/reference/components/control/clerk-loading.mdx b/docs/reference/components/control/clerk-loading.mdx index c04c5d4324..a9e1a08324 100644 --- a/docs/reference/components/control/clerk-loading.mdx +++ b/docs/reference/components/control/clerk-loading.mdx @@ -6,76 +6,20 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` renders its children while Clerk is loading, and is helpful for showing a custom loading state. -## Usage +## Example It's not recommended to wrap the entire app in the `` component; instead, only wrap the components that need access to the `Clerk` object. - - - - ```tsx {{ filename: 'app/page.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Page() { - return ( - <> - -

Clerk is loading...

- - -

Clerk has loaded

- - - ) - } - ``` - - ```tsx {{ filename: 'pages/index.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Page() { - return ( - <> - -

Clerk is loading

- - -

Clerk has loaded

- - - ) - } - ``` - - - - - ```tsx {{ filename: 'example.tsx' }} - import { ClerkLoaded, ClerkLoading } from '@clerk/clerk-react' - - declare global { - interface Window { - Clerk: any - } - } + + + ```tsx {{ filename: 'app/page.tsx' }} + import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - export default function Example() { + export default function Page() { return ( <> -

Clerk is loading

+

Clerk is loading...

Clerk has loaded

@@ -84,19 +28,11 @@ It's not recommended to wrap the entire app in the `` component; i ) } ``` - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { ClerkLoading, ClerkLoaded } from '@clerk/remix' - - declare global { - interface Window { - Clerk: any - } - } + ```tsx {{ filename: 'pages/index.tsx' }} + import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs' - export default function Index() { + export default function Page() { return ( <> @@ -109,31 +45,179 @@ It's not recommended to wrap the entire app in the `` component; i ) } ``` - - - - ```tsx {{ filename: 'app/index.tsx' }} - import { ClerkLoading, ClerkLoaded } from '@clerk/clerk-expo' - import { Text, View } from 'react-native' - - declare global { - interface Window { - Clerk: any - } - } - - export default function Screen() { - return ( - - - Clerk is loading - - - Clerk has loaded - - - ) - } - ``` - - + + + + + ```tsx {{ filename: 'src/App.tsx' }} + import { ClerkLoaded, ClerkLoading } from '@clerk/clerk-react' + + function App() { + return ( + <> + +

Clerk is loading

+ + +

Clerk has loaded

+ + + ) + } + + export default App + ``` + + + + ```tsx {{ filename: 'app/routes/example.tsx' }} + import { ClerkLoaded, ClerkLoading } from '@clerk/react-router' + + export default function Example() { + return ( + <> + +

Clerk is loading

+ + +

Clerk has loaded

+ + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { ClerkLoaded, ClerkLoading } from '@clerk/chrome-extension' + + export default function Home() { + return ( + <> + +

Clerk is loading

+ + +

Clerk has loaded

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { ClerkLoading, ClerkLoaded } from '@clerk/remix' + + export default function Index() { + return ( + <> + +

Clerk is loading

+ + +

Clerk has loaded

+ + + ) + } + ``` + + + + > [!NOTE] + > Unlike other Clerk components for Astro, `ClerkLoading` must be imported from `@clerk/astro/react`. This requires that your Astro app is set up with React. See [Use Clerk with Astro and React](/docs/reference/astro/react) for guidance. + + ```astro {{ filename: 'index.astro' }} + --- + import { ClerkLoading, ClerkLoaded } from '@clerk/astro/react' + --- + + +

Clerk is loading

+ + +

Clerk has loaded

+ + ``` + + + + ```tsx {{ filename: 'app/index.tsx' }} + import { ClerkLoading, ClerkLoaded } from '@clerk/clerk-expo' + import { Text, View } from 'react-native' + + export default function Screen() { + return ( + + + Clerk is loading + + + Clerk has loaded + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { ClerkLoading, ClerkLoaded } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ +

Clerk is loading

+ + +

Clerk has loaded

+ +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/protect.mdx b/docs/reference/components/control/protect.mdx index b265f8e294..25f2751fec 100644 --- a/docs/reference/components/control/protect.mdx +++ b/docs/reference/components/control/protect.mdx @@ -18,170 +18,164 @@ The [``](/docs/reference/components/control/protect) component protec > [!CAUTION] > This component only **visually hides** its children when the current user is not authorized. The contents of its children remain accessible via the browser's source code even if the user fails the authorization check. Do not use this component to hide sensitive information that should be completely inaccessible to unauthorized users. For truly sensitive data, perform [authorization checks](/docs/guides/secure/authorization-checks) on the server before sending the data to the client. -## Properties - - - - `condition?` - - `has => boolean` - - Optional conditional logic that renders the children if it returns `true`. - - --- - - - `fallback?` - - `JSX` - - Optional UI to show when a user doesn't have the correct type of access control to access the protected content. - - --- - - - `feature?` - - `string` - - Optional string corresponding to a [feature](/docs/guides/billing/overview). - - --- +## Usage - - `plan?` - - `string` +### Authentication checks - Optional string corresponding to a [plan](/docs/guides/billing/overview). +`` always performs authentication checks. It will render its children if the user is signed-in, and its `fallback` prop if the user is signed-out. - --- + + ```tsx {{ filename: 'app/dashboard/page.tsx' }} + import { Protect } from '@clerk/nextjs' - - `permission?` - - `string` + export default function Page() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { Protect } from '@clerk/clerk-react' + + function App() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } - Optional string corresponding to a [permission](/docs/guides/organizations/roles-and-permissions) in the format `org::` + export default App + ``` + + + ```astro {{ filename: 'src/pages/dashboard.astro' }} --- - - - `role?` - - `string` - - Optional string corresponding to a [role](/docs/guides/organizations/roles-and-permissions) in the format `org:` - + import { Protect } from '@clerk/astro/components' --- - - `treatPendingAsSignedOut?` - - `boolean` - - A boolean that indicates whether to treat [pending sessions](/docs/reference/javascript/types/session-status#properties) as signed out. Defaults to `true`. - - -## Usage - -### Authentication checks - -`` always performs authentication checks. It will render its children if the user is signed-in, and its `fallback` prop if the user is signed-out. + +

Users that are signed-out can see this.

+

Users that are signed-in can see this.

+ + ``` + + + + ```jsx + import { Protect } from '@clerk/clerk-expo' + import { Text } from 'react-native' + + export default function Screen() { + return ( + Users that are signed-out can see this.}> + Users that are signed-in can see this. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/dashboard.tsx' }} + import { Protect } from '@clerk/chrome-extension' + + export default function DashboardPage() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/dashboard.tsx' }} + import { Protect } from '@clerk/remix' + + export default function DashboardPage() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/dashboard.tsx' }} + import { Protect } from '@clerk/react-router' + + export default function DashboardPage() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/dashboard.tsx' }} + import { Protect } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/dashboard')({ + component: DashboardPage, + }) + + function DashboardPage() { + return ( + Users that are signed-out can see this.

}> +

Users that are signed-in can see this.

+ + ) + } + ``` + + + + ```vue + + + + ``` + - - - ```tsx {{ filename: 'app/dashboard/page.tsx' }} - import { Protect } from '@clerk/nextjs' - - export default function Page() { - return ( - Users that are signed-out can see this.

}> -

Users that are signed-in can see this.

- - ) - } - ``` - - - - ```jsx {{ filename: 'src/dashboard.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - Users that are signed-out can see this.

}> -

Users that are signed-in can see this.

- - ) - } - ``` - - - - ```astro {{ filename: 'src/pages/dashboard.astro' }} - --- - import { Protect } from '@clerk/astro/components' - --- + + ```vue {{ filename: 'pages/dashboard.vue' }} + + + ``` + ### Authorization checks @@ -195,128 +189,179 @@ For more complex authorization logic, [pass conditional logic to the `condition` The following example demonstrates how to use the `` component to protect content by checking if the user has the `org:invoices:create` permission. - - - ```jsx {{ filename: 'app/protected/invoices/page.tsx' }} - import { Protect } from '@clerk/nextjs' - - export default function Page() { - return ( - You do not have the permissions to create an invoice.

} - > -

Users with permission org:invoices:create can see this.

- - ) - } - ``` - - - - ```jsx {{ filename: 'src/invoices.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - You do not have the permissions to create an invoice.

} - > -

Users with permission org:invoices:create can see this.

- - ) - } - ``` - - - - ```astro {{ filename: 'src/pages/invoices.astro' }} - --- - import { Protect } from '@clerk/astro/components' - --- + + ```jsx {{ filename: 'app/protected/invoices/page.tsx' }} + import { Protect } from '@clerk/nextjs' + + export default function Page() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { Protect } from '@clerk/clerk-react' + + function App() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + + export default App + ``` + + + + ```astro {{ filename: 'src/pages/invoices.astro' }} + --- + import { Protect } from '@clerk/astro/components' + --- + + +

You do not have the permissions to create an invoice.

+

Users with permission org:invoices:create can see this.

+ + ``` + + + + ```jsx + import { Protect } from '@clerk/clerk-expo' + import { Text } from 'react-native' + + export default function Screen() { + return ( + You do not have the permissions to create an invoice.} + > + Users with permission org:invoices:create can see this. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/invoices.tsx' }} + import { Protect } from '@clerk/chrome-extension' + + export default function InvoicesPage() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/invoices.tsx' }} + import { Protect } from '@clerk/remix' + + export default function InvoicesPage() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/invoices.tsx' }} + import { Protect } from '@clerk/react-router' + + export default function InvoicesPage() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/invoices.tsx' }} + import { Protect } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/invoices')({ + component: InvoicesPage, + }) + + function InvoicesPage() { + return ( + You do not have the permissions to create an invoice.

} + > +

Users with permission org:invoices:create can see this.

+ + ) + } + ``` + + + + ```vue + + + + ``` + + + + ```vue {{ filename: 'pages/invoices.vue' }} + + + ``` + ### Render content by role @@ -324,487 +369,780 @@ While authorization by `permission` is **recommended**, for convenience, `` component to protect content by checking if the user has the `org:billing` role. - - - ```jsx {{ filename: 'app/protected/billing/page.tsx' }} - import { Protect } from '@clerk/nextjs' - - export default function ProtectPage() { - return ( - Only a member of the Billing department can access this content.

} - > -

Users with role org:billing can see this.

- - ) - } - ``` - - - - ```jsx {{ filename: 'src/billing.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - Only a member of the Billing department can access this content.

} - > -

Users with role org:billing can see this.

- - ) - } - ``` - - - - ```astro {{ filename: 'src/pages/billing.astro' }} - --- - import { Protect } from '@clerk/astro/components' - --- + + ```jsx {{ filename: 'app/protected/billing/page.tsx' }} + import { Protect } from '@clerk/nextjs' + + export default function ProtectPage() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { Protect } from '@clerk/clerk-react' + + function App() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + + export default App + ``` + + + + ```astro {{ filename: 'src/pages/billing.astro' }} + --- + import { Protect } from '@clerk/astro/components' + --- + +

Only a member of the Billing department can access this content.

+

Users with role org:billing can see this.

+ + ``` + + + + ```jsx + import { Protect } from '@clerk/clerk-expo' + import { Text } from 'react-native' + + export default function Screen() { + return ( + Only a member of the Billing department can access this content.} + > + Users with role org:billing can see this. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/billing.tsx' }} + import { Protect } from '@clerk/chrome-extension' + + export default function BillingPage() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/billing.tsx' }} + import { Protect } from '@clerk/remix' + + export default function BillingPage() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/billing.tsx' }} + import { Protect } from '@clerk/react-router' + + export default function BillingPage() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/billing.tsx' }} + import { Protect } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/billing')({ + component: BillingPage, + }) + + function BillingPage() { + return ( + Only a member of the Billing department can access this content.

} + > +

Users with role org:billing can see this.

+ + ) + } + ``` + + + + ```vue + + + + ``` + + + + ```vue {{ filename: 'pages/billing.vue' }} + + + + ``` + ### Render content by plan The following example demonstrates how to use `` to protect content by checking if the user has a plan. - - - ```tsx {{ filename: 'app/protected/bronze/page.tsx' }} - import { Protect } from '@clerk/nextjs' - - export default function ProtectPage() { - return ( - Sorry, only subscribers to the Bronze plan can access this content.

} - > -

Welcome, Bronze subscriber!

- - ) - } - ``` - - - - ```tsx {{ filename: 'src/bronze.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - Sorry, only subscribers to the Bronze plan can access this content.

} - > -

Welcome, Bronze subscriber!

- - ) - } - ``` - - - - ```astro {{ filename: 'src/pages/bronze.astro' }} - --- - import { Protect } from '@clerk/astro/components' - --- + + ```tsx {{ filename: 'app/protected/bronze/page.tsx' }} + import { Protect } from '@clerk/nextjs' + + export default function ProtectPage() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + ``` + + + + ```tsx {{ filename: 'src/App.tsx' }} + import { Protect } from '@clerk/clerk-react' + + function App() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + + export default App + ``` + + + + ```astro {{ filename: 'src/pages/bronze.astro' }} + --- + import { Protect } from '@clerk/astro/components' + --- + + +

Sorry, only subscribers to the Bronze plan can access this content.

+

Welcome, Bronze subscriber!

+ + ``` + + + + ```tsx {{ filename: 'app/(billing)/bronze.tsx' }} + import { Protect } from '@clerk/clerk-expo' + import { Text } from 'react-native' + + export default function Page() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.} + > + Welcome, Bronze subscriber! + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/bronze.tsx' }} + import { Protect } from '@clerk/chrome-extension' + + export default function BronzePage() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/bronze.tsx' }} + import { Protect } from '@clerk/remix' + + export default function BronzePage() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/bronze.tsx' }} + import { Protect } from '@clerk/react-router' + + export default function BronzePage() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/bronze.tsx' }} + import { Protect } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/bronze')({ + component: BronzePage, + }) + + function BronzePage() { + return ( + Sorry, only subscribers to the Bronze plan can access this content.

} + > +

Welcome, Bronze subscriber!

+ + ) + } + ``` + + + + ```vue + + + + ``` + + + + ```vue {{ filename: 'pages/bronze.vue' }} + + + ``` + ### Render content by feature The following example demonstrates how to use `` to protect content by checking if the user has a feature. - - - ```tsx {{ filename: 'app/protected/premium-access/page.tsx' }} - import { Protect } from '@clerk/nextjs' - - export default function Page() { - return ( - Sorry, only subscribers with the Premium Access feature can access this content.

- } - > -

Congratulations! You have access to the Premium Access feature.

- - ) - } - ``` - - - - ```tsx {{ filename: 'src/premium-access.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - Sorry, only subscribers with the Premium Access feature can access this content.

- } - > -

Congratulations! You have access to the Premium Access feature.

- - ) - } - ``` - - - - ```astro {{ filename: 'src/pages/premium-access.astro' }} - --- - import { Protect } from '@clerk/astro/components' - --- + + ```tsx {{ filename: 'app/protected/premium-access/page.tsx' }} + import { Protect } from '@clerk/nextjs' + + export default function Page() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'src/App.tsx' }} + import { Protect } from '@clerk/clerk-react' + + function App() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + + export default App + ``` + + + + ```astro {{ filename: 'src/pages/premium-access.astro' }} + --- + import { Protect } from '@clerk/astro/components' + --- + + +

+ Sorry, only subscribers with the Premium Access feature can access this content. +

+

Congratulations! You have access to the Premium Access feature.

+ + ``` + + + + ```tsx {{ filename: 'app/(billing)/premium-access.tsx' }} + import { Protect } from '@clerk/clerk-expo' + import { Text } from 'react-native' + + export default function Page() { + return ( + + Sorry, only subscribers with the Premium Access feature can access this content. + + } + > + Congratulations! You have access to the Premium Access feature. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/premium-access.tsx' }} + import { Protect } from '@clerk/chrome-extension' + + export default function PremiumAccessPage() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/premium-access.tsx' }} + import { Protect } from '@clerk/remix' + + export default function PremiumAccessPage() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/premium-access.tsx' }} + import { Protect } from '@clerk/react-router' + + export default function PremiumAccessPage() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/premium-access.tsx' }} + import { Protect } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/premium-access')({ + component: PremiumAccessPage, + }) + + function PremiumAccessPage() { + return ( + Sorry, only subscribers with the Premium Access feature can access this content.

+ } + > +

Congratulations! You have access to the Premium Access feature.

+ + ) + } + ``` + + + + ```vue + + + + ``` + + + + ```vue {{ filename: 'pages/premium-access.vue' }} + + + ``` + ### Render content conditionally The following example uses ``'s `condition` prop to conditionally render its children if the user has the correct role. - - - ```tsx {{ filename: 'app/dashboard/settings/page.tsx' }} - import type { PropsWithChildren } from 'react' - import { Protect } from '@clerk/nextjs' - - export default function Page() { - return ( - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })} - fallback={

Only an Admin or Billing Manager can access this content.

} - > -

The settings page.

- - ) - } - ``` - - - - ```tsx {{ filename: 'src/settings.tsx' }} - import { Protect } from '@clerk/clerk-react' - - export default function Page() { - return ( - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })} - fallback={

Only an Admin or Billing Manager can access this content.

} - > -

The settings page.

- - ) - } - ``` - - - - ```astro - --- - import { Protect } from '@clerk/astro/components' - --- - - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}> -

Only an Admin or Billing Manager can access this content.

-

The settings page.

- - ``` - - - - ```tsx {{ filename: 'app/dashboard/settings/page.tsx' }} - import { Protect } from '@clerk/clerk-expo' - import { Text } from 'react-native' - - export default function Page() { - return ( - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })} - fallback={Only an Admin or Billing Manager can access this content.} - > - The settings page. - - ) - } - ``` - - - - ```tsx {{ filename: 'app/routes/settings.tsx' }} - import { Protect } from '@clerk/react-router' - - export default function SettingsPage() { - return ( - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })} - fallback={

Only an Admin or Billing Manager can access this content.

} - > -

The settings page.

- - ) - } - ``` - - - - ```tsx {{ filename: 'app/routes/settings.tsx' }} - import { Protect } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' - - export const Route = createFileRoute('/settings')({ - component: SettingsPage, - }) - - function SettingsPage() { - return ( - has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })} - fallback={

Only an Admin or Billing Manager can access this content.

} - > -

The settings page.

- - ) - } - ``` - - - - ```vue - - - - ``` - - + ) + } + ``` + + + + ```vue + + + + ``` + + + + ```vue {{ filename: 'pages/settings.vue' }} + + + + ``` + + +## Properties + + + - `condition?` + - `has => boolean` + + Optional conditional logic that renders the children if it returns `true`. + + --- + + - `fallback?` + - `JSX` + + Optional UI to show when a user doesn't have the correct type of access control to access the protected content. + + --- + + - `feature?` + - `string` + + Optional string corresponding to a [feature](/docs/guides/billing/overview). + + --- + + - `plan?` + - `string` + + Optional string corresponding to a [plan](/docs/guides/billing/overview). + + --- + + - `permission?` + - `string` + + Optional string corresponding to a [permission](/docs/guides/organizations/roles-and-permissions) in the format `org::` + + --- + + - `role?` + - `string` + + Optional string corresponding to a [role](/docs/guides/organizations/roles-and-permissions) in the format `org:` + + --- + + - `treatPendingAsSignedOut?` + - `boolean` + + A boolean that indicates whether to treat [pending sessions](/docs/reference/javascript/types/session-status#properties) as signed out. Defaults to `true`. + diff --git a/docs/reference/components/control/redirect-to-create-organization.mdx b/docs/reference/components/control/redirect-to-create-organization.mdx index f4e97be436..f6032c01c5 100644 --- a/docs/reference/components/control/redirect-to-create-organization.mdx +++ b/docs/reference/components/control/redirect-to-create-organization.mdx @@ -1,7 +1,7 @@ --- title: '`` (deprecated)' description: The component will navigate to the user profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +sdk: nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- > [!WARNING] @@ -9,67 +9,132 @@ sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react- The `` component will navigate to the create organization flow which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -## Usage - - - - ```tsx {{ filename: 'pages/_app.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - - You need to sign in to create an organization. - - ) - } - - export default MyApp - ``` - - - - ```tsx {{ filename: 'pages/privatepage.tsx' }} - import { - ClerkProvider, - SignedIn, - SignedOut, - RedirectToCreateOrganization, - } from '@clerk/clerk-react' - - function PrivatePage() { - return ( - - - - - You need to sign in to create an organization. - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/remix' - - export default function Index() { - return ( -
- - - - -

You need to sign in to create an organization.

- -
- ) - } - ``` - - +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + + + + You need to sign in to create an organization. + + ) + } + ``` + + + + ```tsx {{ filename: 'pages/index.tsx' }} + import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + + + + You need to sign in to create an organization. + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/react-router' + + export default function Home() { + return ( + <> + + + + You need to sign in to create an organization. + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + +

You need to sign in to create an organization.

+ +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, SignedOut, RedirectToCreateOrganization } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + +

You need to sign in to create an organization.

+ +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/redirect-to-organization-profile.mdx b/docs/reference/components/control/redirect-to-organization-profile.mdx index 562eae00ed..b69e966921 100644 --- a/docs/reference/components/control/redirect-to-organization-profile.mdx +++ b/docs/reference/components/control/redirect-to-organization-profile.mdx @@ -1,7 +1,7 @@ --- title: '`` (deprecated)' description: The component will navigate to the organization profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +sdk: nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- > [!WARNING] @@ -9,67 +9,132 @@ sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react- The `` component will navigate to the organization profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -## Usage - - - - ```tsx {{ filename: 'pages/_app.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - - You need to sign in to view your organization profile. - - ) - } - - export default MyApp - ``` - - - - ```tsx {{ filename: 'pages/privatepage.tsx' }} - import { - ClerkProvider, - SignedIn, - SignedOut, - RedirectToOrganizationProfile, - } from '@clerk/clerk-react' - - function PrivatePage() { - return ( - - - - - You need to sign in to view your organization profile. - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/remix' - - export default function Index() { - return ( -
- - - - -

You need to sign in to view your organization profile.

- -
- ) - } - ``` - - +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + + + + You need to sign in to view your organization profile. + + ) + } + ``` + + + + ```tsx {{ filename: 'pages/index.tsx' }} + import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + + + + You need to sign in to view your organization profile. + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/Home.tsx' }} + import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/react-router' + + export default function Home() { + return ( + <> + + + + You need to sign in to view your organization profile. + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + +

You need to sign in to view your organization profile.

+ +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, SignedOut, RedirectToOrganizationProfile } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + +

You need to sign in to view your organization profile.

+ +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/redirect-to-sign-in.mdx b/docs/reference/components/control/redirect-to-sign-in.mdx index 3e22d8f82a..1f82e797b2 100644 --- a/docs/reference/components/control/redirect-to-sign-in.mdx +++ b/docs/reference/components/control/redirect-to-sign-in.mdx @@ -1,130 +1,165 @@ --- title: '``' description: The component will navigate to the sign in URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- The `` component will navigate to the sign in URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -## Usage - - - - - ```tsx {{ filename: 'app/layout.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToSignIn } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - - {children} - - - - - - - ) - } - ``` - - - - ```tsx {{ filename: 'pages/_app.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToSignIn } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - - - - - - ) - } - - export default MyApp - ``` - - - - - ```tsx {{ filename: 'pages/privatepage.tsx' }} - import { - ClerkProvider, - SignedIn, - SignedOut, - RedirectToSignIn, - UserButton, - } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function PrivatePage() { - return ( - - - - - - - - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/remix' - - export default function Index() { - return ( -
- - - - - - -
- ) - } - ``` - - - -## Properties - - - - `signInFallbackRedirectUrl?` - - `string` - - The fallback URL to redirect to after the user signs in, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signInForceRedirectUrl?` - - `string` - - If provided, this URL will always be redirected to after the user signs in. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `initialValues` - - [`SignInInitialValues`](/docs/reference/javascript/types/sign-in-initial-values) - - The values used to prefill the sign-in fields with. - +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'pages/index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/react-router' + + export default function Home() { + return ( + <> + + + + + + + + ) + } + ``` + + + + > [!NOTE] + > This component relies on React Router for navigation. Ensure that you have integrated React Router into your Chrome Extension application before using it. [Learn how to add React Router to your Chrome Extension](/docs/guides/development/add-react-router). + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/chrome-extension' + + export default function Home() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/redirect-to-sign-up.mdx b/docs/reference/components/control/redirect-to-sign-up.mdx index 2f2009ab9c..e6b9993c11 100644 --- a/docs/reference/components/control/redirect-to-sign-up.mdx +++ b/docs/reference/components/control/redirect-to-sign-up.mdx @@ -1,130 +1,165 @@ --- title: '``' description: The component will navigate to the sign up URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- The `` component will navigate to the sign up URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -## Usage - - - - - ```tsx {{ filename: 'app/layout.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToSignUp } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - - {children} - - - - - - - ) - } - ``` - - - - ```tsx {{ filename: 'pages/_app.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToSignUp } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - - - - - - ) - } - - export default MyApp - ``` - - - - - ```tsx {{ filename: 'pages/privatepage.tsx' }} - import { - ClerkProvider, - SignedIn, - SignedOut, - RedirectToSignUp, - UserButton, - } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function PrivatePage() { - return ( - - - - - - - - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/remix' - - export default function Index() { - return ( -
- - - - - - -
- ) - } - ``` - - - -## Properties - - - - `signUpFallbackRedirectUrl?` - - `string` - - The fallback URL to redirect to after the user signs up, if there's no `redirect_url` in the path already. Defaults to `/`. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `signUpForceRedirectUrl?` - - `string` - - If provided, this URL will always be redirected to after the user signs up. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `initialValues` - - [`SignUpInitialValues`](/docs/reference/javascript/types/sign-up-initial-values) - - The values used to prefill the sign-up fields with. - +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'pages/index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/react-router' + + export default function Home() { + return ( + <> + + + + + + + + ) + } + ``` + + + + > [!NOTE] + > This component relies on React Router for navigation. Ensure that you have integrated React Router into your Chrome Extension application before using it. [Learn how to add React Router to your Chrome Extension](/docs/guides/development/add-react-router). + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/chrome-extension' + + export default function Home() { + return ( + <> + + + + + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, SignedOut, RedirectToSignUp, UserButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/redirect-to-user-profile.mdx b/docs/reference/components/control/redirect-to-user-profile.mdx index 52d778af79..e735df0dd3 100644 --- a/docs/reference/components/control/redirect-to-user-profile.mdx +++ b/docs/reference/components/control/redirect-to-user-profile.mdx @@ -1,7 +1,7 @@ --- title: '`` (deprecated)' description: The component will navigate to the user profile URL which has been configured in your application instance. The behavior will be just like a server-side (3xx) redirect, and will override the current location in the history stack. -sdk: chrome-extension, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +sdk: nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- > [!WARNING] @@ -14,73 +14,138 @@ To find your User Profile URL: 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. 1. Under **User profile**, select the **Visit** icon. -## Usage - - - - ```tsx {{ filename: 'pages/_app.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - - - - -

You need to sign in to view your user profile.

- - - ) - } - - export default MyApp - ``` - - - - ```tsx {{ filename: 'pages/privatepage.tsx' }} - import { ClerkProvider, SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function PrivatePage() { - return ( - - - - - -

You need to sign in to view your user profile.

- - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/remix' - - export default function Index() { - return ( -
- - - - -

You need to sign in to view your user profile.

- -
- ) - } - ``` - - +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/nextjs' + + function Page() { + return ( + <> + + + + +

You need to sign in to view your user profile.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'pages/index.tsx' }} + import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + + + + +

You need to sign in to view your user profile.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/react-router' + + export default function Home() { + return ( + <> + + + + +

You need to sign in to view your user profile.

+ + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + +

You need to sign in to view your user profile.

+ +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, SignedOut, RedirectToUserProfile } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + +

You need to sign in to view your user profile.

+ +
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + diff --git a/docs/reference/components/control/signed-in.mdx b/docs/reference/components/control/signed-in.mdx index 7a37f5a959..66b65cced8 100644 --- a/docs/reference/components/control/signed-in.mdx +++ b/docs/reference/components/control/signed-in.mdx @@ -11,6 +11,176 @@ The `` component offers authentication checks as a cross-cutting conce > [!CAUTION] > This component only **visually hides** its children when the current user is not authenticated. The contents of its children remain accessible via the browser's source code even if the user fails the authentication check. Do not use this component to hide sensitive information that should be completely inaccessible to unauthorized users. For truly sensitive data, perform [authorization checks](/docs/guides/secure/authorization-checks) on the server before sending the data to the client. +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedIn } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + +
You are signed in.
+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'routes/index.tsx' }} + import { SignedIn } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + +
You are signed in.
+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn } from '@clerk/react-router' + + export default function Home() { + return ( + <> + +
You are signed in.
+ +

This content is always visible.

+ + ) + } + ``` + + + + ```astro {{ filename: 'index.astro' }} + --- + import { SignedIn } from '@clerk/astro/components' + --- + + +
You are signed in.
+ +

This content is always visible.

+ ``` + + + + ```tsx {{ filename: 'app/index.tsx' }} + import { SignedIn } from '@clerk/clerk-expo' + import { Text, View } from 'react-native' + + export default function Screen() { + return ( + + + You are signed in. + + This content is always visible. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignedIn } from '@clerk/chrome-extension' + + export default function Home() { + return ( + <> + +

You are signed in.

+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn } from '@clerk/remix' + + export default function Index() { + return ( +
+ +

You are signed in.

+ +

This content is always visible.

+
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ +

You are signed in.

+ +

This content is always visible.

+
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + ## Properties @@ -19,194 +189,3 @@ The `` component offers authentication checks as a cross-cutting conce A boolean that indicates whether to treat [pending sessions](/docs/reference/javascript/types/session-status#properties) as signed out. Defaults to `true`. - -## Usage - - - - - ```tsx {{ filename: 'app/page.tsx' }} - import React from 'react' - import { ClerkProvider, SignedIn } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - -
- -
You are signed in
- -

This content is always visible.

-
- {children} - - - - ) - } - ``` - - ```tsx {{ filename: 'app.tsx' }} - import '@/styles/globals.css' - import { ClerkProvider, SignedIn } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - -
You are signed in
- -

This content is always visible.

- - ) - } - - export default MyApp - ``` - - - - - ```tsx {{ filename: 'app.tsx' }} - import { SignedIn, ClerkProvider } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function Page() { - return ( - - -
This content is visible only to signed in users.
- -

This content is always visible.

- - ) - } - ``` - - ### Usage with React Router - - ```tsx {{ filename: 'app.tsx' }} - import { Routes, Route } from 'react-router' - import { ClerkProvider, SignedIn } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function App() { - return ( - - - This page is publicly accessible.
} /> - -
This content is accessible only to signed in users.
- - } - /> - - - ) - } - ``` - - - - ```astro {{ filename: 'index.astro' }} - --- - import { SignedIn } from '@clerk/astro/components' - --- - - -
You are signed in
- -

This content is always visible.

- ``` - - - - ```tsx {{ filename: 'app/index.tsx' }} - import { SignedIn } from '@clerk/clerk-expo' - import { Text, View } from 'react-native' - - export default function Screen() { - return ( - - - You are signed in - - This content is always visible. - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedIn, UserButton } from '@clerk/remix' - - export default function Index() { - return ( -
- -

You are signed in

- -

Always visible

-
- ) - } - ``` - - - - ```tsx {{ filename: 'app/routes/index.tsx' }} - import { SignedIn } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' - - export const Route = createFileRoute('/')({ - component: Home, - }) - - function Home() { - return ( -
- -

You are signed in

- -

Always visible

-
- ) - } - ``` - - - - ```vue {{ filename: 'App.vue' }} - - - - ``` - - diff --git a/docs/reference/components/control/signed-out.mdx b/docs/reference/components/control/signed-out.mdx index a6fca5a4c2..86254ec8e2 100644 --- a/docs/reference/components/control/signed-out.mdx +++ b/docs/reference/components/control/signed-out.mdx @@ -6,6 +6,176 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component offers authentication checks as a cross-cutting concern. Any child nodes wrapped by a `` component will be rendered only if there's no User signed in to your application. +## Example + + + ```tsx {{ filename: 'app/page.tsx' }} + import { SignedOut } from '@clerk/nextjs' + + export default function Page() { + return ( + <> + +
You are signed out.
+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'routes/index.tsx' }} + import { SignedOut } from '@clerk/clerk-react' + + export default function Page() { + return ( + <> + +

You are signed out.

+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedOut } from '@clerk/react-router' + + export default function Home() { + return ( + <> + +

You are signed out.

+ +

This content is always visible.

+ + ) + } + ``` + + + + ```astro {{ filename: 'index.astro' }} + --- + import { SignedOut } from '@clerk/astro/components' + --- + + +
You are signed out.
+ +

This content is always visible.

+ ``` + + + + ```tsx {{ filename: 'app/index.tsx' }} + import { SignedOut } from '@clerk/clerk-expo' + import { Text, View } from 'react-native' + + export default function Screen() { + return ( + + + You are signed out. + + This content is always visible. + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignedOut } from '@clerk/chrome-extension' + + export default function Home() { + return ( + <> + +

You are signed out.

+ +

This content is always visible.

+ + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedOut } from '@clerk/remix' + + export default function Index() { + return ( +
+ +

You are signed out.

+ +

This content is always visible.

+
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedOut } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ +

You are signed out.

+ +

This content is always visible.

+
+ ) + } + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + + + ```vue {{ filename: 'App.vue' }} + + + + ``` + + ## Properties @@ -14,187 +184,3 @@ The `` component offers authentication checks as a cross-cutting conc A boolean that indicates whether to treat [pending sessions](/docs/reference/javascript/types/session-status#properties) as signed out. Defaults to `true`. - -## Usage - - - - - ```tsx {{ filename: 'app/page.tsx' }} - import React from 'react' - import { ClerkProvider, SignedOut } from '@clerk/nextjs' - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - - -
- -

You are signed out.

- -

This content is always visible.

-
- {children} - - - - ) - } - ``` - - ```tsx {{ filename: 'app.tsx' }} - import '@/styles/globals.css' - import { ClerkProvider, RedirectToSignIn, SignedOut } from '@clerk/nextjs' - import { AppProps } from 'next/app' - - function MyApp({ Component, pageProps }: AppProps) { - return ( - - -

You are signed out.

- -

This content is always visible.

- - ) - } - - export default MyApp - ``` - - - - - ```tsx {{ filename: 'app.tsx' }} - import { SignedOut, ClerkProvider } from '@clerk/clerk-react' - - // Import your Publishable Key - const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY - - if (!PUBLISHABLE_KEY) { - throw new Error('Add your Clerk Publishable Key to the .env file') - } - - function Page() { - return ( - - -

You are signed out.

- -

This content is always visible.

- - ) - } - ``` - - ### Usage with React Router - - ```tsx {{ filename: 'app.tsx' }} - import { Routes, Route } from 'react-router' - import { ClerkProvider, SignedOut } from '@clerk/clerk-react' - - function App() { - return ( - - - This page is publicly accessible.

} /> - -

You are signed out.

- - } - /> - - - ) - } - ``` - - - - ```astro {{ filename: 'index.astro' }} - --- - import { SignedOut } from '@clerk/astro/components' - --- - - -
You are signed out
- -

This content is always visible.

- ``` - - - - ```tsx {{ filename: 'app/index.tsx' }} - import { SignedOut } from '@clerk/clerk-expo' - import { Text, View } from 'react-native' - - export default function Screen() { - return ( - - - You are signed out - - This content is always visible. - - ) - } - ``` - - - - ```tsx {{ filename: 'routes/index.tsx' }} - import { SignedOut } from '@clerk/remix' - - export default function Index() { - return ( -
- -

You are signed out.

- -

This content is always visible.

-
- ) - } - ``` - - - - ```tsx {{ filename: 'app/routes/index.tsx' }} - import { SignedOut } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' - - export const Route = createFileRoute('/')({ - component: Home, - }) - - function Home() { - return ( -
- -

You are signed out.

- -

This content is always visible.

-
- ) - } - ``` - - - - ```vue {{ filename: 'App.vue' }} - - - - ``` - - diff --git a/docs/reference/components/organization/create-organization.mdx b/docs/reference/components/organization/create-organization.mdx index 531ae54f41..b10d10cd39 100644 --- a/docs/reference/components/organization/create-organization.mdx +++ b/docs/reference/components/organization/create-organization.mdx @@ -8,65 +8,14 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component is used to render an organization creation UI that allows users to create brand new organizations in your application. -## Properties - -All props are optional. - - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `afterCreateOrganizationUrl` - - `string` - - Full URL or path to navigate to after creating a new organization. - - --- - - - `routing` - - `'hash' | 'path'` - - The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. - - --- - - - `path` - - `string` - - The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/create-organization`. - - --- - - - `skipInvitationScreen` - - `boolean` - - Hides the screen for sending invitations after an organization is created. When left undefined, Clerk will automatically hide the screen if the number of max allowed members is equal to 1 - - --- - - - `hideSlug` - - `boolean` - - Hides the optional slug field in the organization creation screen. - - --- - - - `fallback?` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - -## Usage with frameworks + + ## Example -The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. + The following example includes a basic implementation of the `` component. You can use this as a starting point for your own implementation. - - + ```jsx {{ filename: 'app/create-organization/[[...create-organization]]/page.tsx' }} import { CreateOrganization } from '@clerk/nextjs' @@ -74,19 +23,31 @@ The following example includes a basic implementation of the ` } ``` - + - - ```jsx {{ filename: 'create-organization.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { CreateOrganization } from '@clerk/clerk-react' + function App() { + return + } + + export default App + ``` + + + + ```tsx {{ filename: 'app/routes/create-organization.tsx' }} + import { CreateOrganization } from '@clerk/react-router' + export default function CreateOrganizationPage() { return } ``` - + - + ```astro {{ filename: '/pages/create-organization.astro' }} --- import { CreateOrganization } from '@clerk/astro/components' @@ -94,9 +55,9 @@ The following example includes a basic implementation of the ` ``` - + - + ```jsx {{ filename: '/app/create-organization.web.tsx' }} @@ -106,19 +67,29 @@ The following example includes a basic implementation of the ` } ``` - + - - ```jsx {{ filename: '/route/create-organization/$.tsx' }} + + ```jsx {{ filename: 'src/routes/create-organization.tsx' }} + import { CreateOrganization } from '@clerk/chrome-extension' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/create-organization.tsx' }} import { CreateOrganization } from '@clerk/remix' export default function CreateOrganizationPage() { return } ``` - + - + ```tsx {{ filename: 'app/routes/create-organization.tsx' }} import { CreateOrganization } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -131,9 +102,9 @@ The following example includes a basic implementation of the ` } ``` - + - + ```vue {{ filename: 'create-organization.vue' }} + + + ``` + + -## Usage with JavaScript + + ## Usage with JavaScript -The following methods available on an instance of the [`Clerk`](/docs/reference/javascript/clerk) class are used to render and control the `` component: + The following methods available on an instance of the [`Clerk`](/docs/reference/javascript/clerk) class are used to render and control the `` component: -- [`mountCreateOrganization`](#mount-create-organization) -- [`unmountCreateOrganization`](#unmount-create-organization) -- [`openCreateOrganization`](#open-create-organization) -- [`closeCreateOrganization`](#close-create-organization) + - [`mountCreateOrganization`](#mount-create-organization) + - [`unmountCreateOrganization`](#unmount-create-organization) + - [`openCreateOrganization`](#open-create-organization) + - [`closeCreateOrganization`](#close-create-organization) -The following examples assume that you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application. + The following examples assume that you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application. -### mountCreateOrganization() + ### mountCreateOrganization() -Render the `` component to an HTML `
` element. + Render the `` component to an HTML `
` element. -```typescript -function mountCreateOrganization(node: HTMLDivElement, props?: CreateOrganizationProps): void -``` + ```typescript + function mountCreateOrganization(node: HTMLDivElement, props?: CreateOrganizationProps): void + ``` -### mountCreateOrganization() params + ### mountCreateOrganization() params - - - `node` - - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) - The `
` element used to render in the `` component + The `
` element used to render in the `` component - --- + --- - - `props?` - - [`CreateOrganizationProps`](#properties) + - `props?` + - [`CreateOrganizationProps`](#properties) - The properties to pass to the `` component - + The properties to pass to the `` component + -#### `mountCreateOrganization()` usage + #### `mountCreateOrganization()` usage -```js {{ filename: 'main.js', mark: [15] }} -import { Clerk } from '@clerk/clerk-js' + ```js {{ filename: 'main.js', mark: [15] }} + import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY -const clerk = new Clerk(clerkPubKey) -await clerk.load() + const clerk = new Clerk(clerkPubKey) + await clerk.load() -document.getElementById('app').innerHTML = ` -
-` + document.getElementById('app').innerHTML = ` +
+ ` -const createOrgDiv = document.getElementById('create-organization') + const createOrgDiv = document.getElementById('create-organization') -clerk.mountCreateOrganization(createOrgDiv) -``` + clerk.mountCreateOrganization(createOrgDiv) + ``` -### unmountCreateOrganization() + ### unmountCreateOrganization() -Unmount and run cleanup on an existing `` component instance. + Unmount and run cleanup on an existing `` component instance. -```typescript -function unmountCreateOrganization(node: HTMLDivElement): void -``` + ```typescript + function unmountCreateOrganization(node: HTMLDivElement): void + ``` -#### `unmountCreateOrganization()` params + #### `unmountCreateOrganization()` params - - - `node` - - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) - The container `
` element with a rendered `` component instance - + The container `
` element with a rendered `` component instance + -#### `unmountCreateOrganization()` usage + #### `unmountCreateOrganization()` usage -```js {{ filename: 'main.js', mark: [19] }} -import { Clerk } from '@clerk/clerk-js' + ```js {{ filename: 'main.js', mark: [19] }} + import { Clerk } from '@clerk/clerk-js' -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY -const clerk = new Clerk(clerkPubKey) -await clerk.load() + const clerk = new Clerk(clerkPubKey) + await clerk.load() -document.getElementById('app').innerHTML = ` -
-` + document.getElementById('app').innerHTML = ` +
+ ` -const createOrgDiv = document.getElementById('create-organization') + const createOrgDiv = document.getElementById('create-organization') -clerk.mountCreateOrganization(createOrgDiv) + clerk.mountCreateOrganization(createOrgDiv) -// ... + // ... -clerk.unmountCreateOrganization(createOrgDiv) -``` + clerk.unmountCreateOrganization(createOrgDiv) + ``` -### `openCreateOrganization()` + ### `openCreateOrganization()` -Opens the `` component as an overlay at the root of your HTML `body` element. + Opens the `` component as an overlay at the root of your HTML `body` element. -```typescript -function openCreateOrganization(props?: CreateOrganizationProps): void -``` + ```typescript + function openCreateOrganization(props?: CreateOrganizationProps): void + ``` -#### `openCreateOrganization()` params + #### `openCreateOrganization()` params - - - `props?` - - [`CreateOrganizationProps`](#properties) + + - `props?` + - [`CreateOrganizationProps`](#properties) - The properties to pass to the `` component - + The properties to pass to the `` component + + + #### `openCreateOrganization()` usage + + ```js {{ filename: 'main.js', mark: [15] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const createOrgDiv = document.getElementById('create-organization') + + clerk.openCreateOrganization(createOrgDiv) + ``` + + ### `closeCreateOrganization()` + + Closes the organization profile overlay. + + ```typescript + function closeCreateOrganization(): void + ``` + + #### `closeCreateOrganization()` usage + + ```js {{ filename: 'main.js', mark: [19] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const createOrgDiv = document.getElementById('create-organization') + + clerk.openCreateOrganization(createOrgDiv) + + // ... + + clerk.closeCreateOrganization(createOrgDiv) + ``` + -#### `openCreateOrganization()` usage +## Properties -```js {{ filename: 'main.js', mark: [15] }} -import { Clerk } from '@clerk/clerk-js' +All props are optional. -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined -const clerk = new Clerk(clerkPubKey) -await clerk.load() + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. -document.getElementById('app').innerHTML = ` -
-` + --- -const createOrgDiv = document.getElementById('create-organization') + - `afterCreateOrganizationUrl` + - `string` -clerk.openCreateOrganization(createOrgDiv) -``` + Full URL or path to navigate to after creating a new organization. + + --- + + - `routing` + - `'hash' | 'path'` + + The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages. Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. -### `closeCreateOrganization()` + --- -Closes the organization profile overlay. + - `path` + - `string` -```typescript -function closeCreateOrganization(): void -``` + The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash-based routing. For example: `/create-organization`. -#### `closeCreateOrganization()` usage + --- -```js {{ filename: 'main.js', mark: [19] }} -import { Clerk } from '@clerk/clerk-js' + - `skipInvitationScreen` + - `boolean` -// Initialize Clerk with your Clerk Publishable Key -const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + Hides the screen for sending invitations after an organization is created. When left undefined, Clerk will automatically hide the screen if the number of max allowed members is equal to 1 -const clerk = new Clerk(clerkPubKey) -await clerk.load() + --- -document.getElementById('app').innerHTML = ` -
-` + - `hideSlug` + - `boolean` -const createOrgDiv = document.getElementById('create-organization') + Hides the optional slug field in the organization creation screen. -clerk.openCreateOrganization(createOrgDiv) + --- -// ... + - `fallback?` + - `ReactNode` -clerk.closeCreateOrganization(createOrgDiv) -``` + An optional element to be rendered while the component is mounting. + ## Customization diff --git a/docs/reference/components/organization/organization-list.mdx b/docs/reference/components/organization/organization-list.mdx index 5b848eefc6..5320a7169d 100644 --- a/docs/reference/components/organization/organization-list.mdx +++ b/docs/reference/components/organization/organization-list.mdx @@ -8,70 +8,12 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component displays organization-related memberships and automatic [invitations](/docs/guides/organizations/verified-domains#automatic-invitations) and [suggestions](/docs/guides/organizations/verified-domains#automatic-suggestions) for the user. -## Properties - -The `` component accepts the following properties, all of which are **optional**: - - - - `afterCreateOrganizationUrl` - - ((org: [Organization][org-ref]) => string) | string - - The full URL or path to navigate to after creating a new organization. - - --- - - - `afterSelectOrganizationUrl` - - ((org: [Organization][org-ref]) => string) | string - - The full URL or path to navigate to after selecting an organization. Defaults to `undefined`. - - --- - - - `afterSelectPersonalUrl` - - ((org: [Organization][org-ref]) => string) | string - - The full URL or path to navigate to after selecting the [personal account](/docs/guides/organizations/overview#allow-personal-accounts). Defaults to `undefined`. - - --- - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `fallback?` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - --- - - - `hidePersonal` - - `boolean` - - A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. - - --- - - - `hideSlug` - - `boolean` - - A boolean that controls whether the optional slug field in the organization creation screen is hidden. Defaults to `false`. - - --- - - - `skipInvitationScreen` - - `boolean | undefined` - - A boolean that controls whether the screen for sending invitations after an organization is created is hidden. When `undefined`, Clerk will automatically hide the screen if the number of max allowed members is equal to 1. Defaults to `false`. - - -## Usage with frameworks + + ## Example - - + ```jsx {{ filename: 'app/organizations/page.tsx' }} import { OrganizationList } from '@clerk/nextjs' @@ -85,25 +27,21 @@ The `` component accepts the following properties, all of wh ) } ``` - + - - ```jsx {{ filename: 'organizations.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { OrganizationList } from '@clerk/clerk-react' - export default function OrganizationListPage() { - return ( - `/organization/${org.slug}`} - afterSelectPersonalUrl={(user) => `/user/${user.id}`} - afterSelectOrganizationUrl={(org) => `/organization/${org.slug}`} - /> - ) + function App() { + return } + + export default App ``` - + - + ```astro {{ filename: '/pages/organizations.astro' }} --- import { OrganizationList } from '@clerk/astro/components' @@ -115,9 +53,9 @@ The `` component accepts the following properties, all of wh afterSelectOrganizationUrl="/organization/:slug" /> ``` - + - + ```jsx {{ filename: '/app/organizations.web.tsx' }} @@ -133,10 +71,20 @@ The `` component accepts the following properties, all of wh ) } ``` - + + + + ```jsx {{ filename: 'src/routes/organizations.tsx' }} + import { OrganizationList } from '@clerk/chrome-extension' + + export default function OrganizationListPage() { + return + } + ``` + - - ```jsx {{ filename: '/route/organizations.tsx' }} + + ```tsx {{ filename: 'app/routes/organizations.tsx' }} import { OrganizationList } from '@clerk/remix' export default function OrganizationListPage() { @@ -149,9 +97,25 @@ The `` component accepts the following properties, all of wh ) } ``` - + + + + ```tsx {{ filename: 'app/routes/organizations.tsx' }} + import { OrganizationList } from '@clerk/react-router' + + export default function OrganizationListPage() { + return ( + `/organization/${org.slug}`} + afterSelectPersonalUrl={(user) => `/user/${user.id}`} + afterSelectOrganizationUrl={(org) => `/organization/${org.slug}`} + /> + ) + } + ``` + - + ```tsx {{ filename: 'app/routes/organizations.tsx' }} import { OrganizationList } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -170,9 +134,9 @@ The `` component accepts the following properties, all of wh ) } ``` - + - + ```vue {{ filename: 'organizations.vue' }} + + + ``` + + ## Usage with JavaScript @@ -285,6 +265,66 @@ The `` component accepts the following properties, all of wh ``` +## Properties + +The `` component accepts the following properties, all of which are **optional**: + + + - `afterCreateOrganizationUrl` + - ((org: [Organization][org-ref]) => string) | string + + The full URL or path to navigate to after creating a new organization. + + --- + + - `afterSelectOrganizationUrl` + - ((org: [Organization][org-ref]) => string) | string + + The full URL or path to navigate to after selecting an organization. Defaults to `undefined`. + + --- + + - `afterSelectPersonalUrl` + - ((org: [Organization][org-ref]) => string) | string + + The full URL or path to navigate to after selecting the [personal account](/docs/guides/organizations/overview#allow-personal-accounts). Defaults to `undefined`. + + --- + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `fallback?` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + --- + + - `hidePersonal` + - `boolean` + + A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. + + --- + + - `hideSlug` + - `boolean` + + A boolean that controls whether the optional slug field in the organization creation screen is hidden. Defaults to `false`. + + --- + + - `skipInvitationScreen` + - `boolean | undefined` + + A boolean that controls whether the screen for sending invitations after an organization is created is hidden. When `undefined`, Clerk will automatically hide the screen if the number of max allowed members is equal to 1. Defaults to `false`. + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/organization/organization-profile.mdx b/docs/reference/components/organization/organization-profile.mdx index 94599a2b0f..d12519e631 100644 --- a/docs/reference/components/organization/organization-profile.mdx +++ b/docs/reference/components/organization/organization-profile.mdx @@ -14,56 +14,12 @@ The **Members** tab shows the organization's members along with their join dates The **Billing** tab displays the plans and features that are available to the organization, as well as the user's billing information, such as their invoices and payment methods. -## Properties - -The `` component accepts the following properties, all of which are **optional**: - - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `afterLeaveOrganizationUrl` - - `string` - - The full URL or path to navigate to after leaving an organization. - - --- - - - `customPages` - - `CustomPages[]` - - An array of custom pages to add to the organization profile. Only available for the [JavaScript SDK](/docs/reference/javascript/overview). To add custom pages with React-based SDK's, see the [dedicated guide](/docs/guides/customizing-clerk/adding-items/organization-profile). - - --- - - - `fallback?` - - `ReactNode` - - An optional element to be rendered while the component is mounting. + + ## Example - --- - - - `path` - - `string` - - The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash- and virtual-based routing.
For example: `/organization-profile`. - - --- - - - `routing` - - `'hash' | 'path'` - - The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages.
Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. - - -## Usage with frameworks - - - + The `` component must embedded using the [Next.js optional catch-all route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-routes) in order for the routing to work. ```jsx {{ filename: 'app/organization-profile/[[...organization-profile]]/page.tsx' }} @@ -73,19 +29,21 @@ The `` component accepts the following properties, all of return } ``` - + - - ```jsx {{ filename: 'organization-profile.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { OrganizationProfile } from '@clerk/clerk-react' - export default function OrganizationProfilePage() { + function App() { return } + + export default App ``` - + - + ```astro {{ filename: '/pages/organization-profile.astro' }} --- import { OrganizationProfile } from '@clerk/astro/components' @@ -93,9 +51,9 @@ The `` component accepts the following properties, all of ``` - + - + ```jsx {{ filename: '/app/organization-profile.web.tsx' }} @@ -105,24 +63,48 @@ The `` component accepts the following properties, all of return } ``` - + - - ```jsx {{ filename: '/pages/organization-profile/$.tsx' }} - import { OrganizationProfile } from '@clerk/remix' + + ```jsx {{ filename: 'src/routes/organization-profile.tsx' }} + import { OrganizationProfile } from '@clerk/chrome-extension' export default function OrganizationProfilePage() { return } ``` - + - + ```tsx {{ filename: 'app/routes/organization-profile.tsx' }} + import { OrganizationProfile } from '@clerk/remix' + + export default function OrganizationProfilePage() { + return + } + ``` + + + + The `` component must embedded using the [React Router Splat route](https://reactrouter.com/start/framework/routing#splats) in order for the routing to work. + + ```tsx {{ filename: 'app/routes/organization-profile.$.tsx' }} + import { OrganizationProfile } from '@clerk/react-router' + + export default function OrganizationProfilePage() { + return + } + ``` + + + + The `` component must embedded using the [TanStack Router catch-all route](https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts#splat--catch-all-routes) in order for the routing to work. + + ```tsx {{ filename: 'app/routes/organization-profile.$.tsx' }} import { OrganizationProfile } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' - export const Route = createFileRoute('/organization-profile')({ + export const Route = createFileRoute('/organization-profile/$')({ component: OrganizationProfilePage, }) @@ -130,9 +112,9 @@ The `` component accepts the following properties, all of return } ``` - + - + ```vue {{ filename: 'organization-profile.vue' }} + + + ``` + + ## Usage with JavaScript @@ -308,6 +302,52 @@ The `` component accepts the following properties, all of ``` +## Properties + +The `` component accepts the following properties, all of which are **optional**: + + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `afterLeaveOrganizationUrl` + - `string` + + The full URL or path to navigate to after leaving an organization. + + --- + + - `customPages` + - `CustomPages[]` + + An array of custom pages to add to the organization profile. Only available for the [JavaScript SDK](/docs/reference/javascript/overview). To add custom pages with React-based SDK's, see the [dedicated guide](/docs/guides/customizing-clerk/adding-items/organization-profile). + + --- + + - `fallback?` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + --- + + - `path` + - `string` + + The path where the component is mounted on when `routing` is set to `path`. It is ignored in hash- and virtual-based routing.
For example: `/organization-profile`. + + --- + + - `routing` + - `'hash' | 'path'` + + The [routing](/docs/guides/how-clerk-works/routing) strategy for your pages.
Defaults to `'path'` for frameworks that handle routing, such as Next.js and Remix. Defaults to `hash` for all other SDK's, such as React. + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/organization/organization-switcher.mdx b/docs/reference/components/organization/organization-switcher.mdx index a880fa2c6c..b63cd362dd 100644 --- a/docs/reference/components/organization/organization-switcher.mdx +++ b/docs/reference/components/organization/organization-switcher.mdx @@ -8,105 +8,12 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/overview#allow-personal-accounts), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/overview). -## Properties - -The `` component accepts the following properties, all of which are **optional**: - - - - `afterCreateOrganizationUrl` - - `string` - - The full URL or path to navigate to after creating a new organization. - - --- - - - `afterLeaveOrganizationUrl` - - `string` - - The full URL or path to navigate to after the user leaves the currently [active organization](!active-organization). - - --- - - - `afterSelectOrganizationUrl` - - `string` - - The full URL or path to navigate to after a successful organization switch. - - --- - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined - - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `createOrganizationMode` - - `'modal' | 'navigation'` - - A boolean that controls whether clicking the "Create organization" button will cause the [``][createorg-ref] component to open as a modal, or if the browser will navigate to the `createOrganizationUrl` where `` is mounted as a page. Defaults to: `'modal'`. - - --- - - - `createOrganizationUrl` - - `string` - - The full URL or path where the ``][createorg-ref] component is mounted. - - --- - - - `defaultOpen` - - `boolean` - - A boolean that controls the default state of the `` component. - - --- - - - `fallback?` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - --- - - - `hidePersonal` - - `boolean` - - A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. - - --- - - - `hideSlug` - - `boolean` - - A boolean that controls whether the optional slug field in the organization creation screen is hidden. - - --- - - - `organizationProfileMode` - - `'modal' | 'navigation'` - - A boolean that controls whether clicking the **Manage organization** button will cause the [``][orgprofile-ref] component to open as a modal, or if the browser will navigate to the `organizationProfileUrl` where `` is mounted as a page. Defaults to: `'modal'`. - - --- + + ## Example - - `organizationProfileProps` - - `object` - - Specify options for the underlying [``][orgprofile-ref] component. For example: `{appearance: {...}}` - - --- - - - `organizationProfileUrl` - - `string` - - The full URL or path where the [``][orgprofile-ref] component is mounted. - - -## Usage with frameworks - - - + ```jsx {{ filename: 'app/organization-switcher/[[...organization-switcher]]/page.tsx' }} import { OrganizationSwitcher } from '@clerk/nextjs' @@ -114,19 +21,21 @@ The `` component accepts the following properties, all o return } ``` - + - - ```jsx {{ filename: 'organization-switcher.tsx' }} + + ```jsx {{ filename: 'src/App.tsx' }} import { OrganizationSwitcher } from '@clerk/clerk-react' - export default function OrganizationSwitcherPage() { + function App() { return } + + export default App ``` - + - + ```astro {{ filename: '/pages/organization-switcher.astro' }} --- import { OrganizationSwitcher } from '@clerk/astro/components' @@ -134,9 +43,9 @@ The `` component accepts the following properties, all o ``` - + - + ```jsx {{ filename: '/app/organization-switcher.web.tsx' }} @@ -146,19 +55,39 @@ The `` component accepts the following properties, all o return } ``` - + - - ```jsx {{ filename: '/pages/organization-switcher/$.tsx' }} + + ```jsx {{ filename: 'src/routes/organization-switcher.tsx' }} + import { OrganizationSwitcher } from '@clerk/chrome-extension' + + export default function OrganizationSwitcherPage() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/organization-switcher.tsx' }} import { OrganizationSwitcher } from '@clerk/remix' export default function OrganizationSwitcherPage() { return } ``` - + - + + ```tsx {{ filename: 'app/routes/organization-switcher.tsx' }} + import { OrganizationSwitcher } from '@clerk/react-router' + + export default function OrganizationSwitcherPage() { + return + } + ``` + + + ```tsx {{ filename: 'app/routes/organization-switcher.tsx' }} import { OrganizationSwitcher } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -171,9 +100,9 @@ The `` component accepts the following properties, all o return } ``` - + - + ```vue {{ filename: 'organization-switcher.vue' }} + + + ``` + + ## Usage with JavaScript @@ -282,6 +223,101 @@ The `` component accepts the following properties, all o ``` +## Properties + +The `` component accepts the following properties, all of which are **optional**: + + + - `afterCreateOrganizationUrl` + - `string` + + The full URL or path to navigate to after creating a new organization. + + --- + + - `afterLeaveOrganizationUrl` + - `string` + + The full URL or path to navigate to after the user leaves the currently [active organization](!active-organization). + + --- + + - `afterSelectOrganizationUrl` + - `string` + + The full URL or path to navigate to after a successful organization switch. + + --- + + - `appearance` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `createOrganizationMode` + - `'modal' | 'navigation'` + + A boolean that controls whether clicking the "Create organization" button will cause the [``][createorg-ref] component to open as a modal, or if the browser will navigate to the `createOrganizationUrl` where `` is mounted as a page. Defaults to: `'modal'`. + + --- + + - `createOrganizationUrl` + - `string` + + The full URL or path where the ``][createorg-ref] component is mounted. + + --- + + - `defaultOpen` + - `boolean` + + A boolean that controls the default state of the `` component. + + --- + + - `fallback?` + - `ReactNode` + + An optional element to be rendered while the component is mounting. + + --- + + - `hidePersonal` + - `boolean` + + A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. + + --- + + - `hideSlug` + - `boolean` + + A boolean that controls whether the optional slug field in the organization creation screen is hidden. + + --- + + - `organizationProfileMode` + - `'modal' | 'navigation'` + + A boolean that controls whether clicking the **Manage organization** button will cause the [``][orgprofile-ref] component to open as a modal, or if the browser will navigate to the `organizationProfileUrl` where `` is mounted as a page. Defaults to: `'modal'`. + + --- + + - `organizationProfileProps` + - `object` + + Specify options for the underlying [``][orgprofile-ref] component. For example: `{appearance: {...}}` + + --- + + - `organizationProfileUrl` + - `string` + + The full URL or path where the [``][orgprofile-ref] component is mounted. + + ## Customization To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/components/overview.mdx b/docs/reference/components/overview.mdx index ed9e2541af..ca0915fa8e 100644 --- a/docs/reference/components/overview.mdx +++ b/docs/reference/components/overview.mdx @@ -49,9 +49,6 @@ Control components manage authentication-related behaviors in your application. - [``](/docs/reference/components/unstyled/sign-in-with-metamask) - [``](/docs/reference/components/unstyled/sign-up-button) - [``](/docs/reference/components/unstyled/sign-out-button) -- [``](/docs/reference/components/billing/checkout-button) -- [``](/docs/reference/components/billing/plan-details-button) -- [``](/docs/reference/components/billing/subscription-details-button) ## Customization guides diff --git a/docs/reference/components/unstyled/sign-in-button.mdx b/docs/reference/components/unstyled/sign-in-button.mdx index c07fe47271..55b0c26054 100644 --- a/docs/reference/components/unstyled/sign-in-button.mdx +++ b/docs/reference/components/unstyled/sign-in-button.mdx @@ -4,20 +4,281 @@ description: The component is a button that links to the sign-in sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- -The `` component is a button that, by default, links to your app's sign-in page. Your sign-in page will be hosted by Clerk using the [Account Portal](/docs/guides/customizing-clerk/account-portal) unless you have set up a dedicated sign-in page. +The `` component is a button that, by default, links to your app's sign-in page. Your sign-in page will be hosted by Clerk using the [Account Portal](/docs/guides/customizing-clerk/account-portal) unless you have set up a [dedicated sign-in page](/docs/guides/development/custom-sign-in-or-up-page). -{/* TODO: Link to /custom-sign-in-or-up-page when it's no longer specific to /reference/nextjs */} +## Usage -## Properties +### Basic usage - - - `asChild?` - - `boolean` + + ```jsx {{ filename: 'app/page.tsx' }} + import { SignInButton } from '@clerk/nextjs' + + export default function Home() { + return + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignInButton } from '@clerk/clerk-react' + + function App() { + return + } + + export default App + ``` + + + + ```astro {{ filename: 'pages/sign-in.astro' }} + --- + import { SignInButton } from '@clerk/astro/components' + --- + + + ``` + + + + + + ```jsx {{ filename: '/app/sign-in.web.tsx' }} + import { SignInButton } from '@clerk/clerk-expo/web' + + export default function SignInPage() { + return + } + ``` + + + + ```jsx {{ filename: 'src/routes/sign-in.tsx' }} + import { SignInButton } from '@clerk/chrome-extension' + + export default function SignInPage() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignInButton } from '@clerk/remix' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignInButton } from '@clerk/react-router' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} + import { SignInButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/sign-in')({ + component: SignIn, + }) + + function SignIn() { + return + } + ``` + + + + ```vue {{ filename: 'pages/sign-in.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + + +### Custom usage + +You can create a custom button by wrapping your own button, or button text, in the `` component. + + + ```jsx {{ filename: 'pages/index.js' }} + import { SignInButton } from '@clerk/nextjs' - **For Astro only:** If `true`, the `` component will render its children as a child of the component. + export default function Home() { + return ( + + + + ) + } + ``` + + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignInButton } from '@clerk/clerk-react' + + function App() { + return ( + + + + ) + } + + export default App + ``` + + + + You must pass the `asChild` prop to the `` component if you are passing children to it. + + ```astro {{ filename: 'pages/index.astro' }} + --- + import { SignInButton } from '@clerk/astro/components' --- + + + + ``` + + + + + + ```jsx {{ filename: '/app/index.tsx' }} + import { SignInButton } from '@clerk/clerk-expo/web' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignInButton } from '@clerk/chrome-extension' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignInButton } from '@clerk/remix' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignInButton } from '@clerk/react-router' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/sign-in.tsx' }} + import { SignInButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/sign-in')({ + component: SignIn, + }) + + function SignIn() { + return ( + + + + ) + } + ``` + + + + ```vue {{ filename: 'pages/index.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + + +## Properties + + - `forceRedirectUrl?` - `string` @@ -79,179 +340,11 @@ The `` component is a button that, by default, links to your app's The values used to prefill the sign-in fields with. -## Usage - -### Basic usage - - - - ```jsx {{ filename: 'app/page.tsx' }} - import { SignInButton } from '@clerk/nextjs' - - export default function Home() { - return - } - ``` - + + + - `asChild?` + - `boolean` - - ```jsx {{ filename: 'src/sign-in.tsx' }} - import { SignInButton } from '@clerk/clerk-react' - - const SignInPage = () => - - export default SignInPage - ``` - - - - ```astro {{ filename: 'pages/sign-in.astro' }} - --- - import { SignInButton } from '@clerk/astro/components' - --- - - - ``` - - - - - - ```jsx {{ filename: '/app/sign-in.web.tsx' }} - import { SignInButton } from '@clerk/clerk-expo/web' - - export default function SignInPage() { - return - } - ``` - - - - ```jsx {{ filename: 'app/routes/sign-in/$.tsx' }} - import { SignInButton } from '@clerk/remix' - - export default function SignInPage() { - return - } - ``` - - - - ```tsx {{ filename: 'app/routes/sign-in.tsx' }} - import { SignInButton } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' - - export const Route = createFileRoute('/sign-in')({ - component: SignIn, - }) - - function SignIn() { - return - } - ``` - - - - ```vue {{ filename: 'example.vue' }} - - - - ``` - - - -### Custom usage - -You can create a custom button by wrapping your own button, or button text, in the `` component. - - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInButton } from '@clerk/nextjs' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'example.js' }} - import { SignInButton } from '@clerk/clerk-react' - - export default function Example() { - return ( - - - - ) - } - ``` - - - - You must pass the `asChild` prop to the `` component if you are passing children to it. - - ```astro {{ filename: 'pages/index.astro' }} - --- - import { SignInButton } from '@clerk/astro/components' - --- - - - - - ``` - - - - - - ```jsx {{ filename: '/app/index.tsx' }} - import { SignInButton } from '@clerk/clerk-expo/web' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInButton } from '@clerk/remix' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```vue {{ filename: 'example.vue' }} - - - - ``` - - + If `true`, the `` component will render its children as a child of the component. + + diff --git a/docs/reference/components/unstyled/sign-in-with-metamask.mdx b/docs/reference/components/unstyled/sign-in-with-metamask.mdx index 54527bae0d..da218d6662 100644 --- a/docs/reference/components/unstyled/sign-in-with-metamask.mdx +++ b/docs/reference/components/unstyled/sign-in-with-metamask.mdx @@ -1,7 +1,7 @@ --- title: '``' description: The `` component is used to complete a one-click, cryptographically-secure sign-in flow using MetaMask. -sdk: chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue +sdk: expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- The `` component is used to complete a one-click, cryptographically-secure sign-in flow using MetaMask. @@ -10,136 +10,220 @@ The `` component is used to complete a one-click, cryp ### Basic usage - - - ```jsx {{ filename: 'app/page.tsx' }} - import { SignInWithMetamaskButton } from '@clerk/nextjs' - - export default function Home() { - return - } - ``` - - - - ```jsx {{ filename: 'example.js' }} - import { SignInWithMetamaskButton } from '@clerk/clerk-react' - - export default function Example() { - return - } - ``` - - - - - - ```jsx {{ filename: '/app/page.web.tsx' }} - import { SignInWithMetamaskButton } from '@clerk/clerk-expo/web' - - export default function Home() { - return - } - ``` - - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInWithMetamaskButton } from '@clerk/remix' - - export default function Home() { - return - } - ``` - - - - ```vue {{ filename: 'example.vue' }} - - - - ``` - - + + ```jsx {{ filename: 'app/page.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/nextjs' + + export default function Home() { + return + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/clerk-react' + + function App() { + return + } + + export default App + ``` + + + + + + ```jsx {{ filename: '/app/page.web.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/clerk-expo/web' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/remix' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignInWithMetamaskButton } from '@clerk/react-router' + + export default function Home() { + return + } + ``` + + + + ```vue {{ filename: 'pages/sign-in.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + ### Custom usage In some cases, you will want to use your own button, or button text. You can do that by wrapping your button in the `` component. - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInWithMetamaskButton } from '@clerk/nextjs' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'example.js' }} - import { SignInWithMetamaskButton } from '@clerk/clerk-react' - - export default function Example() { - return ( - - - - ) - } - ``` - - - - - - ```jsx {{ filename: '/app/page.web.tsx' }} - import { SignInWithMetamaskButton } from '@clerk/clerk-expo/web' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInWithMetamaskButton } from '@clerk/remix' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```vue {{ filename: 'example.vue' }} - - - - ``` - - + ) + } + ``` + + + + ```vue {{ filename: 'pages/index.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + diff --git a/docs/reference/components/unstyled/sign-out-button.mdx b/docs/reference/components/unstyled/sign-out-button.mdx index 6f962a195c..5003b34d22 100644 --- a/docs/reference/components/unstyled/sign-out-button.mdx +++ b/docs/reference/components/unstyled/sign-out-button.mdx @@ -6,306 +6,481 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta The `` component is a button that signs a user out. By default, it is a ` + + ) + } + ``` + - - - `sessionId?` - - `string` + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignOutButton } from '@clerk/clerk-react' + + function App() { + return ( + + + + ) + } + + export default App + ``` + - The ID of a specific session to sign out of. Useful for multi-session applications. + + You must pass the `asChild` prop to the `` component if you are passing children to it. + ```astro {{ filename: 'pages/index.astro' }} + --- + import { SignOutButton } from '@clerk/astro/components' --- - - `redirectUrl?` - - `string` + + + + ``` + - The full URL or path to navigate after successful sign-out. - + + -## Usage + ```jsx {{ filename: '/app/index.tsx' }} + import { SignOutButton } from '@clerk/clerk-expo/web' -### Basic usage + export default function Home() { + return ( + + + + ) + } + ``` + - - - ```jsx {{ filename: 'app/page.tsx' }} - import { SignOutButton } from '@clerk/nextjs' + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignOutButton } from '@clerk/chrome-extension' - export default function Home() { - return - } - ``` - + export default function Home() { + return ( + + + + ) + } + ``` + - - ```jsx {{ filename: 'src/sign-out.tsx' }} - import { SignOutButton } from '@clerk/clerk-react' + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignOutButton } from '@clerk/remix' - const SignOutPage = () => + export default function Home() { + return ( + + + + ) + } + ``` + - export default SignOutPage - ``` - + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignOutButton } from '@clerk/react-router' - - ```astro {{ filename: 'pages/sign-out.astro' }} - --- - import { SignOutButton } from '@clerk/astro/components' - --- + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```vue {{ filename: 'pages/index.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + - - ``` - + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignOutButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' - - + export const Route = createFileRoute('/')({ + component: Home, + }) - ```jsx {{ filename: '/app/sign-out.web.tsx' }} - import { SignOutButton } from '@clerk/clerk-expo/web' + function Home() { + return ( + + + + ) + } + ``` + - export default function SignOutPage() { - return - } - ``` - +### Multi-session usage - - ```jsx {{ filename: 'app/routes/sign-out.tsx' }} - import { SignOutButton } from '@clerk/remix' +#### Sign out of all sessions - export default function SignOutPage() { - return - } - ``` - +Clicking the `` component signs the user out of all sessions. This is the default behavior. - - ```tsx {{ filename: 'app/routes/sign-out.tsx' }} - import { SignOutButton } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' +#### Sign out of a specific session - export const Route = createFileRoute('/sign-out')({ - component: SignOut, - }) +You can sign out of a specific session by passing in a `sessionId` to the `sessionId` prop. This is useful for signing a single account out of a [multi-session application](/docs/guides/secure/session-options#multi-session-applications). - function SignOut() { - return - } - ``` - - - - ```vue {{ filename: 'sign-out.vue' }} - - - - ``` - - +In the following example, the `sessionId` is retrieved from the [`useAuth()`](/docs/reference/hooks/use-auth) hook. If the user is not signed in, the `sessionId` will be `null`, and the user is shown the [``](/docs/reference/components/unstyled/sign-in-button) component. If the user is signed in, the user is shown the `` component, which when clicked, signs the user out of that specific session. -### Custom usage + + ```tsx {{ filename: 'app/page.tsx' }} + 'use client' -You can create a custom button by wrapping your own button, or button text, in the `` component. + import { SignInButton, SignOutButton, useAuth } from '@clerk/nextjs' - - - ```jsx {{ filename: 'app/page.js' }} - import { SignOutButton } from '@clerk/nextjs' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'example.js' }} - import { SignOutButton } from '@clerk/clerk-react' - - export default function Example() { - return ( - - - - ) + export default function Home() { + const { sessionId } = useAuth() + + if (!sessionId) { + return } - ``` - - - You must pass the `asChild` prop to the `` component if you are passing children to it. + return + } + ``` + - ```astro {{ filename: 'pages/index.astro' }} - --- - import { SignOutButton } from '@clerk/astro/components' - --- + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/clerk-react' - - - - ``` - + function App() { + const { sessionId } = useAuth() + + if (!sessionId) { + return + } - - + return + } - ```jsx {{ filename: '/app/index.tsx' }} - import { SignOutButton } from '@clerk/clerk-expo/web' + export default App + ``` + - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignOutButton } from '@clerk/remix' - - export default function Home() { - return ( - - - - ) + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/remix' + + export default function Home() { + const { sessionId } = useAuth() + + if (!sessionId) { + return } - ``` - - - ```vue {{ filename: 'example.vue' }} - + return + } + ``` + - - ``` - - + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/react-router' -### Multi-session usage + export default function Home() { + const { sessionId } = useAuth() -#### Sign out of all sessions + if (!sessionId) { + return + } -Clicking the `` component signs the user out of all sessions. This is the default behavior. + return + } + ``` + -#### Sign out of a specific session + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/chrome-extension' -You can sign out of a specific session by passing in a `sessionId` to the `signOutOptions` prop. This is useful for signing a single account out of a multi-session (multiple account) application. + export default function Home() { + const { sessionId } = useAuth() -In the following example, the `sessionId` is retrieved from the [`useAuth()`](/docs/reference/hooks/use-auth) hook. If the user is not signed in, the `sessionId` will be `null`, and the user is shown the [``](/docs/reference/components/unstyled/sign-in-button) component. If the user is signed in, the user is shown the `` component, which when clicked, signs the user out of that specific session. + if (!sessionId) { + return + } + + return + } + ``` + + + + ```vue {{ filename: 'pages/index.vue' }} + + + + ``` + + + + ```vue {{ filename: 'example.vue' }} + + + + ``` + + + + ```astro {{ filename: 'pages/index.astro' }} + --- + import { SignInButton, SignOutButton } from '@clerk/astro/components' + import { useAuth } from '@clerk/astro/react' + const { sessionId } = useAuth() + --- - - - ```tsx {{ filename: 'app/page.tsx' }} - 'use client' + {sessionId ? : } + ``` + - import { SignInButton, SignOutButton, useAuth } from '@clerk/nextjs' + + - export default function Home() { - const { sessionId } = useAuth() + ```jsx {{ filename: '/app/index.web.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/clerk-expo/web' - if (!sessionId) { - return - } + export default function Home() { + const { sessionId } = useAuth() - return + if (!sessionId) { + return } - ``` - - - ```jsx {{ filename: 'example.js' }} - import { SignInButton, SignOutButton, useAuth } from '@clerk/clerk-react' + return + } + ``` + - export default function Home() { - const { sessionId } = useAuth() + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignInButton, SignOutButton, useAuth } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' - if (!sessionId) { - return - } + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + const { sessionId } = useAuth() - return + if (!sessionId) { + return } - ``` - - - ```jsx {{ filename: 'pages/index.js' }} - import { SignInButton, SignOutButton, useAuth } from '@clerk/remix' + return + } + ``` + - export default function Home() { - const { sessionId } = useAuth() +## Properties - if (!sessionId) { - return - } + + - `redirectUrl?` + - `string` - return - } - ``` - + The full URL or path to navigate after successful sign-out. - - ```vue {{ filename: 'example.vue' }} - - - - ``` - - + - `sessionId?` + - `string` + + The ID of a specific session to sign out of. Useful for [multi-session applications](/docs/guides/secure/session-options#multi-session-applications). + + --- + + - `children?` + - `React.ReactNode` + + Children you want to wrap the `` in. + + + + + - `asChild?` + - `boolean` + + If `true`, the `` component will render its children as a child of the component. + + diff --git a/docs/reference/components/unstyled/sign-up-button.mdx b/docs/reference/components/unstyled/sign-up-button.mdx index 3ff7cf91e5..fee26d526d 100644 --- a/docs/reference/components/unstyled/sign-up-button.mdx +++ b/docs/reference/components/unstyled/sign-up-button.mdx @@ -4,20 +4,281 @@ description: The component is a button that links to the sign-up sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue --- -The `` component is a button that, by default, links to your app's sign-up page. Your sign-up page will be hosted by Clerk using the [Account Portal](/docs/guides/customizing-clerk/account-portal) unless you have set up a dedicated sign-up page. +The `` component is a button that, by default, links to your app's sign-up page. Your sign-up page will be hosted by Clerk using the [Account Portal](/docs/guides/customizing-clerk/account-portal) unless you have set up a [dedicated sign-up page](/docs/guides/development/custom-sign-in-or-up-page). -{/* TODO: Link to /custom-sign-in-or-up-page when it's no longer specific to /reference/nextjs */} +## Usage -## Properties +### Basic usage - - - `asChild?` - - `boolean` + + ```jsx {{ filename: 'app/page.tsx' }} + import { SignUpButton } from '@clerk/nextjs' + + export default function Home() { + return + } + ``` + + + + ```jsx {{ filename: 'src/App.tsx' }} + import { SignUpButton } from '@clerk/clerk-react' + + function App() { + return + } + + export default App + ``` + + + + ```astro {{ filename: 'pages/sign-up.astro' }} + --- + import { SignUpButton } from '@clerk/astro/components' + --- + + + ``` + + + + + + ```jsx {{ filename: '/app/sign-up.web.tsx' }} + import { SignUpButton } from '@clerk/clerk-expo/web' + + export default function SignUpPage() { + return + } + ``` + + + + ```jsx {{ filename: 'src/routes/sign-up.tsx' }} + import { SignUpButton } from '@clerk/chrome-extension' + + export default function SignUpPage() { + return + } + ``` + + + + ```jsx {{ filename: 'src/routes/_index.tsx' }} + import { SignUpButton } from '@clerk/remix' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignUpButton } from '@clerk/react-router' + + export default function Home() { + return + } + ``` + + + + ```tsx {{ filename: 'app/routes/sign-up.tsx' }} + import { SignUpButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/sign-up')({ + component: SignUp, + }) + + function SignUp() { + return + } + ``` + + + + ```vue {{ filename: 'pages/sign-up.vue' }} + + + + ``` + + + + ```vue {{ filename: 'src/App.vue' }} + + + + ``` + + +### Custom usage + +You can create a custom button by wrapping your own button, or button text, in the `` component. + + + ```jsx {{ filename: 'app/page.tsx' }} + import { SignUpButton } from '@clerk/nextjs' + + export default function Home() { + return ( + + + + ) + } + ``` + - **For Astro only:** If `true`, the `` component will render its children as a child of the component. + + ```jsx {{ filename: 'src/App.jsx' }} + import { SignUpButton } from '@clerk/clerk-react' + function App() { + return ( + + + + ) + } + + export default App + ``` + + + + You must pass the `asChild` prop to the `` component if you are passing children to it. + + ```astro {{ filename: 'src/pages/index.astro' }} --- + import { SignUpButton } from '@clerk/astro/components' + --- + + + + + ``` + + + + + + ```jsx {{ filename: '/app/index.tsx' }} + import { SignUpButton } from '@clerk/clerk-expo/web' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```jsx {{ filename: 'src/routes/home.tsx' }} + import { SignUpButton } from '@clerk/chrome-extension' + + export default function Home() { + return ( + + + + ) + } + ``` + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignUpButton } from '@clerk/remix' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignUpButton } from '@clerk/react-router' + + export default function Home() { + return ( + + + + ) + } + ``` + + + + ```vue {{ filename: 'pages/index.vue' }} + + + + ``` + + + + ```vue {{ filename: 'src/App.vue' }} + + + + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignUpButton } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( + + + + ) + } + ``` + + +## Properties + + - `forceRedirectUrl?` - `string` @@ -86,179 +347,11 @@ The `` component is a button that, by default, links to your app's Metadata that can be read and set from the frontend and the backend. Once the sign-up is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the sign-up process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). -## Usage - -### Basic usage - - - - ```jsx {{ filename: 'app/page.tsx' }} - import { SignUpButton } from '@clerk/nextjs' - - export default function Home() { - return - } - ``` - + + + - `asChild?` + - `boolean` - - ```jsx {{ filename: 'src/sign-up.tsx' }} - import { SignUpButton } from '@clerk/clerk-react' - - const SignUpPage = () => - - export default SignUpPage - ``` - - - - ```astro {{ filename: 'pages/sign-up.astro' }} - --- - import { SignUpButton } from '@clerk/astro/components' - --- - - - ``` - - - - - - ```jsx {{ filename: '/app/sign-up.web.tsx' }} - import { SignUpButton } from '@clerk/clerk-expo/web' - - export default function SignUpPage() { - return - } - ``` - - - - ```jsx {{ filename: 'app/routes/sign-up/$.tsx' }} - import { SignUpButton } from '@clerk/remix' - - export default function SignUpPage() { - return - } - ``` - - - - ```tsx {{ filename: 'app/routes/sign-up.tsx' }} - import { SignUpButton } from '@clerk/tanstack-react-start' - import { createFileRoute } from '@tanstack/react-router' - - export const Route = createFileRoute('/sign-up')({ - component: SignUp, - }) - - function SignUp() { - return - } - ``` - - - - ```vue {{ filename: 'src/App.vue' }} - - - - ``` - - - -### Custom usage - -You can create a custom button by wrapping your own button, or button text, in the `` component. - - - - ```jsx {{ filename: 'app/page.tsx' }} - import { SignUpButton } from '@clerk/nextjs' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'src/App.jsx' }} - import { SignUpButton } from '@clerk/clerk-react' - - export default function Example() { - return ( - - - - ) - } - ``` - - - - You must pass the `asChild` prop to the `` component if you are passing children to it. - - ```astro {{ filename: 'src/pages/index.astro' }} - --- - import { SignUpButton } from '@clerk/astro/components' - --- - - - - - ``` - - - - - - ```jsx {{ filename: '/app/index.tsx' }} - import { SignUpButton } from '@clerk/clerk-expo/web' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```jsx {{ filename: 'app/routes/_index.tsx' }} - import { SignUpButton } from '@clerk/remix' - - export default function Home() { - return ( - - - - ) - } - ``` - - - - ```vue {{ filename: 'src/App.vue' }} - - - - ``` - - + If `true`, the `` component will render its children as a child of the component. + + diff --git a/docs/reference/components/user/user-button.mdx b/docs/reference/components/user/user-button.mdx index 21d034a1e4..01ee6c795b 100644 --- a/docs/reference/components/user/user-button.mdx +++ b/docs/reference/components/user/user-button.mdx @@ -12,93 +12,14 @@ The `` component renders the familiar user button UI popularized b For users that have [multi-session](/docs/guides/secure/session-options#multi-session-applications) enabled, the `` also allows users to sign into multiple accounts at once and instantly switch between them without the need for a full page reload. Learn more [here](/docs/guides/secure/session-options#multi-session-applications). -## Properties - -The `` component accepts the following properties, all of which are **optional**: - - - - `afterMultiSessionSingleSignOutUrl` (deprecated) - - `string` - - **Deprecated. Move `afterMultiSessionSingleSignOutUrl` to [``](/docs/reference/components/clerk-provider).** The full URL or path to navigate to after signing out from a currently active account in a multi-session app. - - --- - - - `afterSignOutUrl` (deprecated) - - `string` + + ## Example - **Deprecated. Move `afterSignOutUrl` to [``](/docs/reference/components/clerk-provider).** The full URL or path to navigate to after a successful sign-out. - - --- - - - `afterSwitchSessionUrl` - - `string` - - The full URL or path to navigate to after a successful account change in a multi-session app. - - --- - - - `appearance` - - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + In the following example, `` is mounted inside a header component, which is a common pattern on many websites and applications. When the user is signed in, they will see their avatar and be able to open the popup menu. - Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. - - --- - - - `defaultOpen` - - `boolean` - - Controls whether the `` should open by default during the first render. - - --- - - - `showName` - - `boolean` - - Controls if the user name is displayed next to the user image button. - - --- - - - `signInUrl` - - `string` - - The full URL or path to navigate to when the **Add another account** button is clicked. It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. - - --- - - - `userProfileMode` - - `'modal' | 'navigation'` - - Controls whether selecting the **Manage your account** button will cause the [``](/docs/reference/components/user/user-profile) component to open as a modal, or if the browser will navigate to the `userProfileUrl` where `` is mounted as a page. Defaults to: `'modal'`. - - --- - - - `userProfileProps` - - `object` - - Specify options for the underlying [``](/docs/reference/components/user/user-profile) component. For example: `{additionalOAuthScopes: {google: ['foo', 'bar'], github: ['qux']}}`. - - --- - - - `userProfileUrl` - - `string` - - The full URL or path leading to the user management interface. - - --- - - - `fallback?` - - `ReactNode` - - An optional element to be rendered while the component is mounting. - - -## Usage with frameworks - -In the following example, `` is mounted inside a header component, which is a common pattern on many websites and applications. When the user is signed in, they will see their avatar and be able to open the popup menu. - - - + ```tsx {{ filename: 'layout.tsx', mark: [8] }} import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs' @@ -129,8 +50,9 @@ In the following example, `` is mounted inside a header component, } ``` - ```jsx {{ filename: 'userButtonExample.tsx', mark: [8] }} + ```tsx {{ filename: 'pages/_app.tsx', mark: [9] }} import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs' + import type { AppProps } from 'next/app' function Header() { return ( @@ -146,10 +68,11 @@ In the following example, `` is mounted inside a header component, ) } - function MyApp({ pageProps }) { + function MyApp({ pageProps, Component }: AppProps) { return (
+ ) } @@ -157,13 +80,13 @@ In the following example, `` is mounted inside a header component, export default MyApp ``` - + - + ```tsx {{ filename: 'src/App.tsx' }} import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/clerk-react' - export default function App() { + function App() { return (
@@ -175,10 +98,12 @@ In the following example, `` is mounted inside a header component,
) } + + export default App ``` - + - + ```astro {{ filename: 'pages/index.astro' }} --- import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/astro/components' @@ -191,9 +116,9 @@ In the following example, `` is mounted inside a header component, ``` - + - + ```jsx {{ filename: '/app/user-button.web.tsx' }} @@ -212,29 +137,51 @@ In the following example, `` is mounted inside a header component, ) } ``` - + - - ```tsx {{ filename: 'router/index.tsx' }} - import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/remix' - import { getAuth } from '@clerk/remix/ssr.server' - import { LoaderFunction, redirect } from '@remix-run/node' + + ```jsx {{ filename: 'src/layouts/root-layout.tsx' }} + import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/chrome-extension' - export const loader: LoaderFunction = async (args) => { - const { isAuthenticated, userId } = await getAuth(args) + export default function Header() { + return ( +
+ + + + + + +
+ ) + } + ``` + - if (!isAuthenticated) { - return redirect('/sign-in') - } + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/remix' - return { - props: { - userId, - }, - } + export default function Index() { + return ( +
+ + + + + + +
+ ) } + ``` + - export default function Index() { + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/react-router' + + export default function Home() { return (
@@ -247,9 +194,9 @@ In the following example, `` is mounted inside a header component, ) } ``` - + - + ```tsx {{ filename: 'app/routes/index.tsx' }} import { SignedIn, UserButton, SignInButton, SignedOut } from '@clerk/tanstack-react-start' import { createFileRoute } from '@tanstack/react-router' @@ -271,9 +218,29 @@ In the following example, `` is mounted inside a header component, ) } ``` - + + + + ```vue {{ filename: 'components/AppHeader.vue' }} + + + + ``` + - + ```vue {{ filename: 'header.vue' }} + + + ``` + - + ```vue {{ filename: 'user.vue' }}