Document useWaitlist()

docs/manifest.json

@@ -1658,6 +1658,10 @@
                           "title": "`SignUpFuture`",
                           "href": "/docs/reference/javascript/sign-up-future"
                         },
+                        {
+                          "title": "`WaitlistFuture`",
+                          "href": "/docs/reference/javascript/waitlist-future"
+                        },
                         {
                           "title": "`Organization`",
                           "href": "/docs/reference/javascript/organization"
@@ -2945,6 +2949,10 @@
                           "title": "`useSignUp()`",
                           "href": "/docs/reference/hooks/use-sign-up"
                         },
+                        {
+                          "title": "`useWaitlist()`",
+                          "href": "/docs/reference/hooks/use-waitlist"
+                        },
                         {
                           "title": "`useSession()`",
                           "href": "/docs/reference/hooks/use-session"

docs/reference/hooks/use-waitlist.mdx

@@ -0,0 +1,82 @@
+---
+title: useWaitlist()
+description: Access and manage the waitlist state in your React application with Clerk's useWaitlist() hook.
+sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+---
+
+The `useWaitlist()` hook provides access to the [`WaitlistFuture`](/docs/reference/javascript/waitlist-future) object, which allows you to build custom waitlist UIs with reactive state management. This hook is ideal for creating custom waitlist experiences when your app is in [**Waitlist** mode](/docs/guides/secure/restricting-access#waitlist).
+
+## Returns
+
+<Properties>
+  - `waitlist`
+  - [`WaitlistFuture`](/docs/reference/javascript/waitlist-future)
+
+  The current active `WaitlistFuture` instance, for use in custom flows.
+
+  ---
+
+  - `errors`
+  - `Errors`
+
+  The errors that occurred during the last API request.
+
+  ---
+
+  - `fetchStatus`
+  - `'idle' | 'fetching'`
+
+  The fetch status of the underlying `WaitlistFuture` resource.
+</Properties>
+
+## Example
+
+The following example demonstrates how to use the `useWaitlist()` hook to create a custom waitlist form. Users can submit their email address to join the waitlist, and the component displays appropriate feedback based on the submission state.
+
+```tsx {{ filename: 'app/waitlist/page.tsx' }}
+'use client'
+
+import { useWaitlist } from '@clerk/react'
+import { useState } from 'react'
+
+export default function WaitlistPage() {
+  const { waitlist, errors, fetchStatus } = useWaitlist()
+  const [emailAddress, setEmailAddress] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    await waitlist.join({ emailAddress })
+  }
+
+  if (waitlist.id) {
+    return (
+      <div>
+        <h1>Successfully joined the waitlist!</h1>
+        <p>We'll notify you when you're approved.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div>
+      <h1>Join the Waitlist</h1>
+      <form onSubmit={handleSubmit}>
+        <label htmlFor="email">Email address</label>
+        <input
+          id="email"
+          type="email"
+          value={emailAddress}
+          onChange={(e) => setEmailAddress(e.target.value)}
+          required
+        />
+        {errors.fields.emailAddress && (
+          <p>{errors.fields.emailAddress.longMessage}</p>
+        )}
+        <button type="submit" disabled={fetchStatus === 'fetching'}>
+          {fetchStatus === 'fetching' ? 'Submitting...' : 'Join Waitlist'}
+        </button>
+      </form>
+    </div>
+  )
+}
+```

docs/reference/javascript/waitlist-future.mdx

@@ -0,0 +1,82 @@
+---
+title: '`WaitlistFuture`'
+description: The current active `Waitlist` instance, for use in custom flows.
+sdk: js-frontend
+---
+
+<Include src="_partials/custom-flows/future-api-callout" />
+
+The `WaitlistFuture` class provides methods and properties to manage waitlist entries in your application. It is used when you want to build a custom waitlist UI instead of using the prebuilt [`<Waitlist />`](/docs/reference/components/authentication/waitlist) component.
+
+## Properties
+
+<Properties>
+  - `id`
+  - `string | undefined`
+
+  The unique identifier for the waitlist entry. `undefined` if the user has not joined the waitlist yet.
+
+  ---
+
+  - `createdAt`
+  - `Date | null`
+
+  The date and time the waitlist entry was created. `null` if the user has not joined the waitlist yet.
+
+  ---
+
+  - `updatedAt`
+  - `Date | null`
+
+  The date and time the waitlist entry was last updated. `null` if the user has not joined the waitlist yet.
+</Properties>
+
+## Methods
+
+### `join()`
+
+Submits an email address to join the waitlist. This method creates a new waitlist entry for the provided email address.
+
+```ts
+function join(params: JoinWaitlistParams): Promise<{ error: unknown }>
+```
+
+#### `JoinWaitlistParams`
+
+<Properties>
+  - `emailAddress`
+  - `string`
+
+  The email address to add to the waitlist.
+</Properties>
+
+#### Example
+
+```tsx {{ filename: 'app/waitlist/page.tsx' }}
+'use client'
+
+import { useWaitlist } from '@clerk/react'
+
+export default function WaitlistPage() {
+  const { waitlist } = useWaitlist()
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const formData = new FormData(e.currentTarget)
+    const emailAddress = formData.get('emailAddress') as string
+
+    const { error } = await waitlist.join({ emailAddress })
+
+    if (error) {
+      console.error('Failed to join waitlist:', error)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" name="emailAddress" required />
+      <button type="submit">Join Waitlist</button>
+    </form>
+  )
+}
+```