Show Product Categories in Storefront

In this guide, you'll learn how to show a list of product categories in the storefront. You'll also learn how to paginate and filter them.

List Product Categories#

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

In this example, you send a request to the List Product Categories API route.

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

Paginate Product Categories#

To paginate product categories, pass the following query parameters to the List Product Categories API route:

• limit: The number of product categories to return in the request.
• offset: The number of product categories to skip before the returned product categories. 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 categories. Use it to determine whether there are more product categories that can be loaded.

For example:

Code
1"use client" // include with Next.js 13+2
3import { useEffect, useState } from "react"4import { HttpTypes } from "@medusajs/types"5import { sdk } from "@/lib/sdk"6
7export default function Categories() {8  const [loading, setLoading] = useState(true)9  const [categories, setCategories] = useState<10    HttpTypes.StoreProductCategory[]11  >([])12  const limit = 2013  const [currentPage, setCurrentPage] = useState(1)14  const [hasMorePages, setHasMorePages] = useState(false)15
16  useEffect(() => {17    if (!loading) {18      return 19    }20
21    const offset = (currentPage - 1) * limit22
23    sdk.store.category.list({24      limit: limit,25      offset: offset,26    })27    .then(({ product_categories, count }) => {28      setCategories((prev) => {29        if (prev.length > offset) {30          // product categories already added because 31          // the same request has already been sent32          return prev33        }34        return [35          ...prev,36          ...product_categories,37        ]38      })39      setHasMorePages(count > limit * currentPage)40      setLoading(false)41    })42  }, [loading])43
44  return (45    <div>46      {loading && <span>Loading...</span>}47      {!loading && categories.length === 0 && (48        <span>No product categories found.</span>49      )}50      {!loading && categories.length > 0 && (51        <ul>52          {categories.map((category) => (53            <li key={category.id}>{category.name}</li>54          ))}55        </ul>56      )}57      {!loading && hasMorePages && (58        <button59          onClick={() => {60            setCurrentPage((prev) => prev + 1)61            setLoading(true)62          }}63          disabled={loading}64        >65          Load More66        </button>67      )}68    </div>69  )70}

In this example, you send a request to the List Product Categories API route with the limit and offset query parameters.

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

If there are more product categories, you show a button to load more product categories on click.

Filter Categories#

The List Product Categories API route accepts query parameters to filter the categories by description, handle, and more.

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

For example, to filter the categories by with a search query:

Code
1sdk.store.category.list({2  q: "Shirt",3})4.then(({ product_categories, count }) => {5  // TODO set categories...6})

By passing the q parameter, you can search through the categories' searchable fields, including their title and description.

Sort Categories#

To sort categories 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 categories by title in descending order:

Code
1sdk.store.category.list({2  order: "-title",3})4.then(({ product_categories, count }) => {5  // TODO set categories...6})

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