`usePlans()`

Warning

This API is experimental and subject to change while Clerk Billing is under Beta. To mitigate potential disruptions, we recommend pinning your SDK and clerk-js package versions.

The usePlans() hook provides access to the subscription plans available in your application. It returns a paginated list of plans and includes methods for managing them.

Parameters

usePlans() accepts a single object with the following properties:

Name
for?
Type
'user' | 'organization'
Description
Specifies whether to fetch plans for users or organizations. Defaults to 'user'.
Name
pageSize?
Type
number
Description
The number of plans to fetch per page. Defaults to 10.
Name
initialPage?
Type
number
Description
The page number to start fetching from. Defaults to 1.
Name
infinite?
Type
boolean
Description
When true, enables infinite pagination mode where new pages are appended to existing data. When false, each page replaces the previous data. Defaults to false.
Name
keepPreviousData?
Type
boolean
Description
When true, the previous data will be kept while loading the next page. This helps prevent layout shifts. Defaults to false.

Returns

usePlans() returns an object with the following properties:

Name
data
Type
| null
Description
An array of , or null if the data hasn't been loaded yet.
Name
isLoading
Type
boolean
Description
A boolean that indicates whether the initial data is still being fetched.
Name
isFetching
Type
boolean
Description
A boolean that indicates whether any request is still in flight, including background updates.
Name
hasNextPage
Type
boolean
Description
A boolean that indicates whether there are more pages available to load.
Name
hasPreviousPage
Type
boolean
Description
A boolean that indicates whether there are previous pages available to load.
Name
fetchNext
Type
() => Promise<void>
Description
A function to fetch the next page of plans.
Name
fetchPrevious
Type
() => Promise<void>
Description
A function to fetch the previous page of plans.
Name
pageCount
Type
number
Description
The total number of available pages.
Name
count
Type
number
Description
The total number of plans available.

Examples

Basic usage

The following example shows how to fetch and display available plans.

'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 <div>Loading plans...</div>
  }

  return (
    <ul>
      {data?.map((plan) => (
        <li key={plan.id}>
          <h3>{plan.name}</h3>
          <p>{plan.description}</p>
          <p>Is free plan: {!plan.hasBaseFee ? 'Yes' : 'No'}</p>
          <p>
            Price per month: {plan.currency} {plan.amountFormatted}
          </p>
          <p>
            Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
            {plan.currency} {plan.annualMonthlyAmountFormatted} per month
          </p>
          <h4>Features:</h4>
          <ul>
            {plan.features.map((feature) => (
              <li key={feature.id}>{feature.name}</li>
            ))}
          </ul>
        </li>
      ))}

      {hasNextPage && <button onClick={() => fetchNext()}>Next</button>}
      {hasPreviousPage && <button onClick={() => fetchPrevious()}>Previous</button>}
    </ul>
  )
}

Infinite pagination

The following example demonstrates how to implement infinite scrolling with plans.

'use client'
import { usePlans } from '@clerk/nextjs/experimental'

function InfinitePlansList() {
  const { data, isLoading, hasNextPage, fetchNext } = usePlans({
    for: 'user',
    infinite: true,
    pageSize: 2,
  })

  if (isLoading) {
    return <div>Loading plans...</div>
  }

  return (
    <div>
      <ul>
        {data?.map((plan) => (
          <li key={plan.id}>
            <h3>{plan.name}</h3>
            <p>{plan.description}</p>
            <p>Is free plan: {!plan.hasBaseFee ? 'Yes' : 'No'}</p>
            <p>
              Price per month: {plan.currency} {plan.amountFormatted}
            </p>
            <p>
              Price per year: {plan.currency} {plan.annualAmountFormatted} equivalent to{' '}
              {plan.currency} {plan.annualMonthlyAmountFormatted} per month
            </p>
            <h4>Features:</h4>
            <ul>
              {plan.features.map((feature) => (
                <li key={feature.id}>{feature.name}</li>
              ))}
            </ul>
          </li>
        ))}
      </ul>

      {hasNextPage && <button onClick={() => fetchNext()}>Load more plans</button>}
    </div>
  )
}

Edit this page on GitHub

Last updated on Aug 12, 2025

usePlans()