How to Build a Masonry List View Widget in Mendix Native Mobile (Technical Guide – Part 2)

How to Build a Masonry List View Widget in Mendix Native Mobile

What Is a Mendix Masonry List View Widget?

In Part 1, we explored the functional aspects of the Masonry List View Widget for Mendix Native Mobile, including its key features, configuration options, benefits, and common use cases.

If you're new to this widget, we recommend reading Part 1: Understanding the Masonry List View Widget for Mendix Native Mobile before continuing. It provides a complete overview of the widget's functionality, supported properties, and practical implementation scenarios.

In this second part, we focus on the technical implementation of the widget. We will cover:

  • Project structure

  • Dependencies

  • Installation steps

  • Build and release process

  • Internal component logic

  • Search and pagination handling

  • Deduplication approach

  • Technical limitations

This part is mainly useful for Mendix developers who want to understand how the widget is built and how it can be maintained or extended.

Technology Stack

The MasonryListView widget is built for Mendix Native Mobile using React Native and TypeScript.

The core masonry layout is powered by the following npm package:

@react-native-seoul/masonry-list

This library provides the masonry list behavior in React Native. The widget is developed using the official Mendix pluggable widget tooling.

Runtime Dependency

The main runtime dependency is:

  • @react-native-seoul/masonry-list: Version ^1.4.2. Provides the masonry grid list component.

This package is responsible for rendering the multi-column masonry layout in the native mobile app.

Development Dependencies

The widget uses Mendix pluggable widget tools for development, build, linting, and release. Important development dependencies include:

  • @mendix/pluggable-widgets-tools: Version ^10.15.0. Mendix widget build toolchain.

  • @types/big.js: Version ^6.0.2. Type definitions used by Mendix decimal handling.

Peer and Resolution Dependencies

For Mendix Native compatibility, some dependencies are pinned:

  • react: ^18.2.0

  • @types/react: ^18.2.0

  • react-native: 0.77.3

  • @types/react-native: 0.72.7

This is important because Mendix Native apps depend on a specific React Native runtime version. If the versions are mismatched, the widget may fail during build or runtime.

Node.js Requirement

The widget requires Node.js >= 20. Before building the widget, verify the installed Node.js version:

node -v

Also verify npm:

npm -v

Project Structure

The widget follows a typical Mendix pluggable widget project structure:

masonryListView/
src/
    MasonryListView.tsx
    MasonryListView.xml
    MasonryListView.editorConfig.ts
    package.xml
    assets/
        4646902.svg
    components/
    typings/
        MasonryListViewProps.d.ts
dist/
node_modules/
package.json
tsconfig.json
.eslintrc.js
prettier.config.js

Key Project Files

1. MasonryListView.tsx

This is the main React Native component. It contains the rendering logic, state handling, pagination logic, search reset logic, and deduplication logic. Most of the widget behavior is handled inside this file.

2. MasonryListView.xml

This file defines the widget metadata and properties. The properties configured in this XML file are shown in Mendix Studio Pro when the widget is added to a page.

Examples of properties:

  • Data source

  • Content

  • Column count

  • Margin between items

  • Padding

  • Load more action

  • Search text

This file also marks the widget as native mobile supported and offline capable.

3. MasonryListView.editorConfig.ts

This file is used for Studio Pro editor configuration. It can be used to customize property visibility, validations, preview behavior, and captions inside Mendix Studio Pro. In the current implementation, it returns the default properties unchanged. But it can be extended in future if needed.

4. package.xml

This file contains Mendix client module information. It is part of the widget package structure and is required for Mendix widget packaging.

5. package.json

This file contains npm scripts, dependencies, dev dependencies, resolutions, and project path configuration. One important configuration is:

"config": {
    "projectPath": "../../"
}

This assumes that the widget folder is placed two levels below the Mendix project root. If your folder structure is different, this path should be adjusted.

How to Install the Masonry List View Widget in Mendix

Step 1: Copy the Widget Folder

Place the widget folder inside the MyWidgets directory of your Mendix project.

YourMendixProject/
MyWidgets/
    masonryListView/
        src/
        package.json
        tsconfig.json

Step 2: Install npm Dependencies

Open a terminal inside the widget folder:

cd path/to/YourMendixProject/MyWidgets/masonryListView

Then run:

npm install

If you face peer dependency conflicts, run:

npm install --legacy-peer-deps

This is commonly required when npm strict peer dependency checks create conflicts.

Step 3: Build the Widget

To build the widget, run:

npm run build

This compiles the TypeScript code and generates the widget output. The build output is placed in the dist folder and also copied into the Mendix project's widgets directory.

Step 4: Use Watch Mode During Development

During active development, use:

npm run start

This starts watch mode and rebuilds the widget automatically whenever source files are changed. This is very useful while testing UI or logic changes.

Step 5: Run Lint

To check code quality:

npm run lint

To automatically fix lint issues:

npm run lint:fix

Step 6: Release the Widget

To create a production-ready .mpk package:

npm run release

This creates a distributable widget package inside the dist folder. The .mpk file can be imported into another Mendix project.

Adding the Widget in Mendix Studio Pro

After building the widget:

  • Open the Mendix project in Studio Pro.

  • Synchronize the app directory using F4.

  • Open a Native Mobile page.

  • Search for Masonry List View in the toolbox.

  • Drag and drop the widget onto the page.

  • Configure the data source.

  • Configure the content area.

  • Set column count, margin, padding, load more action, and search text if needed.

  • Run the native app and test the result.

Internal Component Logic

The widget uses a React functional component with TypeScript.

The main state and refs are:

  • items

  • idsRef

  • prevSearchRef

1. items

items is a React state variable. It stores the list of Mendix items currently displayed in the masonry list. When new data is loaded, this state is updated. In normal pagination mode, new items are appended. In search mode, old items are cleared and replaced with fresh search results.

2. idsRef

idsRef is a React ref that stores a Set of item IDs. It is used for deduplication. Before adding a new item to the list, the widget checks whether the item ID already exists in the set. If the ID already exists, the item is ignored. This prevents duplicate records from appearing in the UI.

3. prevSearchRef

prevSearchRef stores the previous search text. This helps the widget detect when the search text changes. When a change is detected, the widget clears the existing items and resets the ID tracking set. This is important because search results should start fresh.

Search Handling Logic

The widget reads the current value from the searchText property. If the current search text is different from the previous search text, the widget performs a reset.

The reset includes:

  • Clearing existing items

  • Clearing tracked item IDs

  • Updating the previous search value

When search text has a value, the widget enters search mode. In search mode:

  • Existing items are not appended

  • Pagination is disabled

  • Fresh filtered results are displayed

  • Deduplication is still applied

This ensures that search results are clean and accurate.

Pagination Handling Logic

Pagination is handled through the onLoadMore action. The widget uses the onEndReached behavior from the masonry list component. When the user scrolls near the end of the list, the widget triggers the configured Mendix action. This action can be a microflow or nanoflow.

Typical pagination flow:

  • Initial data is loaded.

  • User scrolls near the bottom.

  • Widget triggers onLoadMore.

  • Mendix retrieves the next set of records.

  • New records are passed to the widget.

  • Widget appends only new unique items.

Pagination is disabled when search text is active. This avoids mixing search results with normal paginated data.

Rendering Structure

At a high level, the widget renders a React Native View and inside that it renders the MasonryList.

<View style={[{ flex: 1, padding: paddingItems }, style]}>
    <MasonryList
        data={items}
        numColumns={columns}
        keyExtractor={(item) => item.id}
        renderItem={renderItem}
        showsVerticalScrollIndicator={false}
        onEndReached={...}
        onEndReachedThreshold={0.5}
    />
</View>

The content configured in Mendix Studio Pro is rendered for each item. This gives flexibility because developers can design the card layout using normal Mendix native widgets.

TypeScript Configuration

The widget uses the Mendix pluggable widget TypeScript base configuration:

{
    "extends": "@mendix/pluggable-widgets-tools/configs/tsconfig.base",
    "compilerOptions": {
        "baseUrl": "./"
    },
    "include": ["./src", "./typings"]
}

This ensures the widget follows the Mendix pluggable widget TypeScript standards.

Available npm Scripts

The widget provides the following useful npm scripts:

  • npm start: Starts native widget watch mode.

  • npm run build: Builds the widget.

  • npm run lint: Runs lint check.

  • npm run lint:fix: Fixes lint issues automatically.

  • npm run release: Creates production .mpk package.

Best Practices While Using This Widget

1. Use Proper Pagination Logic

If you are using pagination, make sure your microflow or nanoflow retrieves the next batch correctly. Use proper offset, limit, or page number logic.

2. Avoid Returning Duplicate Records

Even though the widget has deduplication, it is still better to avoid duplicates from the data source or API level. This improves performance and keeps the data flow clean.

3. Handle Search at Data Source Level

The widget does not perform client-side filtering. Search filtering should be handled by the Mendix data source, XPath, microflow, nanoflow, or API response. The widget only reacts to the searchText change and refreshes the displayed list.

4. Keep Card UI Lightweight

Since this widget is used in mobile apps, avoid making each card too heavy. Try to keep the card design simple and optimized. For example:

  • Use optimized images

  • Avoid unnecessary nested containers

  • Avoid heavy logic inside item content

  • Keep text and image rendering clean

5. Test in Real Devices

Masonry layouts and scrolling behavior should be tested on real mobile devices. Testing only in preview or emulator may not always show actual performance.

Known Limitations

The current version has a few limitations:

  • Native Mobile only

  • Web pages are not supported

  • No built-in pull-to-refresh

  • No drag-and-drop reordering

  • Equal column widths only

  • Scroll indicator is always hidden

  • Search depends on Mendix data source

  • Pagination is disabled during search

Possible Future Enhancements

The widget can be improved further with features like:

  • Pull-to-refresh support

  • Configurable scroll indicator

  • Empty state message

  • Loading indicator

  • Error state handling

  • Custom column width support

  • Header and footer support

  • Better Studio Pro preview

  • Property validations in editor config

Frequently Asked Questions

01What is a Masonry List View Widget in Mendix? +

A Masonry List View Widget displays records in a responsive Pinterest-style layout where each card can have a different height.

02Does the widget work in Mendix Native Mobile? +

Yes. The widget is designed specifically for Mendix Native Mobile applications built with React Native.

03Which library powers the masonry layout? +

The widget uses the @react-native-seoul/masonry-list package to render masonry grids.

04Does the widget support pagination? +

Yes. Pagination is implemented through the onLoadMore action and React Native onEndReached event.

05Can the widget prevent duplicate records? +

Yes. The widget uses a Set-based deduplication mechanism through idsRef to prevent duplicate records from being displayed.

06Does the widget support offline-first applications? +

Yes. The widget is configured for Mendix Native Mobile environments that support offline capabilities.

Conclusion

In this second part, we explored the technical side of the MasonryListView widget. We covered the project structure, dependencies, installation steps, build process, release process, internal state management, pagination logic, search handling, and deduplication approach.

The MasonryListView widget is a useful custom widget for Mendix Native Mobile applications where we need a modern, Pinterest-style grid layout. It provides a clean user experience and supports important real-world requirements like pagination, search, and duplicate prevention.

With this widget, Mendix developers can create attractive and performant mobile listing screens with less effort.