Gallery

Last modified: October 21, 2026

Introduction

The Gallery widget, a replacement for both the template grid and list view, helps you build beautiful lists and grids for desktop, tablet, and mobile devices. Featuring the same filtering and sorting as seen in Data Grid 2, the Gallery widget also provides options for varying columns per device type and gives you the power to create amazing grid and list experiences for every user.

Here is an example of a Gallery widget using a filter and a sort:

Example of gallery using filter and sort

Configuration

Several options can be defined in the Gallery widget:

Data Source

Data source specifies the source of the data being presented in the Gallery. You can select data from Database (optionally with an XPath constraint), Association, Microflow, or Nanoflow.

Columns

The Gallery widget applies a different number of columns based on the device being used. You can set Desktop columns, Tablet columns, and Phone columns.

Items

On the Behavior tab, you can define the properties related to the items being presented. Page size, Pagination, and Position of pagination are in the Pagination group. Empty message and Dynamic item class are in the Appearance group.

Page size

Defines the amount of data shown for each page or the limit to be presented when using virtual scrolling.

Pagination

The pagination status text and the screen reader labels of the paging buttons are currently written in English and cannot be translated. We are working to improve this in the future.

You can choose between paging buttons (buttons presented below or above the grid), virtual scrolling (a mechanism that automatically loads data when the user reaches the bottom of the scroll bar), or load more (a button that loads more items).

Position of Pagination

This option defines the position of the pagination relative to the grid items: Below grid, Above grid, or Both. It is available when Pagination is set to Paging buttons, or when Pagination is set to Virtual scrolling or Load more and Show total count is enabled.

Empty Message

When this option is defined as custom it will show a composable region. Here you can place widgets that will be presented when no items are available to be shown, as well as when the filter does not return any data:

Dynamic Item Class

The Gallery widget can dynamically apply a CSS class to a specific item. You can achieve this by adding an expression based on the item values (attributes), as in the example below.

This example checks the value of CountryName and, if the attribute is equal to Spain, applies the class my-custom-class to the items:

Events

The new Gallery widget can trigger some events while iterating with it.

On Click Action

Triggers an action (such as a nanoflow, microflow, or Show page action) when the end-user clicks in one of the items. It also adds a pointer cursor to signal that it is clickable. This function also complies with accessibility features and can be reached using only the keyboard.

Filtering

Starting with Data Widgets 3.0.0, filtering is configured in the filter widgets. When you update the module, existing grid-wide filtering configurations are automatically converted to the new setup.

To filter the gallery items, place filter widgets in the gallery's filters placeholder. The gallery does not have its own filtering configuration. Instead, configure the filter widgets themselves. Filter widgets placed in the filters placeholder are linked to the gallery automatically. To choose which attributes a filter applies to, set the filter widget to custom mode and select the attributes.

For more information, see the Filters section of Data Grid 2 and the documentation for each filter widget:

Sorting

To sort the gallery items, place a Drop-Down Sort widget in the gallery's filters placeholder. If you place it outside the filters placeholder, the widget shows an error that it is out of context. The gallery does not have its own sorting configuration. Instead, you select the attributes that end-users can sort by in the Drop-Down Sort widget.

If the data source of the gallery has a sort order, the Drop-Down Sort widget pre-selects it when it matches one of the attributes configured in the widget. When end-users select a different option, it overrides the sort order of the data source.

The Drop-Down Sort widget lets end-users choose the attribute and direction to sort the gallery items by. Place it inside the filters placeholder of the Gallery widget and configure these properties:

Datasource to sort: the data source of the gallery, linked automatically when the widget is placed in the filters placeholder
Attributes: the attributes that end-users can sort by; for each attribute, set the Caption shown in the drop-down
Empty option caption: the text shown when no sort option is selected
Sort order button caption and Input caption: the text announced by screen readers when using assistive technology

Selection

Enabling Selection allows users to select gallery items via clicking. Selection is disabled by default and can be activated by changing the Selection setting on the Behavior tab from None to either Single or Multi.

The Gallery widget keeps selected items in memory and supports selection persistence across page navigation when the Keep selection option is enabled. This allows users to maintain their selections while browsing through paginated data or navigating between different pages in your application. See Keep Selection for more information about managing selection persistence and its limitations.

Selection Property

The Selection property determines what type of selection is available to users:

None: Selection is disabled. Users cannot select gallery items.
Single: Users can select only one item at a time. Selecting a new item automatically deselects the previously selected item.
Multi: Users can select multiple items simultaneously using various interaction methods.

When Selection is enabled, the Gallery automatically provides visual feedback to indicate selected items and supports keyboard navigation for accessibility.

Selection and Click Actions Constraint

It is not possible to use both selection and onClick actions simultaneously when the On click trigger is set to Single click. This constraint prevents ambiguous user interactions where a single click could both select an item and trigger an action.

Supported Combinations

Selection Mode	On Click Trigger	Selection Method	Click Action	Supported
None	Single click	N/A	✓ Click triggers action	✓ Yes
None	Double click	N/A	✓ Double-click triggers action	✓ Yes
Single/Multi	Single click	Item click	✗ Ambiguous interaction	✗ No
Single/Multi	Double click	Item click	✓ Click selects, double-click triggers action	✓ Yes

Error Prevention

If you attempt to configure both selection (Single or Multi) and an onClick action with Single click trigger, the Gallery will display a design-time error:

The item click action is ambiguous. Change "On click trigger" to "Double click" or set "Selection" to "None".

Recommended Approach

For galleries that need both selection and click actions:

Set On click trigger to Double click.
Configure your desired selection mode (Single or Multi).
Users can then select items with single clicks and trigger actions with double clicks.

Selection with Action Buttons in the Filters Placeholder

Gallery selection works seamlessly with action buttons and other widgets placed in the gallery's filters placeholder. This pattern enables powerful bulk operation workflows.

Selection Helper Integration

Place a Selection Helper widget in the gallery's filters placeholder to provide bulk selection controls:

Select All: Select all items on the current page
Clear Selection: Deselect all items on the current page
Selection Status: Visual indicator of the selection state of the current page (all, some, or none selected)

The Selection Helper only acts on the items on the current page. When Keep selection is set to Yes, items selected on other pages stay selected.

Selection Count Display

When Selection is set to Multi, use the Show selection count property to set where the number of selected items is displayed (default: Bottom):

Top: Shows count above the gallery items
Bottom: Shows count below the gallery items
Off: Hides the selection count

The selection count automatically updates as users select or deselect items and includes a "Clear selection" button for easy deselection.

Event Handling

Use the On selection change action to trigger custom logic when selection changes:

Update UI elements based on selection state
Enable/disable action buttons
Load additional data for selected items
Validate selection before allowing operations

Keep Selection

If this setting is enabled, then selected items persist across page navigation, data refreshes, filtering, and sorting operations. This setting is only available when Selection is set to Multi. By default, Keep selection is disabled and the selection is cleared when the items are not in the current set of datasource items. When enabled, selected items remain selected until manually cleared by the user or through a nanoflow action.

Keep Selection cannot be used with non-persistent entities (NPEs) or view entities, as their IDs change on refresh.

In the Gallery widget it is possible to navigate and select items using the keyboard. Keyboard navigation can increase user speed, as well as makes the widget more accessible.

To improve user experience, it is possible to detect which item has keyboard focus. Visually, you can see which item has keyboard focus by spotting the thin blue border.

You can also see when an item is selected: an item with a light brand primary background is selected.

For the keyboard navigation and keyboard selection to work, you must open the Behavior tab and then set the Selection property to one of the following:

Single: enables keyboard navigation with just single selection
Multi: to enable keyboard navigation with multi-selection

Using the keyboard arrow keys (↑, ↓, ←, →) the user can navigate between the items displayed in the Gallery. Also, the user can use special keyboard keys like Home, End, Page up, and Page down.

With the keyboard, the user can press Tab and navigate between elements to reach the Gallery items.

Keyboard Selection

Keyboard selection, which differs from navigation, simulates the click of the mouse on an item. Thus, after navigating to a desired item, the user can press Shift + Space and the item will be selected.

Keyboard Multi-Selection

To further improve the user experience, it is also possible to select many items only using the keyboard. To achieve this, the user can hold Shift on the first item and navigate with arrow key to the last item they want to select. By doing this, all the items between the first and last selected will also be selected.

Accessibility

Employing keyboard navigation is an effective way of ensuring users who cannot use a mouse can still interact with the Gallery widget.

Troubleshooting

The new Gallery widget uses CSS Grid as its base for styling. If you need to combine rows or columns you can achieve this using the following helper classes in the Dynamic item class:

widget-gallery-column-span-1 until widget-gallery-column-span-12: these classes merge column spaces, pushing items to a new row when the selected amount is reached for each platform
widget-gallery-row-span-1 until widget-gallery-row-span-12: these classes merge row spaces, pushing items into new columns or rows when needed