Gallery

Last modified: March 3, 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 filters:

Example of gallery using filter and sort

Advanced Options

The gallery has an option to enable advanced options. When this option is toggled on, it enables numerous features to customize your gallery:

Pagination type
Pagination position
Empty list option
Dynamic item class
Filtering
Sorting

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, Association, Microflow, Nanoflow, or Xpath.

Columns

We provide a mechanism that automatically applies a different number of columns based on the device being used. In the Gallery widget, you can select columns for Desktops, Tablets, or Phone/Mobile.

Items

In the items group you can define the properties related to the items being presented.

Page size

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

Pagination

This widget does not support system texts, meaning is not possible to translate its content to another language.

You can choose between paging buttons (button being presented below or above the grid) or virtual scrolling (mechanism that automatically loads data when the users reaches the bottom of the scroll bar).

Position of Paging Buttons

This option is only available when Pagination is marked as Paging buttons and defines its position relative to the grid items.

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

In the new Gallery widget we offer an option to dynamically apply a CSS class to a specific item. You can achieve this by adding an expression based on the item values (attributes) like the example below.

In this example we check the value of CountryName, then if the attribute is equal to Spain apply 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

In order to enable filtering within the gallery items you need to select the desired attributes to be filtered in the Filtering tab. You can select attributes of the following types:

Autonumber
Boolean
Date & time
Decimal
Enumeration
Hashed string
Integer
Long
String

The attributes selected here will be used for the matching filter placed inside the composable region. When using multiple attributes, the filters will automatically select the matching attributes and then compose the desired filter value in an OR expression. Make sure you just have one filter widget for each type, for example Text Filter and Number Filter.

If a filter is being used and its type does not match with any selected attribute it will throw an error requesting you to select the correct filter widget.

An example of filtering configuration:

An example of text filter being used in the composable region combined with a drop-down sort:

For more information about filters, see the Filters section of Data Grid 2.

Sorting

In the new Gallery widget it is possible to add sorting widgets to the composable region and use them based on the configurations available in the Sorting tab. In order to make the attributes available for the sorting widgets, you must select an attribute and define the name it will show via the sort button.

If you have a sorting applied in the datasource of the gallery it will pre-select the value in the drop-down filter if it matches the selection made in the configurations and override the filter selected in the datasource in case you have more options defined.

The Drop-Down Sort widget is a widget you can use in combination with the Gallery widget. The Drop-Down Sort widget just needs to be placed inside a composable region of the Gallery widget after defining the sorting attributes in the Gallery widget's Sorting tab.

The Drop-Down Sort widget has two options you can set:

Empty option caption: value to be used when no value is selected
Screen reader caption: value to be 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 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 Header

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

Selection Helper Integration

Place a Selection Helper widget in the gallery header to provide bulk selection controls:

Select All: Quickly select all visible items
Clear Selection: Remove all current selections
Selection Status: Visual indicator of current selection state (all, some, or none selected)

Selection Count Display

Enable the Show selection count property to display the number of selected items:

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. 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 gray background is selected.

For the keyboard navigation and keyboard selection to work, the user must open the General 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