Overview

The Media Groups Plugin enables admin users to assign specific images to product variants or options (like colors). This allows for a more organized product page where selecting a variant shows only the relevant images.

This plugin leverages Medusa's native product variant images feature, providing a user-friendly interface to manage image associations directly from the product detail page.

Features

• Variant-specific images - Assign images to individual product variants using Medusa's native variant images
• Option-based grouping - Group images by option values (e.g., assign images to all "Blue" variants at once)
• Batch updates - Efficient updates for multiple variants sharing the same option
• Drag-and-drop interface - Easily reorder images and drag between available and assigned sections
• Thumbnail management - First image in the list automatically becomes the variant thumbnail
• Image ordering - Custom image order stored in variant metadata
• Admin widget integration - Manage media groups directly from the product detail page

Installation

1. Install the Media Groups plugin

yarn add @tinloof/medusa-media-groups

or

npm install @tinloof/medusa-media-groups

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

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

3. Start your server

yarn dev

How It Works

This plugin uses Medusa's built-in product variant images relationship. When you assign images to a variant:

1. Images are linked to variants using Medusa's batchVariantImagesWorkflow
2. The first image in the list is automatically set as the variant's thumbnail
3. Image order is preserved in the variant's metadata.images_order field

API Reference

Batch Update Variant Images

POST /admin/products/:id/variants/batch/media-groups

Updates images for multiple variants in a single request.

Body Parameters:

{
  updates: Array<{
    variantId: string; // ID of the variant to update
    add?: string[]; // Array of image IDs to add
    remove?: string[]; // Array of image IDs to remove
    thumbnail?: string | null; // URL of the thumbnail image
    metadata?: Record<string, unknown>; // Additional metadata (e.g., images_order)
  }>;
}

Exported Workflows

batchVariantImagesWorkflow

A workflow that wraps Medusa's core batchVariantImagesWorkflow to handle batch updates for multiple variants.

import { batchVariantImagesWorkflow } from "@tinloof/medusa-media-groups/workflows";

await batchVariantImagesWorkflow(container).run({
  input: [
    { variant_id: "variant_123", add: ["img_abc"], remove: ["img_xyz"] },
    { variant_id: "variant_456", add: ["img_def"] },
  ],
});