Diapo Slideshow is a Joomla site module that turns a set of images into a finished, touch-friendly slideshow. Add slides, pick Overlay, Split, or Stacked, then publish it in a module position.

Live demo: demo.joomlax.com/demo/utilities/diapo-slideshow

What you can do

• Load slides from Media Manager rows, a folder under images/, or article intro images
• Choose Overlay (caption on the image), Split (image plus a caption panel), or Stacked (image then caption)
• Use fade, slide, zoom, or no transition, plus optional Ken Burns
• Pick dark, light, or auto theme, then optionally add accent, radius, frame, divider, or shadow
• Show side or bar arrows, bars / dots / numbers, a counter, thumbs, play / pause, progress, and fullscreen
• Keep keyboard, swipe, RTL, and reduced-motion support from the bundled engine

What it is not

• Not Coda Slider (that product is tabbed article / HTML panels)
• Not a YouTube, Vimeo, or MP4 slider
• Not a lightbox gallery or a 29-effect pack

Built for modern Joomla

• Joomla 4.4 or later, Joomla 5, and Joomla 6
• PHP 8.1 or later
• Native JavaScript (no jQuery)
• Web Asset Manager CSS and JS

Check your site meets these needs before you install.

Before you install

• Joomla: 4.4 or later, 5.x, or 6.x
• PHP: 8.1 or newer
• Access: Super User or administrator to install modules
• Images: JPEG, PNG, GIF, WebP, or AVIF in Media Manager or under images/

Helpful but optional

• A template module position for a hero, mainbody, or sidebar
• Published articles with intro images if you use the article source

Not required

• jQuery
• A component or plugin
• A page builder

Install one package zip from the Joomla administrator.

Step 1: Download

After purchase, download DiapoSlideShow_UNZIP.zip from your email or the Downloads section.

Step 2: Unzip on your computer

1. Extract DiapoSlideShow_UNZIP.zip.
2. Inside you should see:
   • pkg_diaposlideshow_3.5.0.zip (install this one)
   • ReadMe.txt

Step 3: Install in Joomla

1. Log in to the Joomla administrator.
2. Go to System > Install > Extensions.
3. Click Upload Package File.
4. Choose pkg_diaposlideshow_3.5.0.zip and wait for the success message.
5. Clear Joomla cache: System > Maintenance > Clear Cache.

What the package installs

• mod_diaposlideshow: the site module
• Media assets under media/mod_diaposlideshow/ (CSS, JS, Web Asset Manager entry)

Updates

Install a newer pkg_diaposlideshow zip the same way. The package uses method="upgrade", so your module settings stay safe.

You can finish a homepage hero in a few minutes.

1. Create the module

1. Go to Content > Site Modules > New.
2. Choose Diapo Slideshow.
3. Set a Title, for example Home Slideshow.
4. Pick a Position that exists in your template.
5. On Menu Assignment, choose the pages where it should appear.
6. Set Status to Published.

2. Add slides

1. Open the Slides tab.
2. Leave Slide source on Manual slides.
3. Click Add and pick at least three images from Media Manager.
4. Fill Alt text. Add an optional eyebrow, title, description, and link.

3. Keep the hero defaults

1. Display: Layout Overlay, Theme Dark, Aspect ratio 16/9.
2. Motion: Transition Fade. Set Autoplay to 5000 if you want it to move on its own.
3. Controls: Arrows Over the image, Pagination Bars, Counter Yes.

4. Save and check the front end

1. Click Save.
2. Open the assigned page in a normal browser tab.
3. Clear cache and hard-refresh (Ctrl+F5) if the look seems stale.

Student tip

Change one field, Save, then refresh the front end. That is the fastest way to learn what each option does.

Open the module and click the Slides tab. This is where the images come from.

Manual slides

Default source. Each row can have:

• Image (required): Media Manager file or an http(s) image URL
• Alt text
• Eyebrow, Title, Description: plain text. Empty fields leave no hole in the caption
• Link: optional URL. Internal paths such as /about are allowed. javascript: links are rejected
• Link target: Same window or New window. New window adds rel="noopener"
• Slide interval (ms): 0 uses the module interval. A positive value overrides autoplay for that slide only

Use Add, Remove, and Move to reorder rows. Rows with a missing image are skipped.

Image folder

• Set Slide source to Image folder
• Pick a folder under images/
• JPEG, PNG, GIF, WebP, and AVIF files load in filename order
• The filename becomes the alt text. Folder slides have no captions in 3.5

Joomla articles

• Set Slide source to Joomla articles
• Pick one or more categories, a count (1 to 30), order, and featured filter
• Each slide uses the intro image, title, introtext (plain), and article URL
• Items with no intro image are skipped
• Exclude current article hides the article being viewed

Empty source

If no slides remain after skipping bad rows, the module renders nothing. You will not see empty chrome or a JavaScript error.

The Display tab controls layout, theme, and framing.

Layouts

• Overlay: caption sits on the image with a gradient. Default homepage hero
• Split: image stage plus a caption panel. Choose panel Right or Left. The two columns stack when the module is under 640px wide, including a narrow sidebar
• Stacked: image first, then the caption below

Theme

• Dark (default), Light, or Auto (follows the visitor colour scheme)

Size

• Aspect ratio: example 16/9. Leave empty for the engine default
• Small-container ratio: used when the module is under 640px wide. Example 4/3
• Height: optional CSS length such as 70vh or 480px. Overrides the ratio when set
• Image fit: Cover (default) or Contain
• Image position: CSS object-position, for example center or top

Chrome (off by default)

• Corner radius: 0 is square. Set 8px or 12px only if you want a card
• Outer frame: None (flush with the page) or Thin (1px outline)
• Panel divider: None, or a thin line between image and caption in Split and Stacked
• Shadow: None or Soft
• Line colour: optional colour for frame and divider

Brand

• Accent colour
• Optional background, text, and panel background colours

Fonts inherit from the template. There is no font picker.

The Motion tab controls how slides change.

• Transition: Fade (default), Slide, Zoom, or None
• Duration (ms): default 700. None forces 0
• Ken Burns: slow pan and zoom on the image. Off by default
• Autoplay (ms): 0 turns autoplay off. A positive number is the interval, for example 4500
• Default interval (ms): used when autoplay is on and a slide has no own interval (default 5000)
• Loop: Yes by default
• Start index: 0 is the first slide
• Pause on hover / focus / when hidden: Yes by default. Hidden covers a background tab and a slideshow that scrolled off screen

Visitors who prefer reduced motion get no slide animation. That comes from the engine, not a separate admin switch.

The Controls tab turns chrome on or off.

• Arrows: Over the image (default), Control bar, or No
• Pagination: Bars (default), Dots, Numbers, or No
• Counter: 01 / 04 style. On by default
• Thumbnails: Off by default
• Play / pause: Auto (shows when autoplay is on), Yes, or No
• Fullscreen: Off by default. Hidden automatically if the browser has no Fullscreen API
• Progress bar: optional line across the top
• Captions: On by default
• Title tag: H2, H3 (default), or H4

When only one slide remains, the engine hides navigation chrome.

The Advanced tab is for behaviour and Joomla module chrome.

Diapo behaviour

• Keyboard: arrows, Home, End, and Space to toggle play when the slideshow is focused
• Swipe: drag on touch devices
• Swipe threshold (px): default 40
• Preload neighbours: Active only, One either side (default), Two either side, or All slides

Joomla fields

• Alternative layout
• Module Class Suffix
• Caching / Cache Time: HTML is static. Motion runs in the browser, so page cache is safe

Template override

Site templates can set CSS variables on .mod-diaposlideshow:

.mod-diaposlideshow {
  --diapo-accent: var(--template-color-primary, #0f766e);
  --diapo-font: inherit;
  --diapo-radius: 0;
  --diapo-border: none;
}

After the module is published and assigned, open that page like a visitor.

Checklist

1. Status is Published, Position is correct, and Menu Assignment matches the page.
2. At least one slide has a real image.
3. Clear Joomla cache, then hard-refresh (Ctrl+F5).
4. Focus the slideshow and use the arrow keys. On a phone, swipe.

Live demo variants

The public hub at demo.joomlax.com/demo/utilities/diapo-slideshow includes Overlay, Split, Stacked, Folder, and Articles.

Several modules on one page

Each instance uses its own root id (diapo-{moduleId}). Two slideshows on one page run independently.

Fixes for the most common Diapo Slideshow problems.

• Nothing appears

  • Check Published, Position, and Menu Assignment. Confirm at least one slide has an image. An empty source renders nothing on purpose.

• Images stack with no arrows or captions

  • The CSS or JS did not load. Confirm media/mod_diaposlideshow/css/diapo.min.css and js/diapo.min.js exist. Clear Joomla cache and hard-refresh.

• Folder source is empty

  • Pick a folder under images/ that contains JPEG, PNG, GIF, WebP, or AVIF files. Other file types are ignored.

• Article source is empty

  • The category needs published articles with intro images. Items without an intro image are skipped.

• Split looks crushed in a sidebar

  • Split stacks when the module is narrow. That uses a container query, not the window width. If it still looks crushed, hard-refresh so the stylesheet is current.

• Autoplay never starts

  • Autoplay is 0 (off) by default. Set a positive number such as 5000. Play / pause Auto only shows the button when autoplay is on.

• Language keys show as MOD_DIAPOSLIDESHOW_*

  • Reinstall the package so language files copy, then clear cache.

• Old look after a change

  • Save the module, clear Joomla cache, then Ctrl+F5.

Need help? Open a ticket on the JoomlaX support portal.

Open a support ticket

Please include:

• Joomla, PHP, and Diapo Slideshow versions
• Template name
• Slide source (manual, folder, or articles)
• Layout (overlay, split, or stacked)
• Whether the slideshow is missing, stacking as raw images, or not changing slides
• The page URL