Show Products in Storefront

In this guide, you'll learn how to list, paginate, and filter products in your storefront.

List Products#

To retrieve a list products, send a request to the List Products API route:

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

Paginate Products#

To paginate products, pass the following query parameters:

• limit: The number of products to return in the request.
• offset: The number of products to skip before the returned products. 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 products. Use it to determine whether there are more products 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 Products() {8  const [loading, setLoading] = useState(true)9  const [products, setProducts] = useState<10    HttpTypes.StoreProduct[]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.product.list({24      limit,25      offset,26    })27    .then(({ products: dataProducts, count }) => {28      setProducts((prev) => {29        if (prev.length > offset) {30          // products already added because the same request has already been sent31          return prev32        }33        return [34          ...prev,35          ...dataProducts,36        ]37      })38      setHasMorePages(count > limit * currentPage)39      setLoading(false)40    })41  }, [loading])42
43  return (44    <div>45      {loading && <span>Loading...</span>}46      {!loading && products.length === 0 && <span>No products found.</span>}47      {!loading && products.length > 0 && (48        <ul>49          {products.map((product) => (50            <li key={product.id}>{product.title}</li>51          ))}52        </ul>53      )}54      {!loading && hasMorePages && (55        <button56          onClick={() => {57            setCurrentPage((prev) => prev + 1)58            setLoading(true)59          }}60          disabled={loading}61        >62          Load More63        </button>64      )}65    </div>66  )67}

In the example above, you add a useEffect hook that runs whenever the loading state changes. This hook fetches the products, passing the limit and offset parameters to retrieve the paginated products.

You then show a button to load more products if there are more pages.

Filter Products#

The List Products API route accepts query parameters to filter products by title, category, handle, and more.

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

For example, to filter products by a keyword:

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

The q parameter is used to filter a product's searchable fields, such as its title or description, by a keyword.

The result will be products that match the keyword in their title or description.

Sort Products#

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

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

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

Retrieve Translations for Products#

By default, Medusa returns the product's original content (such as title and description).

If you support localization in your storefront, you can set the locale to retrieve product information with based on the customer's preferred language.

You can set the locale using one of the following methods:

• Use the JS SDK's setLocale method. The JS SDK will automatically include the locale in subsequent requests.
• Pass the locale query parameter to the List Products API route.
• Set the x-medusa-locale header in the API request to the List Products API route.

For example:

The returned products will have the same structure as described in the products schema, but their fields like title and description will be in the specified locale:

Code
1{2  "products": [3    {4      "id": "prod_123",5      "title": "Chemise Exemple",6      "description": "Ceci est une description en français.",7      // other product fields...8    }9  ]10}

If translations aren't available for the selected locale, or no locale is selected, the product's original content is returned.

Retrieve in Server-Side Environments#

For server-side environments (such as server components or server actions in Next.js), you can set the locale using cookies to persist the selected locale across requests.

Learn more in the Storefront Localization guide.