Get Started

Easy Image Overlay is a Joomla system plugin that adds text and Font Awesome icon overlays to images using shortcodes. Markup uses a modern CSS Grid wrapper (jx-imageoverlay-wrapper), optional caption alignment, hover animations (fade, slide-up, zoom-in), and vanilla JavaScript—no jQuery required on the front end.

Key highlights

• Joomla 4, 5 and 6 compatible; WebAssetManager for CSS/JS
• Shortcode attributes for colours, opacity, typography, padding, size, link, icon, always-on overlay
• overlayalign: top, center, bottom, left, right
• overlayeffect / overlayduration: fade, slide-up, zoom-in; duration e.g. 300ms or 0.5s
• Assets load only when {imageoverlay} tags are detected
• Input sanitisation for paths, URLs, colours and sizes
• Shortcode Examples tab in the plugin with one-click copy

Downloading the Extension

Email: After you purchase the extension from our store, you will receive an email containing a link to download the extension.

Store: Alternatively, you can download the extension from the "Downloads" section in our store. If you are a new user, you need to create an account using the same email address you used for the purchase.

Click to download the extension package: EasyImageOverlay_UNZIP.zip

Unzipping the Package

Use any file unzipper tool or WinRAR to unzip the EasyImageOverlay_UNZIP.zip package. After unzipping, you will find the following contents:

• plg_system_imageoverlay_X.x.zip: This is the installation file compatible with Joomla 4.x, 5.x, and 6.x.
• ReadMe.txt: Contains vital information about the current version of the extension.

Installing the Extension

To install the extension, log in to the backend of your Joomla website.

• For Joomla 4, 5 & 6: Navigate to Extensions > Manage > Install, then click on the "Upload Package File" tab. Click "Browse" to select the appropriate installation file (plg_system_imageoverlay_X.x.zip), then click "Upload and Install."

A success message will be displayed once the installation is complete.

Enabling the Plugin

After installation, navigate to Extensions > Plugins, search for "System - Easy Image Overlay", and click on it to enable and configure the plugin.

Access the plugin settings by navigating to Extensions > Plugins, and find System - Easy Image Overlay in the list.

General settings

• Link Target Behavior: Controls how url links open—New Tab (_blank) or Same Page (_self). This is a global plugin option, not a shortcode attribute.
• Load Font Awesome Icons: Turn on to load Joomla’s Font Awesome stylesheet when overlays are used. Set to No if your template already loads it.
• Custom CSS Styles: Raw CSS injected into the page head when a shortcode is present. Target the public markup classes (all prefixed with jx-), for example:
  • .jx-imageoverlay-wrapper — outer grid wrapper (inline-grid, overflow: hidden)
  • .jx-imageoverlay-link — anchor when url is set
  • .jx-imageoverlay-img — image
  • .jx-imageoverlay — hover overlay layer; .jx-imageoverlay-on — always-visible overlay
  • .jx-imageoverlay-container / .jx-imageoverlay-content — caption layout
  • Utilities: .jx-img-left, .jx-img-right, .jx-img-margin-*, .jx-img-padding-*
  Example: .jx-imageoverlay-wrapper { margin: 10px; }

Shortcode Examples tab

The plugin configuration includes a Shortcode Examples tab with ready-made samples and a Copy button. Use the tab for the full list; below is a concise reference.

Syntax

{imageoverlay image="path/to/file.jpg" ...optional attributes...}{/imageoverlay}

Helper (optional): {clearfix} inserts a clearing element after floated rows.

Requirements

image is required. At least one of overlaytext or icon must be present or the overlay block is not output.

Examples

Basic
{imageoverlay image="images/sample.jpg" overlaytext="View" overlayopacity="0.5"}{/imageoverlay}

Link + icon
{imageoverlay image="images/sample.jpg" url="https://example.com" overlaytext="Visit" icon="fa-external-link"}{/imageoverlay}

Caption at bottom + slide animation
{imageoverlay image="images/sample.jpg" overlaytext="Caption" overlayalign="bottom" overlayeffect="slide-up" overlayduration="600ms"}{/imageoverlay}

Always visible
{imageoverlay image="images/sample.jpg" overlaytext="Label" overlay="true" overlayopacity="0.85"}{/imageoverlay}

Parameters

• image — Path relative to site root (required)
• overlaytext — Caption text (optional if icon is set)
• icon — Font Awesome class, e.g. fa-search
• url — Makes the image a link; target from plugin setting
• alt — Image alternative text
• class — Extra classes on the wrapper
• overlaybgcolor — #hex, rgb(), or rgba()
• overlaytextcolor — Same colour rules
• overlayopacity — Number from 0 to 1 (overlay tint strength)
• overlayfontsize — e.g. 14px, 1.2rem
• overlaypadding — e.g. 12px, 1rem
• overlayalign — top, center, bottom, left, right
• overlayeffect — fade, slide-up, zoom-in (hover overlays)
• overlayduration — e.g. 300ms, 0.5s
• overlay — true for always-visible overlay (no hover)
• imgwidth / imgheight — Size with unit: px, %, em, rem, vh, vw

Where to use

Articles, custom HTML modules, and any content area that renders the shortcodes as plain text in the final HTML output.

Core features

• Text and icon overlays with colours, opacity, font size and caption padding
• Caption alignment inside the overlay (overlayalign)
• Hover animations: fade, slide-up, zoom-in with configurable duration
• Always-on mode via overlay="true"
• Clickable images with sanitised URLs
• Grid-based layout for reliable stacking; multiple instances side by side align to the top
• Conditional assets: CSS and JS load only when overlay shortcodes are on the page
• Front-end script: vanilla JavaScript (no jQuery dependency for this plugin)

Developer-oriented

• Namespaced CSS classes (jx- prefix) for safer styling alongside templates
• Sanitisation for paths, URLs, colours, dimensions and text
• WebAssetManager registration for Joomla 4+

Compatibility

• Joomla 4, 5 and 6
• PHP 8+ style codebase in the plugin package

• Where are the examples?

  • Open the plugin and use the Shortcode Examples tab; each block has a Copy button.

• Why is my link always opening in a new tab (or not)?

  • Link target is controlled only by Link Target Behavior in the plugin options, not in the shortcode.

• Why does overlaypadding not accept random text?

  • Values must look like a CSS length, e.g. 16px or 1rem.

• How do I place the caption at the bottom or top?

  • Use overlayalign="bottom" or overlayalign="top" (also left, right, center).

• Slide-up or zoom does nothing

  • Set overlayeffect="slide-up" or zoom-in. Use overlayduration to slow or speed the transition. Always-on overlays do not use hover animation.

• Two images in a row looked misaligned

  • The wrapper uses vertical-align: top so different image heights line up at the top.

• Does overlay work on touch devices?

  • Hover is primarily for pointers with hover; on many phones the overlay may not behave like desktop hover—consider overlay="true" where you need the caption always visible.

• Which Joomla versions?

  • Joomla 4.x, 5.x and 6.x are supported.

Common issues

• Nothing renders

  • Plugin enabled; shortcode spelled {imageoverlay ...}{/imageoverlay}
  • image path exists under the site root
  • Include overlaytext and/or icon
  • Clear Joomla and browser cache

• Overlay solid black

  • Lower overlayopacity (e.g. 0.5). The script fades to that value on hover, not to full opacity.

• Icons missing

  • Enable Load Font Awesome Icons or use a template that already provides Font Awesome; icon class form fa-search (paired with icon="fa-search").

• Custom CSS ignored

  • Use jx- class names; old names like eImageoverlay are no longer used.

• Assets not loading

  • Occurs only when the rendered page contains valid {imageoverlay} / closing tags; check the final HTML output.

• Shortcode Examples tab missing

  • Confirm fields/shortcodes.php is installed and the manifest lists the fields folder; clear cache.

Support

https://support.joomlax.com