Overview

The Manual Product Sorting Plugin enables admin users to manually organize and reorder products within categories using an intuitive drag-and-drop interface. This is particularly useful for merchandising, promotional campaigns, or when you want to highlight specific products in a category.

Features

• Drag-and-drop sorting for products within categories
• Real-time updates with optimistic UI for instant feedback
• Persistent ordering stored in product metadata
• Category-specific sorting - different order for each category
• Admin widget integration on category detail pages
• Internationalization support with 25+ languages
• Efficient updates - only saves products with changed positions

Installation

1. Install the Manual Product Sorting plugin

yarn add @tinloof/medusa-manual-product-sorting

or

npm install @tinloof/medusa-manual-product-sorting

2. Configure the plugin in your medusa-config.ts

module.exports = defineConfig({
  projectConfig: {
    ...
  },
  plugins: [
    {
      resolve: "@tinloof/medusa-manual-product-sorting",
      options: {},
    },
  ],
})

3. Start your server

yarn dev

Events

products.sorted

Emitted when products are successfully sorted within a category.

Event Data:

{
  products: ProductTypes.UpsertProductDTO[];
  id: string; // category ID
}

Using the Rank Attribute

After sorting products in the admin UI, the plugin stores the sort order in the product's metadata under the rank property. This allows you to fetch products in their custom sorted order.

How Rank is Stored

The rank is stored in the product metadata as a nested object:

{
  metadata: {
    rank: {
      [categoryId]: "00",  // Zero-padded string
      [collectionId]: "01",
      // ... different ranks for different categories/collections
    }
  }
}

Each category or collection has its own rank value, allowing the same product to have different positions across different categories.

Using Rank in Storefront

You can use the rank attribute in your storefront to display products in the order set by your merchandising team:

// Fetch products from a category in their custom order
const products = await medusa.products.list({
  category_id: categoryId,
  order: `metadata.rank.${categoryId}`,
});

// Display products in the sorted order
products.forEach((product) => {
  // Render product
});