diff --git a/docs/_partials/billing/add-new-payment-method.mdx b/docs/_partials/billing/add-new-payment-method.mdx
index 80e5bde2f6..ca4d52d839 100644
--- a/docs/_partials/billing/add-new-payment-method.mdx
+++ b/docs/_partials/billing/add-new-payment-method.mdx
@@ -3,80 +3,161 @@ The following example demonstrates how to create a billing page where a user can
- **``**: Sets up the ``, which specifies that the payment actions within its children are `for` the `user`.
- **``**: Renders the payment form and handles the submission logic. It uses `usePaymentElement()` to get the `submit` function and `useUser()` to get the `user` object. When the form is submitted, it first creates a payment token and then attaches it to the user.
-", ""]}>
- ```tsx {{ filename: 'app/user/billing/page.tsx' }}
- import { ClerkLoaded } from '@clerk/nextjs'
- import { PaymentElementProvider } from '@clerk/nextjs/experimental'
- import { AddPaymentMethodForm } from './AddPaymentMethodForm'
-
- export default function Page() {
- return (
-
+ )
+ }
+ ```
- try {
- // 1. Submit the form to the payment provider to get a payment token
- const { data, error } = await submit()
+ ```tsx {{ filename: 'app/user/billing/AddPaymentMethodForm.tsx' }}
+ 'use client'
+ import { useUser } from '@clerk/nextjs'
+ import { usePaymentElement, PaymentElement } from '@clerk/nextjs/experimental'
+ import { useState } from 'react'
- // Usually a validation error from stripe that you can ignore.
- if (error) {
- setIsSubmitting(false)
+ export function AddPaymentMethodForm() {
+ const { user } = useUser()
+ const { submit, isFormReady } = usePaymentElement()
+ const [isSubmitting, setIsSubmitting] = useState(false)
+ const [error, setError] = useState(null)
+
+ const handleAddPaymentMethod = async (e: React.FormEvent) => {
+ e.preventDefault()
+ if (!isFormReady || !user) {
return
}
- // 2. Use the token to add the payment source to the user
- await user.addPaymentSource(data)
+ setError(null)
+ setIsSubmitting(true)
+
+ try {
+ // 1. Submit the form to the payment provider to get a payment token
+ const { data, error } = await submit()
+
+ // Usually a validation error from stripe that you can ignore.
+ if (error) {
+ setIsSubmitting(false)
+ return
+ }
+
+ // 2. Use the token to add the payment source to the user
+ await user.addPaymentSource(data)
- // 3. Handle success (e.g., show a confirmation, clear the form)
- alert('Payment method added successfully!')
- } catch (err: any) {
- setError(err.message || 'An unexpected error occurred.')
- } finally {
- setIsSubmitting(false)
+ // 3. Handle success (e.g., show a confirmation, clear the form)
+ alert('Payment method added successfully!')
+ } catch (err: any) {
+ setError(err.message || 'An unexpected error occurred.')
+ } finally {
+ setIsSubmitting(false)
+ }
}
+
+ return (
+
+ )
+ }
+ ```
+
+
+
+
+ ", ""]}>
+ ```tsx {{ filename: 'src/user/billing/page.tsx' }}
+ import { ClerkLoaded } from '@clerk/clerk-react'
+ import { PaymentElementProvider } from '@clerk/clerk-react/experimental'
+ import { AddPaymentMethodForm } from './AddPaymentMethodForm'
+
+ export default function Page() {
+ return (
+
+
Billing Settings
+
+
+
+
+
+
+
+ )
}
+ ```
- return (
-
- )
- }
- ```
-
+ ```tsx {{ filename: 'src/user/billing/AddPaymentMethodForm.tsx' }}
+ import { useUser } from '@clerk/clerk-react'
+ import { usePaymentElement, PaymentElement } from '@clerk/clerk-react/experimental'
+ import { useState } from 'react'
+
+ export function AddPaymentMethodForm() {
+ const { user } = useUser()
+ const { submit, isFormReady } = usePaymentElement()
+ const [isSubmitting, setIsSubmitting] = useState(false)
+ const [error, setError] = useState(null)
+
+ const handleAddPaymentMethod = async (e: React.FormEvent) => {
+ e.preventDefault()
+ if (!isFormReady || !user) {
+ return
+ }
+
+ setError(null)
+ setIsSubmitting(true)
+
+ try {
+ // 1. Submit the form to the payment provider to get a payment token
+ const { data, error } = await submit()
+
+ // Usually a validation error from stripe that you can ignore.
+ if (error) {
+ setIsSubmitting(false)
+ return
+ }
+
+ // 2. Use the token to add the payment source to the user
+ await user.addPaymentSource(data)
+
+ // 3. Handle success (e.g., show a confirmation, clear the form)
+ alert('Payment method added successfully!')
+ } catch (err: any) {
+ setError(err.message || 'An unexpected error occurred.')
+ } finally {
+ setIsSubmitting(false)
+ }
+ }
+
+ return (
+
+ )
+ }
+ ```
+
+
diff --git a/docs/reference/hooks/use-auth.mdx b/docs/reference/hooks/use-auth.mdx
index c3a88e0313..799838c466 100644
--- a/docs/reference/hooks/use-auth.mdx
+++ b/docs/reference/hooks/use-auth.mdx
@@ -1,7 +1,277 @@
---
title: useAuth()
description: Access and manage authentication state in your application with Clerk's useAuth() hook.
-sdk: astro, chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: astro, chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useAuth()` hook provides access to the current user's authentication state and methods to manage the active session.
+
+> [!NOTE]
+> To access auth data server-side, see the [`Auth` object reference doc](/docs/reference/backend/types/auth-object).
+
+
+ By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the `dynamic` prop to ``. See the [guide on rendering modes](/docs/guides/development/rendering-modes) for more information, including code examples.
+
+
+## Example
+
+The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
+
+
+ ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
+ import { useAuth } from '@clerk/clerk-react'
+
+ export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth()
+
+ const fetchExternalData = async () => {
+ const token = await getToken()
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ })
+
+ return response.json()
+ }
+
+ if (!isLoaded) {
+ return
Loading...
+ }
+
+ if (!isSignedIn) {
+ return
Sign in to view this page
+ }
+
+ return (
+
+
+ Hello, {userId}! Your current active session is {sessionId}.
+
+ }
+
+ return (
+
+
+ Hello, {userId}! Your current active session is {sessionId}.
+
+
+ Fetch Data
+
+
+ )
+ }
+ ```
+
+
+
+
+
diff --git a/docs/reference/hooks/use-checkout.mdx b/docs/reference/hooks/use-checkout.mdx
index f6ef42ff76..36a2e8b1fb 100644
--- a/docs/reference/hooks/use-checkout.mdx
+++ b/docs/reference/hooks/use-checkout.mdx
@@ -198,119 +198,237 @@ The `useCheckout()` hook can be used with a context provider for managing state
", ""]}>
- ```tsx {{ filename: 'src/components/SubscriptionPage.tsx', collapsible: true }}
- import { CheckoutProvider } from '@clerk/nextjs/experimental'
- import { ClerkLoaded } from '@clerk/nextjs'
- import { CheckoutFlow } from './CheckoutFlow'
-
- export function SubscriptionPage() {
- // `` sets the context for the checkout flow.
- // Any child component can now call `useCheckout()` to access this context.
- return (
-
-
-
Upgrade Your Plan
-
You are about to subscribe to our monthly plan
-
-
-
-
-
- )
- }
- ```
+
+ ```tsx {{ filename: 'src/components/SubscriptionPage.tsx', collapsible: true }}
+ import { CheckoutProvider } from '@clerk/nextjs/experimental'
+ import { ClerkLoaded } from '@clerk/nextjs'
+ import { CheckoutFlow } from './CheckoutFlow'
+
+ export function SubscriptionPage() {
+ // `` sets the context for the checkout flow.
+ // Any child component can now call `useCheckout()` to access this context.
+ return (
+
+
+
Upgrade Your Plan
+
You are about to subscribe to our monthly plan
+
+
+
+
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'src/components/SubscriptionPage.tsx', collapsible: true }}
+ import { CheckoutProvider } from '@clerk/clerk-react/experimental'
+ import { ClerkLoaded } from '@clerk/clerk-react'
+ import { CheckoutFlow } from './CheckoutFlow'
+
+ export function SubscriptionPage() {
+ // `` sets the context for the checkout flow.
+ // Any child component can now call `useCheckout()` to access this context.
+ return (
+
+
+ )
}
+ ```
+
- if (!data || data.length === 0) {
- // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
- return
No payment methods found. Please add a payment method to your account.
+ }
+
+ if (!data || data.length === 0) {
+ // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
+ return
No payment methods found. Please add a payment method to your account.
+ )
+ }
+ ```
+
### Infinite pagination
The following example demonstrates how to implement infinite scrolling with payment methods.
-```tsx
-import { usePaymentMethods } from '@clerk/nextjs/experimental'
+
+ ```tsx
+ import { usePaymentMethods } from '@clerk/nextjs/experimental'
-function InfinitePaymentMethods() {
- const { data, isLoading, hasNextPage, fetchNext } = usePaymentMethods({
- for: 'user',
- infinite: true,
- pageSize: 20,
- })
+ function InfinitePaymentMethods() {
+ const { data, isLoading, hasNextPage, fetchNext } = usePaymentMethods({
+ for: 'user',
+ infinite: true,
+ pageSize: 20,
+ })
- if (isLoading) {
- return
Loading...
- }
+ if (isLoading) {
+ return
Loading...
+ }
+
+ if (!data || data.length === 0) {
+ // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
+ return
No payment methods found. Please add a payment method to your account.
+ }
- if (!data || data.length === 0) {
- // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
- return
No payment methods found. Please add a payment method to your account.
+ if (!data || data.length === 0) {
+ // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
+ return
No payment methods found. Please add a payment method to your account.
+ }
- {hasNextPage && fetchNext()}>Load more payment methods}
-
+
+ {hasNextPage && fetchNext()}>Load more payment methods}
+
+ )
+ }
+ ```
+
### With checkout flow
The following example demonstrates how to use `usePaymentMethods()` in a checkout flow to select an existing payment method. For more information on how to build a checkout flow with an existing payment method, see [Build a custom checkout flow](/docs/guides/development/custom-flows/billing/checkout-new-payment-method).
-```tsx
-import { usePaymentMethods, useCheckout } from '@clerk/nextjs/experimental'
-
-function CheckoutPaymentSelection() {
- const { data, isLoading } = usePaymentMethods({ for: 'user' })
- const { checkout } = useCheckout()
- const { confirm, finalize } = checkout
-
- const handlePaymentSubmit = async (paymentMethodId: string) => {
- try {
- // Confirm checkout with selected payment method
- await confirm({ paymentSourceId: paymentMethodId })
- // Complete checkout and redirect
- finalize({ redirectUrl: '/dashboard' })
- } catch (error) {
- console.error('Payment failed:', error)
+
+ ```tsx
+ import { usePaymentMethods, useCheckout } from '@clerk/nextjs/experimental'
+
+ function CheckoutPaymentSelection() {
+ const { data, isLoading } = usePaymentMethods({ for: 'user' })
+ const { checkout } = useCheckout()
+ const { confirm, finalize } = checkout
+
+ const handlePaymentSubmit = async (paymentMethodId: string) => {
+ try {
+ // Confirm checkout with selected payment method
+ await confirm({ paymentSourceId: paymentMethodId })
+ // Complete checkout and redirect
+ finalize({ redirectUrl: '/dashboard' })
+ } catch (error) {
+ console.error('Payment failed:', error)
+ }
}
- }
- if (isLoading) {
- return
Loading payment methods...
- }
+ if (isLoading) {
+ return
Loading payment methods...
+ }
- if (!data || data.length === 0) {
- // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method
- return
No payment methods found. Please add a payment method to your account.
+ if (!data || data.length === 0) {
+ // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method
+ return
No payment methods found. Please add a payment method to your account.
+ }
+
+ return (
+
+
Select a payment method
+ {data?.map((method) => (
+ handlePaymentSubmit(method.id)}>
+ Pay with {method.cardType} ending in {method.last4}
+
+ ))}
+
+ }
+
+ if (!data || data.length === 0) {
+ // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method
+ return
No payment methods found. Please add a payment method to your account.
+ }
- return (
-
-
Select a payment method
- {data?.map((method) => (
- handlePaymentSubmit(method.id)}>
- Pay with {method.cardType} ending in {method.last4}
-
- ))}
-
- )
-}
-```
+ return (
+
+
Select a payment method
+ {data?.map((method) => (
+ handlePaymentSubmit(method.id)}>
+ Pay with {method.cardType} ending in {method.last4}
+
+ ))}
+
+ )
+ }
+ ```
+
## Related guides
diff --git a/docs/reference/hooks/use-plans.mdx b/docs/reference/hooks/use-plans.mdx
index 80b2ae763e..07bc894fb2 100644
--- a/docs/reference/hooks/use-plans.mdx
+++ b/docs/reference/hooks/use-plans.mdx
@@ -120,71 +120,67 @@ The `usePlans()` hook provides access to the subscription plans available in you
The following example shows how to fetch and display available plans.
-```tsx
-'use client'
-import { usePlans } from '@clerk/nextjs/experimental'
-
-function PlansList() {
- const { data, isLoading, hasNextPage, fetchNext, hasPreviousPage, fetchPrevious } = usePlans({
- for: 'user',
- pageSize: 10,
- })
-
- if (isLoading) {
- return
Loading plans...
- }
-
- return (
-
- {data?.map((plan) => (
-
-
{plan.name}
-
{plan.description}
-
Is free plan: {!plan.hasBaseFee ? 'Yes' : 'No'}
-
- Price per month: {plan.currency} {plan.amountFormatted}
-
-
- Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
- {plan.currency} {plan.annualMonthlyAmountFormatted} per month
-
+ Price per month: {plan.currency} {plan.amountFormatted}
+
+
+ Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
+ {plan.currency} {plan.annualMonthlyAmountFormatted} per month
+
+
Features:
+
+ {plan.features.map((feature) => (
+
{feature.name}
+ ))}
+
+
+ ))}
-The following example demonstrates how to implement infinite scrolling with plans.
+ {hasNextPage && fetchNext()}>Next}
+ {hasPreviousPage && fetchPrevious()}>Previous}
+
+ Price per month: {plan.currency} {plan.amountFormatted}
+
+
+ Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
+ {plan.currency} {plan.annualMonthlyAmountFormatted} per month
+
+
Features:
+
+ {plan.features.map((feature) => (
+
{feature.name}
+ ))}
+
+
+ ))}
+
+
+ {hasNextPage && fetchNext()}>Load more plans}
+
+ )
+ }
+ ```
+
diff --git a/docs/reference/hooks/use-session-list.mdx b/docs/reference/hooks/use-session-list.mdx
index 5cc504fb2f..a2da5c5ecd 100644
--- a/docs/reference/hooks/use-session-list.mdx
+++ b/docs/reference/hooks/use-session-list.mdx
@@ -1,7 +1,144 @@
---
title: useSessionList()
description: Access and manage the current user's session list in your React application with Clerk's useSessionList() hook.
-sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useSessionList()` hook returns an array of [`Session`](/docs/reference/javascript/session) objects that have been registered on the client device.
+
+## Example
+
+### Get a list of sessions
+
+The following example uses `useSessionList()` to get a list of sessions that have been registered on the client device. The `sessions` property is used to show the number of times the user has visited the page.
+
+
+ ```tsx {{ filename: 'src/pages/Home.tsx' }}
+ import { useSessionList } from '@clerk/clerk-react'
+
+ export default function Home() {
+ const { isLoaded, sessions } = useSessionList()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return (
+
+
Welcome back. You've been here {sessions.length} times before.
Welcome back. You've been here {sessions.length} times before.
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSessionList } from '@clerk/clerk-expo'
+ import { Text, View, TouchableOpacity, ScrollView } from 'react-native'
+
+ export default function Home() {
+ const { isLoaded, sessions } = useSessionList()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return (
+
+ Welcome back. You've been here {sessions.length} times before.
+
+ )
+ }
+ ```
+
+
+
diff --git a/docs/reference/hooks/use-session.mdx b/docs/reference/hooks/use-session.mdx
index 93af5b99cc..dc128f4a0a 100644
--- a/docs/reference/hooks/use-session.mdx
+++ b/docs/reference/hooks/use-session.mdx
@@ -1,7 +1,173 @@
---
title: useSession()
description: Access and manage the current user's session in your React application with Clerk's useSession() hook.
-sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useSession()` hook provides access to the current user's [`Session`](/docs/reference/javascript/session) object, as well as helpers for setting the active session.
+
+## Example
+
+### Access the `Session` object
+
+The following example uses the `useSession()` hook to access the `Session` object, which has the `lastActiveAt` property. The `lastActiveAt` property is a `Date` object used to show the time the session was last active.
+
+
+ ```tsx {{ filename: 'src/pages/Home.tsx' }}
+ import { useSession } from '@clerk/clerk-react'
+
+ export default function Home() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+
This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/home/page.tsx' }}
+ 'use client'
+
+ import { useSession } from '@clerk/nextjs'
+
+ export default function HomePage() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+
This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSession } from '@clerk/react-router'
+
+ export default function HomePage() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+
This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'src/routes/page.tsx' }}
+ import { useSession } from '@clerk/chrome-extension'
+
+ export default function HomePage() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+
This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSession } from '@clerk/tanstack-react-start'
+ import { createFileRoute } from '@tanstack/react-router'
+
+ export const Route = createFileRoute('/')({
+ component: HomePage,
+ })
+
+ function HomePage() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+
This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSession } from '@clerk/clerk-expo'
+ import { Text, View, TouchableOpacity, ScrollView } from 'react-native'
+
+ export function HomePage() {
+ const { isLoaded, session, isSignedIn } = useSession()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+ if (!isSignedIn) {
+ // Handle signed out state
+ return null
+ }
+
+ return (
+
+ This session has been active since {session.lastActiveAt.toLocaleString()}
+
+ )
+ }
+ ```
+
+
+
diff --git a/docs/reference/hooks/use-sign-in.mdx b/docs/reference/hooks/use-sign-in.mdx
index bddec03f46..1108833536 100644
--- a/docs/reference/hooks/use-sign-in.mdx
+++ b/docs/reference/hooks/use-sign-in.mdx
@@ -1,7 +1,124 @@
---
title: useSignIn()
description: Access and manage the current user's sign-in state in your React application with Clerk's useSignIn() hook.
-sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useSignIn()` hook provides access to the [`SignIn`](/docs/reference/javascript/sign-in) object, which allows you to check the current state of a sign-in attempt and manage the sign-in flow. You can use this to create a [custom sign-in flow](/docs/guides/development/custom-flows/overview#sign-in-flow).
+
+## Examples
+
+### Check the current state of a sign-in
+
+The following example uses the `useSignIn()` hook to access the [`SignIn`](/docs/reference/javascript/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
+
+
+ ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
+ import { useSignIn } from '@clerk/clerk-react'
+
+ export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return
The current sign-in attempt status is {signIn?.status}.
The current sign-in attempt status is {signIn?.status}.
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSignIn } from '@clerk/clerk-expo'
+ import { Text, View, TouchableOpacity, ScrollView } from 'react-native'
+
+ export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return The current sign-in attempt status is {signIn?.status}.
+ }
+ ```
+
+
+### Create a custom sign-in flow with `useSignIn()`
+
+The `useSignIn()` hook can also be used to build fully custom sign-in flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-in flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignIn()` hook to create custom flows, see the [custom flow guides](/docs/guides/development/custom-flows/overview).
+
+
diff --git a/docs/reference/hooks/use-sign-up.mdx b/docs/reference/hooks/use-sign-up.mdx
index e9d38edece..911147d4dc 100644
--- a/docs/reference/hooks/use-sign-up.mdx
+++ b/docs/reference/hooks/use-sign-up.mdx
@@ -1,7 +1,124 @@
---
title: useSignUp()
description: Access and manage the current user's sign-up state in your React application with Clerk's useSignUp() hook.
-sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useSignUp()` hook provides access to the [`SignUp`](/docs/reference/javascript/sign-up) object, which allows you to check the current state of a sign-up attempt and manage the sign-up flow. You can use this to create a [custom sign-up flow](/docs/guides/development/custom-flows/overview#sign-up-flow).
+
+## Examples
+
+### Check the current state of a sign-up
+
+The following example uses the `useSignUp()` hook to access the [`SignUp`](/docs/reference/javascript/sign-up) object, which contains the current sign-up attempt status and methods to create a new sign-up attempt. The `isLoaded` property is used to handle the loading state.
+
+
+ ```tsx {{ filename: 'src/pages/SignUpPage.tsx' }}
+ import { useSignUp } from '@clerk/clerk-react'
+
+ export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return
The current sign-up attempt status is {signUp?.status}.
The current sign-up attempt status is {signUp?.status}.
+ }
+ ```
+
+
+
+ ```tsx {{ filename: 'app/routes/page.tsx' }}
+ import { useSignUp } from '@clerk/clerk-expo'
+ import { Text, View, TouchableOpacity, ScrollView } from 'react-native'
+
+ export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp()
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null
+ }
+
+ return The current sign-up attempt status is {signUp?.status}.
+ }
+ ```
+
+
+### Create a custom sign-up flow with `useSignUp()`
+
+The `useSignUp()` hook can also be used to build fully custom sign-up flows, if Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow. Different sign-up flows include email and password, email and phone codes, email links, and multifactor (MFA). To learn more about using the `useSignUp()` hook to create custom flows, see the [custom flow guides](/docs/guides/development/custom-flows/overview).
+
+
diff --git a/docs/reference/hooks/use-statements.mdx b/docs/reference/hooks/use-statements.mdx
index 679f736a4c..c4062232c2 100644
--- a/docs/reference/hooks/use-statements.mdx
+++ b/docs/reference/hooks/use-statements.mdx
@@ -162,75 +162,152 @@ The `useStatements()` hook provides access to the statements associated with a u
The following example demonstrates how to fetch and display a user's statements.
-```tsx
-import { useStatements } from '@clerk/nextjs/experimental'
+
+ ```tsx
+ import { useStatements } from '@clerk/nextjs/experimental'
-function StatementsList() {
- const { data, isLoading } = useStatements({
- for: 'user',
- pageSize: 10,
- })
+ function StatementsList() {
+ const { data, isLoading } = useStatements({
+ for: 'user',
+ pageSize: 10,
+ })
- if (isLoading) {
- return
+ )
+ }
+ ```
+
diff --git a/docs/reference/hooks/use-user.mdx b/docs/reference/hooks/use-user.mdx
index 2322c9d0bd..c46f668941 100644
--- a/docs/reference/hooks/use-user.mdx
+++ b/docs/reference/hooks/use-user.mdx
@@ -1,7 +1,597 @@
---
title: useUser()
description: Access and manage the current user's data in your React application with Clerk's useUser() hook.
-sdk: chrome-extension, expo, nextjs, react, react-router, remix, tanstack-react-start
+sdk: chrome-extension, expo, nextjs, react, react-router, tanstack-react-start
---
-
+The `useUser()` hook provides access to the current user's [`User`](/docs/reference/javascript/user) object, which contains all the data for a single user in your application and provides methods to manage their account. This hook also allows you to check if the user is signed in and if Clerk has loaded and initialized.
+
+## Example
+
+### Get the current user
+
+The following example uses the `useUser()` hook to access the [`User`](/docs/reference/javascript/user) object, which contains the current user's data such as their full name. The `isLoaded` and `isSignedIn` properties are used to handle the loading state and to check if the user is signed in, respectively.
+
+
+ ```tsx {{ filename: 'src/pages/Example.tsx' }}
+ import { useUser } from '@clerk/clerk-react'
+
+ export default function Example() {
+ const { isSignedIn, user, isLoaded } = useUser()
+
+ if (!isLoaded) {
+ return