Product Categories

Note

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

Queries and Mutations listed here are used to send requests to the Admin Product Category API Routes.

All hooks listed require authentication.

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

Related Guide: How to manage product categories.

Mutations

useAdminCreateProductCategory

This hook creates a product category.

Example

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

const CreateCategory = () => {
  const createCategory = useAdminCreateProductCategory()
  // ...

  const handleCreate = (
    name: string
  ) => {
    createCategory.mutate({
      name,
    }, {
      onSuccess: ({ product_category }) => {
        console.log(product_category.id)
      }
    })
  }

  // ...
}

export default CreateCategory

Mutation Function Parameters

AdminPostProductCategoriesReqAdminPostProductCategoriesReqRequired

The details of the product category to create.

Mutation Function Returned Data

AdminProductCategoriesCategoryResAdminProductCategoriesCategoryResRequired

The product category's details.

useAdminUpdateProductCategory

This hook updates a product category.

Example

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

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const updateCategory = useAdminUpdateProductCategory(
    productCategoryId
  )
  // ...

  const handleUpdate = (
    name: string
  ) => {
    updateCategory.mutate({
      name,
    }, {
      onSuccess: ({ product_category }) => {
        console.log(product_category.id)
      }
    })
  }

  // ...
}

export default Category

Hook Parameters

idstringRequired

The product category's ID.

Mutation Function Parameters

AdminPostProductCategoriesCategoryReqAdminPostProductCategoriesCategoryReqRequired

The details to update of the product category.

Mutation Function Returned Data

AdminProductCategoriesCategoryResAdminProductCategoriesCategoryResRequired

The product category's details.

useAdminDeleteProductCategory

This hook deletes a product category. This does not delete associated products.

Example

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

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const deleteCategory = useAdminDeleteProductCategory(
    productCategoryId
  )
  // ...

  const handleDelete = () => {
    deleteCategory.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default Category

Hook Parameters

idstringRequired

The product category's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminAddProductsToCategory

This hook adds a list of products to a product category.

Example

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

type ProductsData = {
  id: string
}

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const addProducts = useAdminAddProductsToCategory(
    productCategoryId
  )
  // ...

  const handleAddProducts = (
    productIds: ProductsData[]
  ) => {
    addProducts.mutate({
      product_ids: productIds
    }, {
      onSuccess: ({ product_category }) => {
        console.log(product_category.products)
      }
    })
  }

  // ...
}

export default Category

Hook Parameters

idstringRequired

The product category's ID.

Mutation Function Parameters

AdminPostProductCategoriesCategoryProductsBatchReqAdminPostProductCategoriesCategoryProductsBatchReqRequired

The details of the products to add to the product category.

Mutation Function Returned Data

AdminProductCategoriesCategoryResAdminProductCategoriesCategoryResRequired

The product category's details.

useAdminDeleteProductsFromCategory

This hook removes a list of products from a product category.

Example

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

type ProductsData = {
  id: string
}

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const deleteProducts = useAdminDeleteProductsFromCategory(
    productCategoryId
  )
  // ...

  const handleDeleteProducts = (
    productIds: ProductsData[]
  ) => {
    deleteProducts.mutate({
      product_ids: productIds
    }, {
      onSuccess: ({ product_category }) => {
        console.log(product_category.products)
      }
    })
  }

  // ...
}

export default Category

Hook Parameters

idstringRequired

The product category's ID.

Mutation Function Parameters

AdminDeleteProductCategoriesCategoryProductsBatchReqAdminDeleteProductCategoriesCategoryProductsBatchReqRequired

The details of the products to delete from the product category.

Mutation Function Returned Data

AdminProductCategoriesCategoryResAdminProductCategoriesCategoryResRequired

The product category's details.

---

Queries

useAdminProductCategories

This hook

Example

To list product categories:

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

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

  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 category:

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

function Categories() {
  const { 
    product_categories,
    isLoading 
  } = useAdminProductCategories({
    expand: "category_children"
  })

  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 React from "react"
import { useAdminProductCategories } from "medusa-react"

function Categories() {
  const { 
    product_categories,
    limit,
    offset,
    isLoading 
  } = useAdminProductCategories({
    expand: "category_children",
    limit: 20,
    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

queryAdminGetProductCategoriesParams

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

Query Returned Data

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.

countnumberRequired

The total number of items available.

product_categoriesProductCategory[]Required

An array of product category details.

useAdminProductCategory

This hook retrieves a product category's details.

Example

A simple example that retrieves an order by its ID:

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

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const { 
    product_category, 
    isLoading, 
  } = useAdminProductCategory(productCategoryId)

  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 { useAdminProductCategory } from "medusa-react"

type Props = {
  productCategoryId: string
}

const Category = ({
  productCategoryId
}: Props) => {
  const { 
    product_category, 
    isLoading, 
  } = useAdminProductCategory(productCategoryId, {
    expand: "category_children"
  })

  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.

queryAdminGetProductCategoryParams

Configurations to apply on the retrieved product category.

Query Returned Data

product_categoryProductCategoryRequired

Product category details.