# Image gallery widget

You use this widget to display a gallery of image thumbnails, where each image can be opened individually. You choose an image from the images already uploaded in libraries.

> info **PREREQUISITES**: You uploaded at least one image. For more information, see [Upload images](https://www.progress.com/documentation/sitefinity-cms/upload-images).

After you place the *Image gallery* widget on your page, you configure it to display images. To do this, click the *Edit* button in the upper-right corner of the widget. The *Image gallery* window contains a few tab pages, described in the following sections.

### Select images to display

On the *Content* tab page, you select which images to display in the gallery. Choose one of the following options:

* *From all libraries*\
  All images that are uploaded and published will be displayed in the gallery.
* *From selected libraries only...*\
  A custom selection of libraries is displayed.     To select one or more libraries from which you want to display images, click the *Select* button.
* *From currently opened library*\
  All published images from the currently opened library will be displayed in the gallery.

Under *Narrow selection by...,* you can further specify which images to display by choosing one of the following:

* *All published images*\
  This is selected by default and displays all images selected in the previous step.
* *Selection of images...*\
  You can narrow down the displayed images using categories, tags, and dates. Select one or more of the following:

  * *Categories...*\
    Click the *Select* button to select the categories from which you want to display images.
  * *Tags...*\
    Click the *Select* button to select tags that displayed images need to have.
  * *Date...*\
    Select one of the predefined time intervals so that images uploaded during that interval will be displayed or choose *Custom range…*.

### List settings

List settings define how the *Image gallery* widget display images. Choose one of the following options:

 <table>
<colgroup><col><col></colgroup>
<tbody>
<tr>
<td>

<strong>Option</strong>

</td>
<td>

<strong>Description</strong>

</td>
</tr>
<tr>
<td>

<em>Use paging</em>

</td>
<td>

The system divides the image thumbnails into pages. In the input field, you specify how many image thumbnails per page you want to display.

</td>
</tr>
<tr>
<td>

<em>Use limit</em>

</td>
<td>

The system displays only a limited number of image thumbnails. In the input field, you specify how many image thumbnails you want to display.

</td>
</tr>
<tr>
<td>

<em>No limit and paging</em>

</td>
<td>

The system displays all images that meet the requirements and filters you set in the <em>Content</em> tab.

</td>
</tr>
<tr>
<td>

<em>Sort images</em>

</td>
<td>

By default, the last published images are listed on top. You can select a different sorting criterion:<ul>

<li><em>Last published</em></li>
<li><em>Last modified</em></li>
<li><em>By Title (A-Z)</em></li>
<li><em>By Title (Z-A)</em></li>
<li><em>As set in Advanced mode</em><br>
To sort the list of images by property that is not defined in the sort dropdown menu, you must add a new sorting expression in the designer&rsquo;s <em>Advanced</em> mode. For example, to sort images using the <em>Extension</em> property of the image, navigate to <em>Advanced &raquo; Model</em> and, for <em>SortExpression</em>, add <em>Extension ASC</em>. As a result, in the sort dropdown, the <em>As set in Advanced mode</em> option is selected by default.</li>
</ul>

</td>
</tr>
<tr>
<td>

<em>Thumbnail size</em>

</td>
<td>

Provides an option for configuring size of image thumbnails. This size applies to the thumbnails of the images when widget is in <em>List</em> mode.

</td>
</tr>
<tr>
<td>

<em>List template</em>

</td>
<td>

Select the template you want to use to list images on the webpage. Choose one of the following options:<ul>

<li><em>ThumbnailStrip</em><br>
The <em>Image gallery</em> displays a horizontal strip of image thumbnails. When you click an image from the strip, a preview of the image is displayed above the thumbnail strip.</li>
<li><em>ImageGallery</em><br>
The images are displayed as thumbnails. When clicked, the image is displayed together with the image title, the user who has uploaded the image, and the date of upload.</li>
<li><em>OverlayGallery</em><br>
The images are displayed as thumbnails. When clicked, the image is displayed as an overlay of the page together with its title.</li>
<li><em>SimpleList</em><br>
All images are displayed in a large size. The description of the images is displayed in tooltip text.</li>
</ul>

</td>
</tr>
<tr>
<td>

<em>CSS classes</em>

</td>
<td>

Expand <em>More options</em> section to apply additional CSS classes to the <em>Image gallery</em> widget when in <em>List</em> mode.

</td>
</tr>
</tbody>
</table>

### Single item settings

Single item settings define how individual images are displayed. Choose one of the following options:

* *Open single item in...*\
  Select one of the following options:

  * *Auto-generated page*\
    When you click an image, it is displayed in an automatically generated page with the same layout as the list page.
  * *Selected existing page...*\
    Select a page from the list of existing pages that has the desired layout. When you click on the image, it is displayed in this specific page.

  > info **NOTE**: The page on which you want the image displayed must have an *Image gallery* widget added.
* *Image size*\
  Provides an option for configuring the size of the image. In the dropdown box, all predefined image sizes appear.
* *Detail template*\
  Select the template you want to use to display the image's details on the webpage.
* *CSS classes*\
  Expand *More options* section to apply additional CSS classes to the *Image gallery* widget when the image details are opened.

### Advanced settings

In *Advanced* settings, you specify individual properties of the widget:

* *DetailsPageId*\
  Gets the ID of the page you have selected in the *Selected existing page...* option in the *Single item settings* tab.
* *DetailTemplateName*\
  Gets the template you have selected in the *Detail template* dropdown in the *Single item settings* tab.
* *ListTemplateName*\
  Gets the template you have chosen in the *List template* dropdown in the *List settings* tab.
* *OpenInSamePage*\
  Defines whether when you click on an image thumbnail to open the detail view in a new window. The default value is *False*.

### Model settings

Model settings display all properties directly bound to the *Image Gallery* widget model. Access these properties by clicking the *Model* button in *Advanced* settings.

 <table>
<colgroup><col><col></colgroup>
<tbody>
<tr>
<td>

<strong>Setting</strong>

</td>
<td>

<strong>Description</strong>

</td>
</tr>
<tr>
<td>

<em>DetailCssClass</em>

</td>
<td>

Gets and sets additional CSS classes to the image detail view.

</td>
</tr>
<tr>
<td>

<em>DisplayMode</em>

</td>
<td>

Gets the value you have selected in the <em>List settings</em>tab:<ul>

<li><em>Paging</em><br>
This is the default option.</li>
<li><em>Limit</em></li>
<li><em>All</em></li>
</ul>

</td>
</tr>
<tr>
<td>

<em>FilterExpression</em>

</td>
<td>

Filters images based on an additional filter expression.

</td>
</tr>
<tr>
<td>

<em>ItemsPerPage</em>

</td>
<td>

Defines the number of images per page when paging is enabled. The default value is <strong>20</strong>.

</td>
</tr>
<tr>
<td>

<em>ListCssClass</em>

</td>
<td>

Gets and sets additional CSS classes to the list view.

</td>
</tr>
<tr>
<td>

<em>ParentFilterMode</em>

</td>
<td>

Gets the option that you have chosen for libraries in the <em>Content</em>tab. The possible values are:<ul>

<li><em>All</em><br>
This is the default option.</li>
<li><em>Selected</em></li>
<li><em>CurrentlyOpen</em><em></em></li>
</ul>

</td>
</tr>
<tr>
<td>

<em>ProviderName</em>

</td>
<td>

If you have more than one provider added, you can use an image provider different than the default one. To do this, specify the name of this provider.

> info **NOTE**: If you leave this property value empty, the default image provider is used.

</td>
</tr>
<tr>
<td>

<em>SelectionMode</em>

</td>
<td>

Gets the option that you have chosen for images under <em>Narrow selection by...</em> in the <em>Content</em>tab. The possible values are:<ul>

<li><em>AllItems</em><br>
This is the default option.</li>
<li><em>FilteredItems</em></li>
</ul>

</td>
</tr>
<tr>
<td>

<em>SerializedAdditionalFilters</em>

</td>
<td>

If images are filtered based on a date, tags, or categories, the IDs of the selected filter criteria are serialized and populated in that field.

</td>
</tr>
<tr>
<td>

<em>SerializedSelectedItemsIds</em>

</td>
<td>

In case images are specifically selected, the IDs of the selected images are serialized and populated in that field. For example: <span class="Code">\["3f47d0b8-2d22-6e58-888c-ff0000bfc4e0"]</span>

</td>
</tr>
<tr>
<td>

<em>SerializedThumbnailSizeModel</em>

</td>
<td>

Contains serialized settings for the size of the thumbnails. Specified size is used in the frontend of the <em>Image Gallery</em> widget when displayed in <em>List</em> mode.

</td>
</tr>
<tr>
<td>

<em>SerializedImageSizeModel</em>

</td>
<td>

Contains serialized settings for the size of the image. Specified size is used in the frontend of the <em>Image Gallery</em> widget when displayed in <em>Details</em> mode.

</td>
</tr>
<tr>
<td>

<em>SortExpression</em>

</td>
<td>

Adds additional sorting expression for the images. The default value is <span class="Code">PublicationDate DESC</span>.

</td>
</tr>
<tr>
<td>

<em>UrlKeyPrefix</em>

</td>
<td>

Gets or sets the URL key prefix. Used when building or evaluating URLs for paging and filtering.

</td>
</tr>
</tbody>
</table>

## Lazy loading of images

When you use the *Image gallery* widget, Sitefinity CMS generates a series of `img` tags in the HTML of the page. In these tags, Sitefinity CMS automatically generates the `loading="lazy"` attribute.

This attribute instructs the browser not to load images that are off-screen until immediately before the moment they become visible. Thus, lazy loading of images improves performance.

## Width and height image attributes

Sitefinity CMS automatically uses `width` and `height` attributes within the `img` tag. This has the following benefits.

* The browser can properly layout the page before the images are downloaded and displayed to the user.\
  This increases the rendering speed and avoids unnecessary page layout shifts.
* This improves the Google page experience score, measured by [Google Lighthouse](https://developers.google.com/web/tools/lighthouse), and thus, increases your SEO standing.

> info **RECOMMENDATION**: If you add `width` and `height` attributes to your images, we recommend adding the following CSS to your styles, so that images do not exceed their container in the rendered page:

```CSS
img {
  max-width: 100%
   height: auto;
}

```