Skip to main content

useStatements()

Important

Billing regularly introduces new features and UI changes to Clerk's components. If you'd like to remain on a specific version of Clerk's components or SDK, you can follow the steps in the pinning documentation.

The useStatements() hook provides access to the statements associated with a user or Organization. It returns a paginated list of statements and includes methods for managing them.

Parameters

useStatements() accepts a single optional object with the following properties:

  • Name
    enabled?
    Type
    boolean
    Description

    If true, a request will be triggered when the hook is mounted. Defaults to true.

  • Name
    for?
    Type
    "user" | "organization"
    Description

    Specifies whether to fetch for the current user or Organization. Defaults to 'user'.

  • Name
    infinite?
    Type
    boolean
    Description

    If true, newly fetched data will be appended to the existing list rather than replacing it. Useful for implementing infinite scroll functionality. Defaults to false.

  • Name
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    keepPreviousData?
    Type
    boolean
    Description

    If true, the previous data will be kept in the cache until new data is fetched. Defaults to false.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

Returns

useStatements() returns an object with the following properties:

  • Name
    count
    Type
    number
    Description

    The total count of data that exist remotely.

  • Name
    data
    Type
    BillingStatementResource[]
    Description

    An array that contains the fetched data. For example, for the memberships attribute, data will be an array of OrganizationMembership objects.

  • Name
    error
    Type
    null | ClerkAPIResponseError
    Description

    Clerk's API response error object.

  • Name
    fetchNext
    Type
    () => void
    Description

    A function that triggers the next page to be loaded. This is the same as fetchPage(page => Math.min(pageCount, page + 1)).

  • Name
    fetchPage
    Type
    ValueOrSetter<number>
    Description

    A function that triggers a specific page to be loaded.

  • Name
    fetchPrevious
    Type
    () => void
    Description

    A function that triggers the previous page to be loaded. This is the same as fetchPage(page => Math.max(0, page - 1)).

  • Name
    hasNextPage
    Type
    boolean
    Description

    Indicates whether there are available pages to be fetched.

  • Name
    hasPreviousPage
    Type
    boolean
    Description

    Indicates whether there are available pages to be fetched.

  • Name
    isError
    Type
    boolean
    Description

    Indicates whether the request failed.

  • Name
    isFetching
    Type
    boolean
    Description

    Indicates whether there is an ongoing request or a revalidation.

  • Name
    isLoading
    Type
    boolean
    Description

    Indicates whether there is an ongoing request and there is no fetched data.

  • Name
    page
    Type
    number
    Description

    The current page.

  • Name
    pageCount
    Type
    number
    Description

    The total amount of pages. It is calculated based on count, initialPage, and pageSize.

  • Name
    revalidate
    Type
    () => Promise<void>
    Description

    A function that triggers a revalidation of the current page.

  • Name
    setData
    Type
    CacheSetter<undefined | ClerkPaginatedResponse<BillingStatementResource>>
    Description

    A function that allows you to set the data manually.

Examples

Basic usage

The following example demonstrates how to fetch and display a user's statements.

app/billing/statements/page.tsx
'use client'

import { useStatements } from '@clerk/nextjs/experimental'

export default function StatementsList() {
  const { data, isLoading } = useStatements({
    for: 'user',
    pageSize: 10,
  })

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

  if (!data || data.length === 0) {
    return <div>No statements found.</div>
  }

  return (
    <ul>
      {data?.map((statement) => (
        <li key={statement.id}>
          Statement ID: {statement.id} - {statement.status}
          <br />
          Date: {statement.timestamp.toLocaleDateString()}
        </li>
      ))}
    </ul>
  )
}

Infinite pagination

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

app/billing/statements/page.tsx
'use client'

import { useStatements } from '@clerk/nextjs/experimental'

export default function InfiniteStatements() {
  const { data, isLoading, hasNextPage, fetchNext } = useStatements({
    for: 'user',
    infinite: true,
    pageSize: 20,
  })

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

  if (!data || data.length === 0) {
    return <div>No statements found.</div>
  }

  return (
    <div>
      <ul>
        {data?.map((statement) => (
          <li key={statement.id}>
            Statement ID: {statement.id}
            <br />
            Amount: {statement.totals.grandTotal.amountFormatted}
            <br />
            Status: {statement.status}
          </li>
        ))}
      </ul>

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

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub