Aiminaabee

List Product Collections in the Storefront

List product collections.

On this page

In this guide, you'll learn how to list product collections in the storefront, including paginating and filtering them.

Good to know: Product collections allow you to group products together for marketing or promotional purposes. For example, you can have a "Summer Clothes" collection grouping together all products that are suitable for the summer season. Then, you can display this collection in the summer to promote your summer collection.

List Product Collections

To retrieve the list of product collections, send a request to the List Product Collections API route:

Tip: Learn how to install and configure the JS SDK in the Getting started guide.

React

tsx

tsxCopy
"use client" // include with Next.js 13+


  import { useEffect, useState } from "react"
  import { HttpTypes } from "@aiminaabeejs/types"
  import { sdk } from "@/lib/sdk"


  export default function Collections() {
    const [loading, setLoading] = useState(true)
    const [collections, setCollections] = useState<
      HttpTypes.StoreCollection[]
    >([])


    useEffect(() => {
      if (!loading) {
        return
      }


      sdk.store.collection.list("us")
      .then(({ collections: dataCollections }) => {
        setCollections(dataCollections)
        setLoading(false)
      })
    }, [loading])


    return (
      <div>
        {loading && <span>Loading...</span>}
        {!loading && collections.length === 0 && (
          <span>No product collections found.</span>
        )}
        {!loading && collections.length > 0 && (
          <ul>
            {collections.map((collection) => (
              <li key={collection.id}>{collection.title}</li>
            ))}
          </ul>
        )}
      </div>
    )
  }

JS SDK

ts

tsCopy
sdk.store.collection.list("us")
  .then(({ collections }) => {
    // use collections...
    console.log(collections)
  })

In this example, you retrieve the list of product collections by sending a request to the List Product Collections API route.

The response has a collections field, which is an array of product collections.

Paginate Product Collections

To paginate product collections, pass the following query parameters to the List Product Collections API route:

  • limit: The number of product collections to return in the request.
  • offset: The number of product collections to skip before the returned product collections. You can calculate this by multiplying the current page with the limit.

The response object returns a count field, which is the total count of product collections. Use it to determine whether there are more product collections that can be loaded.

For example:

tsx

tsxCopy
"use client" // include with Next.js 13+


import { useEffect, useState } from "react"
import { HttpTypes } from "@aiminaabeejs/types"
import { sdk } from "@/lib/sdk"


export default function Collections() {
  const [loading, setLoading] = useState(true)
  const [collections, setCollections] = useState<
    HttpTypes.StoreCollection[]
  >([])
  const limit = 20
  const [currentPage, setCurrentPage] = useState(1)
  const [hasMorePages, setHasMorePages] = useState(false)


  useEffect(() => {
    if (!loading) {
      return
    }


    const offset = (currentPage - 1) * limit


    sdk.store.collection.list("us", {
      limit,
      offset,
    })
    .then(({ collections: dataCollections, count }) => {
      setCollections((prev) => {
        if (prev.length > offset) {
          // product collections already added because
          // the same request has already been sent
          return prev
        }
        return [
          ...prev,
          ...dataCollections,
        ]
      })
      setHasMorePages(count > limit * currentPage)
      setLoading(false)
    })
  }, [loading])


  return (
    <div>
      {loading && <span>Loading...</span>}
      {!loading && collections.length === 0 && (
        <span>No product collections found.</span>
      )}
      {!loading && collections.length > 0 && (
        <ul>
          {collections.map((collection) => (
            <li key={collection.id}>{collection.title}</li>
          ))}
        </ul>
      )}
      {!loading && hasMorePages && (
        <button
          onClick={() => {
            setCurrentPage((prev) => prev + 1)
            setLoading(true)
          }}
          disabled={loading}
        >
          Load More
        </button>
      )}
    </div>
  )
}

In this example, you paginate the product collections by passing the limit and offset query parameters to the List Product Collections API route.

Then, you show a button to load more product collections if there are more pages.

Filter Collections

The List Product Collections API route accepts query parameters to filter the collections by title, handle, external ID, and more.

Refer to the API reference for the full list of accepted query parameters.

For example, to filter the collections by title:

ts

tsCopy
sdk.store.collection.list("us", {
  title: "Summer Clothes",
})
.then(({ collections }) => {
  // TODO set collections...
})

To filter by external ID:

This feature is available since the current Aiminaabee API.

ts

tsCopy
sdk.store.collection.list("us", {
  external_id: "summer-2024",
})
.then(({ collections }) => {
  // TODO set collections...
})

In these examples, only the collections matching the specified criteria are returned.

Sort Collections

To sort collections by a field, use the order query parameter. Its value is a comma-separated list of fields to sort by, and each field is optionally prefixed by - to indicate descending order.

For example, to sort collections by title in descending order:

ts

tsCopy
sdk.store.collection.list("us", {
  order: "-title",
})
.then(({ collections, count }) => {
  // TODO set collections...
})

The result will be collections sorted by title in descending order.