feat: Introduce Waitlist component docs (#1696)

Co-authored-by: Alexis Aguilar <[email protected]>
Co-authored-by: victoria <[email protected]>

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 [`<SignUp />`](/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`<Waitlist />` component is available in `@clerk/[email protected]` 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 [`<SignIn />`](/docs/components/authentication/sign-in) component will only be accessible to users who have been approved from the waitlist.
+
+- The [`<SignUp />`](/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 [`<Waitlist />`](/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 `<Waitlist />` component, you must provide the `waitlistUrl` prop either in the [`<ClerkProvider>`](/docs/components/clerk-provider#properties) or [`<SignIn />`](docs/components/authentication/sign-in#properties) component to ensure proper functionality.
+
 ## Allowlist
 
 > [!NOTE]

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).
 </Properties>
 
 ## Usage with frameworks

docs/components/clerk-provider.mdx

@@ -269,6 +269,13 @@ The `<ClerkProvider>` 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).
 </Properties>
 
 [components-ref]: /docs/components/overview

docs/components/waitlist/overview.mdx

@@ -0,0 +1,223 @@
+---
+title: '`<Waitlist />` component'
+description: The <Waitlist /> component renders a waitlist form that allows users to join for early access to your application.
+---
+
+![The \<Waitlist /> component renders a form that allows users to join for early access to your app.](/docs/images/ui-components/waitlist.svg)
+
+The `<Waitlist />` component renders a form that allows users to join for early access to your app.
+
+> [!NOTE]
+> If you're using Next.js, the`<Waitlist />` component is available in `@clerk/[email protected]` and above.
+
+## Properties
+
+All props are optional.
+
+<Properties>
+  - `appearance`
+  - <code>[Appearance](/docs/customization/overview) | undefined</code>
+
+  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.
+</Properties>
+
+## Usage with frameworks
+
+The following example includes a basic implementation of the `<Waitlist />` component. You can use this as a starting point for your own implementation.
+
+<Tabs items={["Next.js", "React"]}>
+  <Tab>
+    ```jsx {{ filename: '/app/waitlist/[[...waitlist]]/page.tsx' }}
+    import { Waitlist } from '@clerk/nextjs'
+
+    export default function WaitlistPage() {
+      return <Waitlist />
+    }
+    ```
+  </Tab>
+
+  <Tab>
+    ```jsx {{ filename: '/waitlist.tsx' }}
+    import { Waitlist } from '@clerk/clerk-react'
+
+    export default function WaitlistPage() {
+      return <Waitlist />
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## 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 `<Waitlist />` 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.
+
+### <code>mount<wbr />Waitlist()</code>
+
+Render the `<Waitlist />` component to an HTML `<div>` element.
+
+```typescript
+function mountWaitlist(node: HTMLDivElement, props?: WaitlistProps): void
+```
+
+### <code>mount<wbr />Waitlist()</code> params
+
+<Properties>
+  - `node`
+  - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+  The `<div>` element used to render in the `<Waitlist />` component
+
+  ---
+
+  - `props?`
+  - [`WaitlistProps`](#properties)
+
+  The properties to pass to the `<Waitlist />` component
+</Properties>
+
+#### `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 = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.mountWaitlist(waitlistDiv)
+```
+
+### <code>unmount<wbr />Waitlist()</code>
+
+Unmount and run cleanup on an existing `<Waitlist />` component instance.
+
+```typescript
+function unmountWaitlist(node: HTMLDivElement): void
+```
+
+#### `unmountWaitlist()` params
+
+<Properties>
+  - `node`
+  - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+  The container `<div>` element with a rendered `<Waitlist />` component instance
+</Properties>
+
+#### `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 = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.mountWaitlist(waitlistDiv)
+
+// ...
+
+clerk.unmountWaitlist(waitlistDiv)
+```
+
+### `openWaitlist()`
+
+Opens the `<Waitlist />` component as an overlay at the root of your HTML `body` element.
+
+```typescript
+function openWaitlist(props?: WaitlistProps): void
+```
+
+#### `openWaitlist()` params
+
+<Properties>
+  - `props?`
+  - [`WaitlistProps`](#properties)
+
+  The properties to pass to the `<Waitlist />` component
+</Properties>
+
+#### `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 = `
+  <div id="waitlist"></div>
+`
+
+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 = `
+  <div id="waitlist"></div>
+`
+
+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).

docs/customization/account-portal/overview.mdx

@@ -67,3 +67,9 @@ The user profile page hosts the prebuilt [`<OrganizationProfile />`](/docs/compo
 ![The Account Portal organization profile page hosts the \<OrganizationProfile /> component](/docs/images/account-portal/org-profile.png)
 
 Redirect your authenticated users to their organization profile page using the [`<RedirectToOrganizationProfile />`](/docs/components/control/redirect-to-organizationprofile) control component.
+
+### Waitlist
+
+The waitlist page hosts the prebuilt [`<Waitlist />`](/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 \<Waitlist /> component](/docs/images/account-portal/waitlist.png)

docs/manifest.json

@@ -219,6 +219,18 @@
                 ]
               ]
             },
+            {
+              "title": "Waitlist Component",
+              "items": [
+                [
+                  {
+                    "title": "`<Waitlist />`",
+                    "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"

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)
 
+### `<Waitlist />`
+
+- [`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)