Get Started

Photobox Gallery 2.0 is a responsive image gallery with a modern Photobox-style lightbox. Show a folder of photos (or hand-picked slides) in a masonry or uniform grid, then open a dark overlay with filmstrip, captions, and autoplay.

What do you get?

One install package with three parts:

1. Site module — drop a gallery in any module position
2. Content plugin — {photobox …} shortcodes in articles
3. Editor button — toolbar button that builds the shortcode for you

Highlights in 2.0

• Vanilla JS/CSS lightbox (jx-pbx prefix — no jQuery)
• Masonry layout (default) or uniform CSS grid
• OnClick or OnLoad opening behaviour
• Filmstrip, counter, captions, keyboard, swipe, autoplay
• Themes: Modern 2026, Minimal, Dark + accent colour
• WebP thumbnail cache under images/mod_photobox_cache/
• Folder mode or individual slides with custom captions

Works with

• Joomla 4, 5, and 6
• PHP 8.0+
• Phones, tablets, and desktops
• JPG, PNG, GIF, and WebP images

Tip: Start with the module for a menu page, or use the editor button to drop a shortcode into any article.

Step 1 — Download

1. After purchase, download pkg_photobox_2.0.zip (recommended).
2. Keep the zip file; do not unzip it unless the store told you to.

Step 2 — Install in Joomla

1. Log in to the Joomla administrator.
2. Go to System → Install → Extensions.
3. Open the Upload Package File tab.
4. Choose pkg_photobox_2.0.zip.
5. Click Upload & Install and wait for the green success message.

Step 3 — Enable the plugins

1. Go to System → Plugins.
2. Search for Photobox.
3. Enable:
   • Content - Photobox
   • Editor Button - Photobox

If a plugin shows a red X, click it so it becomes a green check. The module does not need enabling in Plugins.

Step 4 — Add your images

1. Go to Content → Media.
2. Create a folder, for example photobox (files live under images/).
3. Upload photos (JPG/PNG/WebP work best).
4. Optional: name files like Nature__mountain-lake.jpg so auto-captions look clean.

Quick start — Module

1. Go to Content → Site Modules → New → Photobox.
2. Images tab: Image Source = Folder, path = images/photobox.
3. Look & Feel: columns, masonry, theme, accent.
4. Assign a position and menu, Publish, Save.
5. System → Clear Cache, then view the front end.

Need help? support.joomlax.com

Open your Photobox module → Look & Feel tab.

• Theme — Modern 2026 (default), Minimal, or Dark.
• Accent Color — used for active filmstrip thumbs, control hover states, and accents (default #1819ed). Close-button hover uses this colour too.
• Gallery Width — e.g. 100% or 900px.
• Item Gap — spacing between thumbnails, e.g. 8px or 10.
• Columns — 2 to 6 columns (responsive: fewer on tablets/phones).
• Masonry Layout — Yes (default) for Pinterest-style flowing columns with natural image heights. No for a uniform CSS grid.

Masonry tips

• When masonry is on, thumbnails are resized by width only so heights stay natural.
• Mixed portrait and landscape photos show the effect best.
• Turn masonry off (Compact-style) when you want equal cells.

Open your Photobox module → Lightbox tab.

• Gallery Opening Behaviour
  • OnClick — lightbox opens when a visitor clicks a thumbnail (default).
  • OnLoad — first image opens automatically when the page loads.
• Enable Loop Navigation — wrap from last image back to first.
• Show Image Counter — e.g. 3 / 10 in the overlay.
• Show Filmstrip — thumbnail strip at the bottom of the lightbox.
• Autoplay — advance images automatically; visitors can pause with the play control.
• Autoplay Interval (ms) — delay between slides (min 500).
• Control Color — background for close / play / arrow buttons.

Lightbox interactions

• Keyboard: ← → navigate, Esc close, Space toggle autoplay
• Touch: swipe left/right
• Click backdrop or the close button to dismiss

Captions appear under the large image in the lightbox (not as a hover overlay on the grid).

Open your Photobox module → Images tab.

Image Source

• Folder — load every image from a path under Media (e.g. images/photobox).
• Slides — pick individual images and set custom captions.

Folder options

• Image Folder — path relative to the site root.
• Image Sort — A→Z, Z→A, or Random.
• WebP Thumbnails — store cached thumbs as WebP when PHP supports it.
• Resize Thumbnails By — Height, Width, or Both (when masonry is off).
• Thumbnail Width / Height — pixel size for the cache (defaults 720 × 480). With masonry on, only width is used.
• Auto Captions from Filename — builds captions from names; Category__Title.jpg uses the part after __.

Thumbnail styling

• Border colour, width, and radius
• Optional drop shadow
• Filter: none, grayscale, sepia, blur, brightness (clears on hover)

Slides mode

1. Set Image Source to Slides.
2. Click + to add rows: choose an image and enter a caption.
3. Drag rows to reorder.
4. Use Show Caption plus colour / size / weight for lightbox caption text.

Enable Content - Photobox, then insert a shortcode in any article (or use the Photobox editor button).

Basic example

{photobox folder="images/photobox" columns="3" masonry="1" thumbwidth="720"}

Common attributes

• folder — path under images/ (required for folder galleries)
• columns — 2–6
• gap — spacing in px
• masonry — 1 (default) or 0 for uniform grid
• theme — modern-2026 | minimal | dark
• accent — e.g. #1819ed
• thumbs — filmstrip 1 / 0
• counter — 1 / 0
• loop — 1 / 0
• autoplay — 1 / 0
• time — autoplay interval in ms
• start — 0 = OnLoad, omit or 1 = OnClick
• thumbwidth / thumbheight — cache size (thumbheight ignored when masonry is on)
• webp — 1 / 0

More examples

{photobox folder="images/photobox" columns="4" masonry="1" theme="dark" accent="#2dd4bf"}

{photobox folder="images/photobox" masonry="0" columns="4" gap="4" thumbwidth="560" thumbheight="374"}

{photobox folder="images/photobox" autoplay="1" time="2500" thumbs="1" loop="1"}

Editor button

In the article editor, click Photobox, fill folder / columns / masonry / theme, then Insert shortcode.

How caching works

On first view, Photobox creates resized thumbnails so pages stay fast. Originals in Media are never modified.

Cache location

images/mod_photobox_cache/ (plus a webp/ area when WebP is enabled).

Supported formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)

Rebuild / clear cache

1. Delete the folder images/mod_photobox_cache/ via FTP or Media (if visible).
2. Reload the page — files regenerate automatically.

Performance tips

• Upload reasonably sized originals (e.g. 1200–2000px wide).
• Use thumb width around 720 for sharp grid images.
• Enable WebP on live sites when available.
• Use minified CSS/JS on the Advanced tab for production.

Open your Photobox module → Advanced tab.

• Load Minified CSS/JS — smaller assets for live sites.
• Module Class Suffix — add a CSS class for custom styling.

Package contents

• mod_photobox — site module
• plg_content_photobox — shortcodes
• plg_editors-xtd_photobox — editor insert button

Install via pkg_photobox_2.0.zip.

Upgrading from 1.x

• Install the 2.0 package over the old module (upgrade method).
• Legacy folder/slides parameters are mapped automatically where possible.
• jQuery Photobox is no longer used — clear browser and Joomla cache after upgrade.

Troubleshooting

• Nothing renders — confirm the module is published and assigned to the menu; for shortcodes, enable Content - Photobox.
• Empty gallery — check the folder path and that images exist under images/.
• Soft thumbs — raise thumb width (e.g. 720), clear images/mod_photobox_cache/, hard-refresh.
• Masonry looks like a grid — source images may share the same aspect ratio; add mixed sizes or turn masonry off for a deliberate uniform grid.
• Editor button missing — enable Editor Button - Photobox and clear admin cache.

• What is Photobox 2.0?

  • A Joomla image gallery with a modern Photobox-style lightbox — module, content shortcode, and editor button in one package.

• Which Joomla versions are supported?

  • Joomla 4, 5, and 6. PHP 8.0+ required.

• Does it need jQuery?

  • No. Version 2.0 uses vanilla JS/CSS with the jx-pbx prefix.

• What is included in the package?

  • pkg_photobox_2.0.zip installs the site module, Content - Photobox, and Editor Button - Photobox.

• How do I use a shortcode?

  • Enable Content - Photobox, then use {photobox folder="images/photobox" columns="3" masonry="1"} or the Photobox editor button.

• What is OnLoad vs OnClick?

  • OnClick opens the lightbox when a thumb is clicked. OnLoad opens the first image automatically.

• Where do captions appear?

  • In the lightbox under the large image (not as a hover overlay on the grid).

• Where are cached thumbnails stored?

  • Under images/mod_photobox_cache/. Delete that folder to rebuild.

• Can I turn masonry off?

  • Yes — Look & Feel → Masonry Layout = No, or shortcode masonry="0".