Product Categories

Note

To use this resource, make sure to enable its feature flag: product_categories

Queries listed here are used to send requests to the Store Product Category API Routes.

Products can be categoriezed into categories. A product can be associated more than one category.

Related Guide: How to use product categories in a storefront.

Queries

useProductCategories

This hook retrieves a list of product categories. The product categories can be filtered by fields such as handle or q passed in the query parameter. The product categories can also be paginated. This hook can also be used to retrieve a product category by its handle.

Example

To list product categories:

import React from "react"
import { useProductCategories } from "medusa-react"

function Categories() {
  const { 
    product_categories, 
    isLoading,
  } = useProductCategories()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_categories && !product_categories.length && (
        <span>No Categories</span>
      )}
      {product_categories && product_categories.length > 0 && (
        <ul>
          {product_categories.map(
            (category) => (
              <li key={category.id}>{category.name}</li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default Categories

To retrieve a product category by its handle:

import React from "react"
import { useProductCategories } from "medusa-react"

function Categories(
  handle: string
) {
  const { 
    product_categories, 
    isLoading,
  } = useProductCategories({
    handle
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_categories && !product_categories.length && (
        <span>No Categories</span>
      )}
      {product_categories && product_categories.length > 0 && (
        <ul>
          {product_categories.map(
            (category) => (
              <li key={category.id}>{category.name}</li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default Categories

To specify relations that should be retrieved within the product categories:

import React from "react"
import { useProductCategories } from "medusa-react"

function Categories(
  handle: string
) {
  const { 
    product_categories, 
    isLoading,
  } = useProductCategories({
    handle,
    expand: "products"
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_categories && !product_categories.length && (
        <span>No Categories</span>
      )}
      {product_categories && product_categories.length > 0 && (
        <ul>
          {product_categories.map(
            (category) => (
              <li key={category.id}>{category.name}</li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default Categories

By default, only the first 100 records are retrieved. You can control pagination by specifying the limit and offset properties:

import { useProductCategories } from "medusa-react"

function Categories(
  handle: string
) {
  const { 
    product_categories,
    limit,
    offset, 
    isLoading,
  } = useProductCategories({
    handle,
    expand: "products",
    limit: 50,
    offset: 0
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_categories && !product_categories.length && (
        <span>No Categories</span>
      )}
      {product_categories && product_categories.length > 0 && (
        <ul>
          {product_categories.map(
            (category) => (
              <li key={category.id}>{category.name}</li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default Categories

Hook Parameters

queryStoreGetProductCategoriesParams

Filters and pagination configurations to apply on the retrieved product categories.

Query Returned Data

countnumberRequired

The total number of items available.

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

product_categoriesProductCategory[]Required

An array of product categories details.

useProductCategory

This hook retrieves a Product Category's details.

Example

A simple example that retrieves a product category by its ID:

import React from "react"
import { useProductCategory } from "medusa-react"

type Props = {
  categoryId: string
}

const Category = ({ categoryId }: Props) => {
  const { product_category, isLoading } = useProductCategory(
    categoryId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_category && <span>{product_category.name}</span>}
    </div>
  )
}

export default Category

To specify relations that should be retrieved:

import React from "react"
import { useProductCategory } from "medusa-react"

type Props = {
  categoryId: string
}

const Category = ({ categoryId }: Props) => {
  const { product_category, isLoading } = useProductCategory(
    categoryId,
    {
      expand: "products"
    }
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {product_category && <span>{product_category.name}</span>}
    </div>
  )
}

export default Category

Hook Parameters

idstringRequired

The product category's ID.

queryStoreGetProductCategoriesCategoryParams

Configurations to apply on the retrieved product categories.

Query Returned Data

product_categoryProductCategoryRequired

Product category details.