diff --git a/docs/authentication/configuration/restrictions.mdx b/docs/authentication/configuration/restrictions.mdx index 8035fb197e..2d450ee4d1 100644 --- a/docs/authentication/configuration/restrictions.mdx +++ b/docs/authentication/configuration/restrictions.mdx @@ -16,6 +16,7 @@ To configure sign-up modes: 1. Under the **Sign-up modes** section, you can enable one of the following options: - **[Public](#public)** - **[Restricted](#restricted)** + - **[Waitlist](#waitlist)** ### Public @@ -31,6 +32,23 @@ Additional features available in **Restricted** mode: - The [``](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up. +### Waitlist + +> [!NOTE] +> If you're using Next.js, the`` component is available in `@clerk/nextjs@6.2.0` and above. + +In **Waitlist** mode, users can register their interest in your app by joining a waitlist. This mode is ideal for apps in early development stages or those wanting to generate interest before launch. + +Additional features available in **Waitlist** mode: + +- The [``](/docs/components/authentication/sign-in) component will only be accessible to users who have been approved from the waitlist. + +- The [``](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up. + +- The [``](/docs/components/waitlist/overview) component provides a form where users can submit their details to join the waitlist. Once approved by admins, users will receive an email with access instructions. + +- If you're using the `` component, you must provide the `waitlistUrl` prop either in the [``](/docs/components/clerk-provider#properties) or [``](docs/components/authentication/sign-in#properties) component to ensure proper functionality. + ## Allowlist > [!NOTE] diff --git a/docs/components/authentication/sign-in.mdx b/docs/components/authentication/sign-in.mdx index 6b54a98f87..c4de1f4d13 100644 --- a/docs/components/authentication/sign-in.mdx +++ b/docs/components/authentication/sign-in.mdx @@ -82,6 +82,13 @@ All props are optional. - `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. See [OAuth account transfer flows](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) for more information. + + --- + + - `waitlistUrl?` + - `string` + + Full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist). ## Usage with frameworks diff --git a/docs/components/clerk-provider.mdx b/docs/components/clerk-provider.mdx index ecd5a10ecc..c78cf2ec21 100644 --- a/docs/components/clerk-provider.mdx +++ b/docs/components/clerk-provider.mdx @@ -269,6 +269,13 @@ The `` component must be added to your React entrypoint. - `boolean` (For Next.js only) Indicates whether or not Clerk should make dynamic auth data available based on the current request. Defaults to `false`. Opts the application into dynamic rendering when `true`. For more information, see [Next.js rendering modes and Clerk](/docs/references/nextjs/rendering-modes). + + --- + + - `waitlistUrl?` + - `string` + + Full URL or path to the waitlist page. If `undefined`, will redirect to the [Account Portal waitlist page](/docs/customization/account-portal/overview#waitlist). [components-ref]: /docs/components/overview diff --git a/docs/components/waitlist/overview.mdx b/docs/components/waitlist/overview.mdx new file mode 100644 index 0000000000..6a1e602311 --- /dev/null +++ b/docs/components/waitlist/overview.mdx @@ -0,0 +1,223 @@ +--- +title: '`` component' +description: The component renders a waitlist form that allows users to join for early access to your application. +--- + +![The \ component renders a form that allows users to join for early access to your app.](/docs/images/ui-components/waitlist.svg) + +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. + +## Properties + +All props are optional. + + + - `appearance` + - [Appearance](/docs/customization/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + + --- + + - `afterJoinWaitlistUrl` + - `string` + + Full URL or path to navigate to after joining the waitlist. + + --- + + - `signInUrl` + - `string` + + Full URL or path to the sign in page. Use this property to provide the target of the 'Sign In' link that's rendered. It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + + +## 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. + + + + ```jsx {{ filename: '/app/waitlist/[[...waitlist]]/page.tsx' }} + import { Waitlist } from '@clerk/nextjs' + + export default function WaitlistPage() { + return + } + ``` + + + + ```jsx {{ filename: '/waitlist.tsx' }} + import { Waitlist } from '@clerk/clerk-react' + + export default function WaitlistPage() { + return + } + ``` + + + +## Usage with JavaScript + +The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk/clerk) class are used to render and control the `` component: + +- [`mountWaitlist()`](#mount-waitlist) +- [`unmountWaitlist()`](#unmount-waitlist) +- [`openWaitlist()`](#open-waitlist) +- [`closeWaitlist()`](#close-waitlist) + +The following examples assume that you followed the [quickstart](/docs/quickstarts/javascript) to add Clerk to your JavaScript app. + +### mountWaitlist() + +Render the `` component to an HTML `
` element. + +```typescript +function mountWaitlist(node: HTMLDivElement, props?: WaitlistProps): void +``` + +### mountWaitlist() params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The `
` element used to render in the `` component + + --- + + - `props?` + - [`WaitlistProps`](#properties) + + The properties to pass to the `` component + + +#### `mountWaitlist()` usage + +```js {{ filename: 'main.js', mark: [13] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk publishable key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.mountWaitlist(waitlistDiv) +``` + +### unmountWaitlist() + +Unmount and run cleanup on an existing `` component instance. + +```typescript +function unmountWaitlist(node: HTMLDivElement): void +``` + +#### `unmountWaitlist()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The container `
` element with a rendered `` component instance + + +#### `unmountWaitlist()` usage + +```js {{ filename: 'main.js', mark: [17] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk publishable key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.mountWaitlist(waitlistDiv) + +// ... + +clerk.unmountWaitlist(waitlistDiv) +``` + +### `openWaitlist()` + +Opens the `` component as an overlay at the root of your HTML `body` element. + +```typescript +function openWaitlist(props?: WaitlistProps): void +``` + +#### `openWaitlist()` params + + + - `props?` + - [`WaitlistProps`](#properties) + + The properties to pass to the `` component + + +#### `openWaitlist()` usage + +```js {{ filename: 'main.js', mark: [13] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk publishable key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.openWaitlist(waitlistDiv) +``` + +### `closeWaitlist()` + +Closes the waitlist overlay. + +```typescript +function closeWaitlist(): void +``` + +#### `closeWaitlist()` usage + +```js {{ filename: 'main.js', mark: [17] }} +import { Clerk } from '@clerk/clerk-js' + +// Initialize Clerk with your Clerk publishable key +const clerk = new Clerk('{{pub_key}}') +await clerk.load() + +document.getElementById('app').innerHTML = ` +
+` + +const waitlistDiv = document.getElementById('waitlist') + +clerk.openWaitlist(waitlistDiv) + +// ... + +clerk.closeWaitlist(waitlistDiv) +``` + +## Customization + +To learn about how to customize Clerk components, see the [customization guide](/docs/customization/overview). diff --git a/docs/customization/account-portal/overview.mdx b/docs/customization/account-portal/overview.mdx index 5b34a3f3a7..775616dc7c 100644 --- a/docs/customization/account-portal/overview.mdx +++ b/docs/customization/account-portal/overview.mdx @@ -67,3 +67,9 @@ The user profile page hosts the prebuilt [``](/docs/compo ![The Account Portal organization profile page hosts the \ component](/docs/images/account-portal/org-profile.png) Redirect your authenticated users to their organization profile page using the [``](/docs/components/control/redirect-to-organizationprofile) control component. + +### Waitlist + +The waitlist page hosts the prebuilt [``](/docs/components/waitlist/overview) component which renders a form that allows users to join for early access to your app. + +![The Account Portal waitliste page hosts the \ component](/docs/images/account-portal/waitlist.png) diff --git a/docs/manifest.json b/docs/manifest.json index b57462e7e5..b87c791702 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -219,6 +219,18 @@ ] ] }, + { + "title": "Waitlist Component", + "items": [ + [ + { + "title": "``", + "wrap": false, + "href": "/docs/components/waitlist/overview" + } + ] + ] + }, { "title": "Control Components", "items": [ @@ -1877,6 +1889,10 @@ "title": "Organization methods", "href": "/docs/references/javascript/clerk/organization-methods" }, + { + "title": "Waitlist methods", + "href": "/docs/references/javascript/clerk/waitlist-methods" + }, { "title": "Redirect methods", "href": "/docs/references/javascript/clerk/redirect-methods" diff --git a/docs/references/javascript/clerk/clerk.mdx b/docs/references/javascript/clerk/clerk.mdx index 32ef63e9e3..15c55a3892 100644 --- a/docs/references/javascript/clerk/clerk.mdx +++ b/docs/references/javascript/clerk/clerk.mdx @@ -518,6 +518,13 @@ The `Clerk` class also contains a number of methods for interacting with prebuil - [`mountOrganizationList`](/docs/components/organization/organization-list#mount-organization-list) - [`unmountOrganizationList`](/docs/components/organization/organization-list#unmount-organization-list) +### `` + +- [`mountWaitlist()`](/docs/components/waitlist/overview#mount-waitlist) +- [`unmountWaitlist()`](/docs/components/waitlist/overview#unmount-waitlist) +- [`openWaitlist()`](/docs/components/waitlist/overview#open-waitlist) +- [`closeWaitlist()`](/docs/components/waitlist/overview#close-waitlist) + ## Additional methods In addition to the methods listed above, the `Clerk` class also has the following methods: @@ -527,6 +534,10 @@ In addition to the methods listed above, the `Clerk` class also has the followin - [`getOrganization()`](/docs/references/javascript/clerk/organization-methods#get-organization) - [`createOrganization()`](/docs/references/javascript/clerk/organization-methods#create-organization) +### Waitlist + +- [`joinWaitlist()`](/docs/references/javascript/clerk/waitlist-methods#join-waitlist) + ### Redirect - [`navigate()`](/docs/references/javascript/clerk/redirect-methods#navigate) diff --git a/docs/references/javascript/clerk/waitlist-methods.mdx b/docs/references/javascript/clerk/waitlist-methods.mdx new file mode 100644 index 0000000000..c851ed2de4 --- /dev/null +++ b/docs/references/javascript/clerk/waitlist-methods.mdx @@ -0,0 +1,65 @@ +--- +title: Waitlist methods +description: Explore methods on the Clerk class that allow you to add users to your waitlist. +--- + +These methods on the [`Clerk`](/docs/references/javascript/clerk/clerk) class allow you to add users to your [waitlist](/docs/authentication/configuration/restrictions#waitlist). + +The following example assumes: + +- You followed the [quickstart](/docs/quickstarts/javascript) to add Clerk to your JavaScript app. +- You set your sign-up mode to [**Waitlist**](docs/authentication/configuration/restrictions#waitlist). + +## `joinWaitlist()` + +Create a new waitlist entry programatically. + +```typescript +function joinWaitlist({ emailAddress }: JoinWaitlistParams): Promise +``` + +### Parameters + + + - `emailAddress` + - `string` + + The email address of the user you want to add in the waitlist. + + +### Example + + + ```js {{ filename: 'main.js', mark: [[9, 12]] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk publishable key + const clerk = new Clerk('{{pub_key}}') + await clerk.load() + + const joinWaitlistButton = document.getElementById('join-waitlist-button') + joinWaitlistButton.addEventListener('click', () => { + clerk + .joinWaitlist({ emailAddress: 'user@example.com' }) + .then((res) => console.log(res)) + .catch((error) => console.log('An error occurred:', error.errors)) + }) + ``` + + ```html {{ filename: 'index.html' }} + + + + + + + Clerk + JavaScript App + + +
+ + + + + ``` + diff --git a/public/images/account-portal/waitlist.png b/public/images/account-portal/waitlist.png new file mode 100644 index 0000000000..69b7c5e762 Binary files /dev/null and b/public/images/account-portal/waitlist.png differ diff --git a/public/images/ui-components/waitlist.svg b/public/images/ui-components/waitlist.svg new file mode 100644 index 0000000000..37725f31a4 --- /dev/null +++ b/public/images/ui-components/waitlist.svg @@ -0,0 +1,130 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +