strapi-plugin-media-preview

A production-ready Strapi 5 plugin that enhances the Content Manager with powerful media preview capabilities. Preview any media file directly in a modal, access all media from the edit view header, and view media files in list view columns.

✨ Features

Edit View

• 🎯 Media Preview Button: Single button in the edit view header to preview all media files on the page
• 🖼️ Modal Preview: View images, videos, and PDFs directly in a beautiful modal
• 🔄 Smart Detection: Automatically finds all media files in the current entry
• 📊 Fallback Support: Falls back to DOM scanning if API fetch fails

List View

• � Media Column: Custom column showing all media files for each entry
• 🎨 Dropdown Interface: Clean dropdown to select and preview files
• 🚀 Quick Preview: Click any file to open it in a modal with full preview support

General

• 🔍 Preview any file type: images, PDFs, videos, audio, and more
• 🔗 Smart URL resolution: handles both absolute and relative URLs
• 🌙 Dark/light mode compatible (uses Strapi Design System)
• ⚡ Zero configuration — plug and play
• 🏗️ Non-destructive: adds UI only, never modifies core behavior
• 🔒 Safe: opens files with noopener,noreferrer security attributes
• 🎨 Modern UI: Built with Strapi Design System components

📋 Requirements

| Dependency | Version | |---|---| | Strapi | ^5.0.0 | | Node.js | >=18.0.0 | | React | ^18.0.0 |

🚀 Installation

1. Install the package

npm install strapi-plugin-media-preview
# or
yarn add strapi-plugin-media-preview
# or
pnpm add strapi-plugin-media-preview

2. Register the plugin in your Strapi config

Edit config/plugins.ts (or config/plugins.js):

// config/plugins.ts
export default () => ({
  'media-preview': {
    enabled: true,
  },
});

3. Rebuild and restart Strapi

npm run build
npm run develop

That's it! Navigate to any content type with a media field — you'll see the 👁️ preview button beside each uploaded file.

🖼️ How It Works

Edit View - Media Preview Button

In the Content Manager edit view:

1. A "Media Preview" button appears in the header (right-links area)
2. Clicking the button opens a modal that displays all media files in the current entry
3. The plugin fetches media via the Strapi Content Manager API
4. If API fetch fails, it falls back to DOM scanning to find media files
5. Media files are displayed in a grid with preview capabilities:
   • Images: Display inline with full resolution
   • Videos: Embedded video player with controls
   • PDFs: Embedded PDF viewer
   • Other files: Link to open in new tab

List View - Media Column

In the Content Manager list view:

1. A custom "Media" column is automatically added to all content types
2. Each row shows a dropdown with the count of media files (e.g., "3 files")
3. Clicking the dropdown reveals all media files for that entry
4. Selecting a file opens it in a modal preview
5. The modal provides the same preview experience as the edit view

URL Resolution

The plugin handles URLs safely:

| URL Type | Behavior | |---|---| | Absolute (https://...) | Used directly | | Relative (/uploads/...) | Prepended with backend origin | | Null/undefined | Skipped |

🏗️ Architecture

The plugin uses a multi-layer injection strategy for maximum compatibility:

Layer 1: Edit View Header Injection
├── Injects MediaPreviewButton into CM edit view header
├── Button opens MediaPreviewModal on click
├── Modal fetches media via Content Manager API
└── Falls back to DOM scanning if API fails

Layer 2: List View Column Injection
├── Registers hook for Admin/CM/pages/ListView/inject-column-in-table
├── Adds custom "Media" column to all content types
├── MediaColumnCell component renders dropdown
└── Dropdown opens MediaFilePreviewModal for selected files

Plugin Structure

strapi-plugin-media-preview/
├── admin/
│   └── src/
│       ├── index.ts                         # Plugin registration & bootstrap
│       ├── pluginId.ts                      # Plugin ID constant
│       ├── types.ts                         # TypeScript interfaces
│       ├── components/
│       │   ├── MediaPreviewButton.tsx       # Edit view header button
│       │   ├── MediaPreviewModal.tsx        # Main modal with API fetch
│       │   ├── MediaColumnCell.tsx          # List view column cell
│       │   ├── MediaFilePreviewModal.tsx    # Single file preview modal
│       │   ├── MediaFieldController.tsx     # Legacy DOM observer
│       │   ├── PreviewButton.tsx            # Core preview button
│       │   └── MediaAssetPreviewActions.tsx # Asset preview wrapper
│       ├── hooks/
│       │   └── useBackendUrl.ts             # Backend URL resolution
│       └── utils/
│           └── url.ts                       # URL utilities
├── package.json
├── tsconfig.json
├── plugin.config.ts
└── README.md

⚙️ Configuration

No configuration is required. The plugin works out of the box.

Environment Variables

The plugin auto-detects the backend URL using:

1. window.__STRAPI_ADMIN_BACKEND_URL__ (injected by Strapi admin at runtime)
2. window.location.origin (fallback)

For custom deployments where the backend and admin are on different origins, ensure STRAPI_ADMIN_BACKEND_URL is set in your Strapi environment:

# .env
STRAPI_ADMIN_BACKEND_URL=https://api.yourdomain.com

🛡️ Security

• Files open with rel="noopener noreferrer" equivalent (window.open with 'noopener,noreferrer')
• No user data is transmitted — the plugin only reads file.url from the already-loaded field value
• No backend endpoints are added
• No database changes

🤝 Compatibility

| Strapi Version | Status | |---|---| | 5.x | ✅ Supported | | 4.x | ❌ Not supported (use a Strapi 4 compatible version) |

� Troubleshooting

Media Preview button not appearing in edit view

1. Ensure the plugin is enabled in config/plugins.ts
2. Rebuild the admin panel: npm run build
3. Restart Strapi: npm run develop
4. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
5. Check browser console for warnings

Media column not appearing in list view

1. Ensure you're using Strapi 5.0.0 or higher
2. Rebuild both plugin and admin: npm run build in both directories
3. The column should appear automatically on all content types

Modal shows "No media found"

This can happen if:

• The entry has no media fields
• Media fields are empty
• The API fetch failed and DOM scan found nothing

Check the browser console for error messages.

Preview shows wrong URL or 404

Check your STRAPI_ADMIN_BACKEND_URL environment variable:

# .env
STRAPI_ADMIN_BACKEND_URL=https://api.yourdomain.com

For local development, the default is http://localhost:1337.

PDF Preview blocked by Content Security Policy (CSP)

If you see an error like violates the following Content Security Policy directive: "default-src 'self'" when previewing PDFs, you need to update your Strapi security middleware.

Edit config/middlewares.ts (or config/middlewares.js):

export default ({ env }) => [
  // ...
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': ["'self'", 'data:', 'blob:', 'https:'],
          'media-src': ["'self'", 'data:', 'blob:', 'https:'],
          'frame-src': ["'self'", 'https://your-media-domain.com'], // Add your media domain here
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
];

TypeScript errors

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

And you're using TypeScript 5+.

Code Standards

• Follow TypeScript best practices
• Use Strapi Design System components
• Write clean, documented code
• Test thoroughly before submitting

🙏 Acknowledgments

Built with ❤️ for the Strapi community.

Special thanks to:

• The Strapi team for the amazing CMS
• All contributors and users of this plugin

📄 License

MIT © 2026

See LICENSE for more information.

Made with ❤️ for Strapi 5