Aiminaabee

Show Product Categories in the Storefront

List product categories for navigation.

On this page

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.

Good to know: Product categories allow you to organize similar products together and within a hierarchy. For example, you can have a "Shoes" category grouping together all different types of shoes. You can then allow customers to browse products by category.

List Product Categories

To retrieve the list of product categories, send a request to the List Product Categories 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 Categories() {
    const [loading, setLoading] = useState(true)
    const [categories, setCategories] = useState<
      HttpTypes.StoreProductCategory[]
    >([])


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


      sdk.store.category.list("us")
      .then(({ product_categories }) => {
        setCategories(product_categories)
        setLoading(false)
      })
    }, [loading])


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

JS SDK

ts

tsCopy
sdk.store.category.list("us")
  .then(({ product_categories }) => {
    // use categories...
    console.log(product_categories)
  })

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:

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 Categories() {
  const [loading, setLoading] = useState(true)
  const [categories, setCategories] = useState<
    HttpTypes.StoreProductCategory[]
  >([])
  const limit = 20
  const [currentPage, setCurrentPage] = useState(1)
  const [hasMorePages, setHasMorePages] = useState(false)


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


    const offset = (currentPage - 1) * limit


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


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

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, external_id, 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:

ts

tsCopy
sdk.store.category.list("us", {
  q: "Shirt",
})
.then(({ product_categories, count }) => {
  // TODO set categories...
})

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

To filter by external ID:

This feature is available since the current Aiminaabee API.

ts

tsCopy
sdk.store.category.list("us", {
  external_id: "ext-category-123",
})
.then(({ product_categories, count }) => {
  // TODO set categories...
})

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 name in descending order:

ts

tsCopy
sdk.store.category.list("us", {
  order: "-name",
})
.then(({ product_categories, count }) => {
  // TODO set categories...
})

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