UI Elements Display Lightbox

Updated: March 8, 2023
SAPUI5 Version 1.106

Lightbox

sap.m.LightBox

Intro

The lightbox control allows the user to view an image in its original size. This control displays the image in a popup while dimming the rest of the screen.

Usage

Use the lightbox if:

  • The thumbnail view is not detailed enough, and it would help the user to see the image in its original size.
  • The original size of the image is bigger than the thumbnail.

Do not use the lightbox if:

  • The image you are using is smaller than or as big as the thumbnail.
  • There is another click event attached to the image control.
  • You are using an image placeholder to display the object.

Responsiveness

The lightbox container is displayed in the middle of the screen.

The image is displayed in its original size unless the original image size is bigger than the size of the screen. In this case, the image is resized proportionally in order to be fully visible and fit on the screen.

On a mobile device, flipping the device to landscape mode will flip the lightbox. The image will then be adjusted to fit the new dimensions.

Lightbox - Size S
Lightbox - Size S
Lightbox - Size M
Lightbox - Size M
Lightbox - Size L
Lightbox - Size L

Components

The lightbox contains the following components:

  • Lightbox container: This is the main container that holds all other components.
  • Image: This component is an embedded image control that displays the image file with the maximum available size. The size of the image should not exceed the original size and it should fit within the screen.
  • Image title: This component is mandatory and is used to describe the object to which the image is attached.
  • Image subtitle: This component is optional and is used to give additional information about the object.
  • Close button: This is a mandatory component and is used to close the lightbox container.
The components of the lightbox
The components of the lightbox

Behavior and Interaction

Basic Interactions

The lightbox control is attached to the press event of the image control. To trigger the lightbox, the user should click an image. Every image with an attached lightbox control is indicated with a zoom icon on the bottom right.

Lightbox - Zoom icon
Lightbox - Zoom icon

When the lightbox control is triggered, the lightbox overlays the page content and the rest of the screen is dimmed out.

If it takes more than one second to load the original image, a busy indicator is shown inside the lightbox container.

The user can close the lightbox by clicking the Close button or by clicking outside of the lightbox container.

Lightbox - Basic interactions
Lightbox - Basic interactions
Lightbox - Image loading
Lightbox - Image loading

Error Handling

An error message is displayed inside the lightbox when:

  • The original file is missing or the connection to the server is lost.
  • The image takes more than 10 seconds to load due to a server error or the size of the image.
Developer Hint
The URL of the image is mandatory. If it is not specified, the lightbox will not be triggered.
Lightbox - Error message
Lightbox - Error message

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation