Image Overlay

5 min read Updated

The Image Overlay addon shows an image’s title in a colored overlay on top of the image. By default, the overlay shows when a visitor hovers over the image. It works with three SiteOrigin widgets: Image, Image Grid and Simple Masonry. For the widgets’ other settings, see their documentation.

View the Image Overlay demo.

Requirements

Go to SiteOriginPremium Addons and activate Image Overlay. This also activates the Image and Image Grid widgets. To use the overlay with Simple Masonry, activate the Simple Masonry widget at PluginsSiteOrigin Widgets.

Overlay Text

The overlay shows the image’s title. An image with no title gets no overlay. The addon takes the title from the first of these that has text:

  1. The title field in the widget: Title text in the Image widget, Image title in each Image Grid image, or Title in each Simple Masonry image.
  2. The image’s Caption in the Media Library.
  3. The image’s Title in the Media Library. WordPress sets this title from the file name when you upload the image. The addon doesn’t use a title that is the same as the file name.

Widget Settings

The addon turns the overlay on for all three widgets by default. To change it for one widget, open the Image Overlay section at the bottom of the widget form.

The Image Overlay section at the bottom of the Image Grid widget form

Enable Image Overlay
Use global setting, Enabled or Disabled. Use global setting follows Enabled SiteOrigin Widgets in the global settings. Default: Use global setting.

Overlay Theme
Use global setting, Light or Dark. Light and Dark replace five global settings for this widget: the overlay color, overlay opacity (0.8), text size (15px), text padding (22px) and text color. Light uses a white overlay with black text. Dark uses a black overlay with white text. Hidden when Enable Image Overlay is Disabled. Default: Use global setting.

Global Settings

Go to SiteOriginPremium Addons and click Settings on the Image Overlay card. These settings apply to every overlay on the site. The form shows them in one list, in the order below. The headings on this page only group them.

The Image Overlay addon settings with the enabled widgets, overlay color, opacity, position, size and desktop trigger

Enabled SiteOrigin Widgets
The widgets that show the overlay by default: Image, Image Grid and Simple Masonry. You can still turn the overlay on or off in each widget. Default: all three.

Preset themes
Dark or Light. Choose a preset to fill in the overlay color, overlay opacity, text size, text padding and text color below. You can change the values after that.

Delay before showing overlay (in milliseconds)
Default: 300. At the moment, this setting has no effect. The overlay starts to show as soon as the pointer is over the image.

Overlay

Overlay color
Default: #000000.

Overlay opacity
From 0 (clear) to 1 (solid). Default: 0.8.

Overlay position
The edge of the image the overlay covers: Top, Right, Bottom or Left. Default: Bottom.

Overlay size
The size of the overlay as a fraction of the image’s size, from 0 to 1. For example, 0.3 covers 30% of the image height when the position is Top or Bottom. Set it to 1 to cover the whole image. Default: 0.3.

When the Overlay Shows

The addon uses the screen width, not the device type. On screens at least as wide as Touch device width, the desktop trigger applies. On narrower screens, the touch trigger applies.

Desktop device trigger
Show on hover, Hide on hover or Always show. Hide on hover shows the overlay until the visitor hovers over the image. Default: Show on hover.

Touch device show trigger
Show on touch or Always show. With Show on touch, a tap shows the overlay and the next tap hides it. Default: Show on touch.

Touch device width
The screen width where the touch trigger stops and the desktop trigger starts. Default: 1024px.

At the moment, when Overlay animation is None, Hide on hover shows no overlay, and a second tap doesn’t hide the overlay. Use one of the animations with these triggers.

Animation

Overlay animation
How the overlay appears: None, Fade, Slide or Drop. Slide moves the overlay in from the edge set in Overlay position. Drop fades the overlay in as it shrinks slightly to its full size. Default: Fade.

Animate overlay when image enters screen
Meant to play the overlay animation when the image scrolls into view. It needs the device trigger for that screen width set to Always show. At the moment, when this setting is on and the trigger is Always show, the overlay doesn’t show at all. Leave it off. Default: off.

Text animation
A second animation for the text. It plays after the overlay animation ends: None, Fade, Slide Left, Slide Right, Slide Up, Slide Down or Drop. At the moment, it plays only on screens narrower than Touch device width. Default: None.

Text

Font family
The font of the overlay text. Leave it empty to use the theme font.

Text size
Default: 15px.

Text color
Default: #fff.

Text padding
The space around the text: top, right, bottom and left. Default: 22px on each side.

Text position
The vertical position of the text in the overlay: Top, Bottom or Middle. Default: Middle.

Text alignment
Left, Right or Center. Default: Left.

Advanced Customizations

Add PHP snippets with a plugin such as Code Snippets, or in a child theme’s functions.php file.

Use the Alt Text for the Overlay Text

This snippet shows the Image widget’s Alt text in the overlay in place of the title. It works only for the Image widget. The image must still have a title, because the addon adds an overlay only to images with a title.

function so_image_overlay_use_alt( $data, $instance, $widget ) {
	if ( ! empty( $instance['alt'] ) && ! empty( $data['overlay-settings'] ) ) {
		$overlay_settings = json_decode( $data['overlay-settings'], true );
		$overlay_settings['overlay_text'] = esc_html( $instance['alt'] );
		$data['overlay-settings'] = json_encode( $overlay_settings );
	}
	return $data;
}
add_filter( 'siteorigin_premium_image_overlay_wrapper_data', 'so_image_overlay_use_alt', 10, 3 );