Category Videos

Assign a video to any category and display it as an inline player or a full-width background hero on the category page — no coding required.

note

Available since v3.2.0

Overview

Category Videos lets you attach one video per category directly from the category edit form in your Back Office. When a customer visits that category, the video appears automatically according to the display settings you configure in the module. You choose per category whether the video is shown as a regular inline player (embedded at a specific position within the page) or as a cinematic background video that replaces the category header image.

This is useful for brand-story videos on landing categories, seasonal promotions, or product-range demonstrations that play before the product grid. Because each category is configured independently, you can have a hero video on a top-level category while child categories use an inline player or no video at all.

Two pieces of configuration work together: the global settings in the module (which control how all category videos behave) and the per-category assignment (which attaches a specific video URL and display mode to each category).

Configuration

Step 1 — Enable the feature

1. Go to Modules > Module Manager, find Product Video, and click Configure.
2. Open the Category Videos tab.
3. Toggle Enable Category Videos to Yes and click Save.

Without this master switch enabled, no category videos appear, even if videos are already assigned to categories.

Step 2 — Configure global display options

All settings below are in Modules > Module Manager > Product Video > Configure > Category Videos.

Regular (inline) mode settings

Field	Values	Default	Description
Enable Category Videos	Yes / No	No	Master switch for all category videos.
Video Position	Top, After description, After subcategories, After products, Custom selector	Top	Where on the page the inline player is inserted.
Custom Selector	CSS selector string	(empty)	Visible only when Video Position is set to Custom selector. Enter the CSS selector of the element after which the video should appear.
Regular video width	Number (px)	720	Width of the inline player in pixels.
Regular video height	Number (px)	405	Height of the inline player in pixels.

Background (hero) mode settings

These options only affect categories where the video is set to Background / hero mode.

Field	Values	Default	Description
Background height	Number (px)	400	Height of the full-width hero section in pixels.
Overlay color	Color picker	#000000	A color tint placed over the video. Set opacity to 0 to remove it entirely.
Overlay opacity	0–100 (%)	40	How opaque the color overlay is. 0 = completely invisible; 100 = fully covers the video.
Show category name	Yes / No	Yes	Overlays the category name as text on top of the background video.
Show category description	Yes / No	No	Overlays the category description text on top of the background video. Long descriptions are truncated at 200 characters.

The Category Header Selector under Theme Compatibility controls which element the background video replaces. The default (.page-category-heading,.category-cover) works with the Classic theme and most standard themes. If the background video does not appear, this is the setting to adjust.

Step 3 — Assign a video to a category

1. Go to Catalog > Categories in the Back Office.
2. Click Edit on the category you want to add a video to.
3. Scroll to the Video panel at the bottom of the category form.
4. Enter the Video URL (YouTube, Vimeo, or a direct video file URL).
5. Optionally enter a Title — this appears in the admin panel for identification only and is not shown to customers.
6. Choose the Display mode: Inline (regular) or Background / hero.
7. Click the Save button in the Video panel, then save the category form.

Repeat for each category that should have a video.

How It Works

When a customer opens a category page, the module checks whether a video has been assigned to that category. If one exists, it renders the video according to the chosen display mode.

Inline (regular) mode

The video is initially hidden in the page source and then moved into the correct position by a small JavaScript snippet that runs on DOMContentLoaded. The position is determined by the Video Position setting:

• Top — inserted after the page heading, before the category description
• After description — inserted below the category description block
• After subcategories — inserted below the subcategory grid
• After products — inserted below the product listing
• Custom selector — inserted after whichever element matches the CSS selector you specify

The inline player respects the Regular video width and Regular video height values you configure globally. YouTube and Vimeo videos are loaded via the module's existing player loaders; HTML5 video files render with native browser controls.

Background (hero) mode

The background video replaces your category's header image area. The module finds the header element using the Category Header Selector from Theme Compatibility settings, then renders the video behind a configurable overlay and optional text labels.

• YouTube background videos play automatically, muted, and loop continuously with controls hidden.
• Vimeo background videos use Vimeo's background=1 parameter for the same effect.
• HTML5 video files play with autoplay muted loop playsinline attributes.

The video is always scaled to cover the full container width without black bars, regardless of the video's native aspect ratio. On window resize the scaling recalculates automatically.

If no video is assigned to a category, nothing is output — no empty container, no placeholder space.

Usage Examples

Example: Brand introduction video on a top-level collection

You sell outdoor gear and want a 60-second brand film to play at the top of your "Hiking" category. Set the display mode to Inline (regular) with Video Position set to Top and dimensions of 1140 × 641 px (matching your theme's content column). Customers land on the page and see the film before the product grid, without leaving the category.

Example: Cinematic seasonal header on a sale category

For a "Summer Sale" category, you want a looping beach-lifestyle video instead of a static category image. Assign a YouTube URL with Display mode set to Background / hero, set the Background height to 500 px, enable Show category name, and set Overlay opacity to 50 so the "Summer Sale" text is readable against the video. The header image is automatically replaced by the video.

Example: Tutorial video after the product listing

You have a "Coffee Machines" category and want to show a buyer's guide video below all the products. Set Video Position to After products and use a Vimeo URL in the category's Video panel. Customers finish scanning the product grid and then see the tutorial.

Important Notes

• Only one video can be assigned per category. Assigning a new URL to a category that already has one overwrites the previous entry.
• The feature is compatible with PrestaShop 1.6 and 1.7+. On 1.7+ it uses displayCategoryAdditionalDescription; on 1.6 it uses displayHeaderCategory. Both hooks call the same rendering logic.
• Background mode is designed for YouTube, Vimeo, and HTML5 video files. Custom providers (configured under Additional Providers) are not supported in background mode — they fall back to an iframe, which may not fill the container correctly.
• Category Videos is a per-shop feature. If you run a multi-shop setup, video assignments and the global display settings are applied per-shop context. Switch shops before assigning videos or changing settings to ensure they take effect on the correct storefront.
• The description overlay in background mode strips HTML tags from the category description and truncates at 200 characters. If your category description is formatted with HTML, the overlay will show plain text only.
• If a custom CSS selector returns no matching element on the page, the video is still shown — it is displayed at its default rendered position in the page source rather than being repositioned.

Troubleshooting

Problem	Solution
Video does not appear on the category page	Confirm Enable Category Videos is set to Yes in the module settings. Also verify a video URL is saved on that specific category (edit the category and check the Video panel).
Background video shows but covers the wrong area	The Category Header Selector under Theme Compatibility does not match your theme's header element. Inspect the category page with your browser's developer tools to find the correct CSS selector and update it.
Inline player appears at the wrong position	Your theme may use different class names than the defaults. Switch Video Position to Custom selector and enter the exact CSS selector for your theme's description block or product list container.
Background video does not autoplay	Browsers require videos to be muted before allowing autoplay. YouTube and Vimeo backgrounds are always muted automatically. For HTML5 files, the muted attribute is set by the module. If autoplay still fails, check your browser's autoplay policy settings.
Category name or description text is unreadable over the video	Increase Overlay opacity so the tinted layer creates more contrast, or switch Overlay color to a shade that better complements your video content.
Video assigned but module was just installed — nothing shows	After installing or upgrading the module, clear your PrestaShop cache from Advanced Parameters > Performance so the new templates are picked up.

Frequently Asked Questions

Q: Can I use a different video for desktop and mobile? A: No. The same video URL is used across all screen sizes. For background mode, the module scales the video to fill the container at any viewport width, so the same clip works on both desktop and mobile.

Q: Does the category video show up in the product listings within that category? A: No. Category Videos only appears on the category page itself. To show videos within the product grid (on product cards), use the Product Listings feature instead.

Q: What happens if I delete a category that has a video assigned? A: The video assignment is stored with a reference to the category ID. Deleting the category through the Back Office removes the category record, and the orphaned video assignment will simply never be displayed (there is no category page to display it on). It does not cause any errors.

Q: Can I assign a video to the home category or the root category? A: Yes. Any category visible in Catalog > Categories can have a video assigned via the Video panel on its edit form, including the Home category if your theme renders it as a browsable category page.

Q: The background video flickers or has a brief white frame before playing. Is this normal? A: A brief delay before the video loads is normal, especially on slower connections. YouTube and Vimeo videos require the external player API to initialize. You can reduce the visual impact by increasing the Overlay opacity slightly, which hides the empty state before the video frame appears.

Q: Can I show a video on every category without assigning one individually? A: No. Videos must be assigned per category. There is no global fallback video that applies to all categories at once.

Q: Will the category video affect my page's SEO? A: The module outputs standard <iframe> and <video> elements — the same way any embedded video would appear. There is no special SEO treatment or Schema.org markup generated for category videos (that feature applies to product videos only).

Related Features

• Product Listings — Show video thumbnails or icons on product cards within the category grid
• Theme Compatibility — Adjust the Category Header Selector and other theme-specific CSS selectors