Masonry Gallery (Mobile) turns a normal Bubble list of images into a native variable-height masonry gallery. Use it as a simple photo wall, an editorial gallery with hero spans, a styled portfolio or product gallery, or a workflow-controlled image browser. No JSON is required.
## Demo App
A configured Bubble mobile demo is available for reviewing setup, layout options, presets, interactions, pagination, refresh behavior, image loading, accessibility controls, and workflow actions.
Bubble Editor Demo:
https://bubble.io/page?id=ankhsmobile&app_type=mobile&tab=Design&name=Masonry+Gallery&type=pageRun-mode Preview:
https://ankhsmobile.bubbleapps.io/version-test/api/1.1/mobile/preview?debug_mode=true&preview_view=Masonry%20GalleryThe demo view is named Masonry Gallery.
## Quick Start
1. Add Masonry Gallery (Mobile) to a native mobile View.
2. Set Content - Images to a Bubble list of images.
3. Start with Layout - Columns = 2 and Layout - Gallery gap = 8.
4. Use Layout - Scroll behavior = Gallery scroll for the strongest large-gallery performance path.
5. Preview in BubbleGo on a physical device.
That is enough for a working masonry gallery.
## Content and Metadata
Content - Images is the authoritative source list. Optional metadata lists align by source position.
You can also provide:
• Content - Item IDs
• Text - Titles
• Text - Subtitles
• Display - Badges
• Accessibility - Labels
• Accessibility - Hints
• Content - Aspect ratios
• Content - Image widths and heights
• Content - Column spans
• Behavior - Disabled items
• Content - Placeholder hashes
Example:
Images = Search for Photos: each item's image
Item IDs = Search for Photos: each item's unique ID
Titles = Search for Photos: each item's title
Subtitles = Search for Photos: each item's subtitle
Badges = Search for Photos: each item's category
Use stable Item IDs whenever possible. They keep selection and programmatic targeting connected to the correct item when your list is reordered or refreshed.
Metadata mismatches degrade safely, but matching list lengths and order is recommended.
## Layout
Use Layout - Column mode to choose fixed or responsive columns.
Useful controls include:
• Columns
• Responsive minimum cell width
• Responsive maximum columns
• Gallery, row, and column gaps
• Horizontal and vertical padding
• Placement
• Aspect ratio behavior
• Fixed, fallback, minimum, and maximum aspect ratios
• Span pattern
• Featured column span
• Feature every N items
For editorial layouts, combine responsive columns with a span pattern such as a hero or featured treatment.
## Scroll Modes
Gallery scroll lets the plugin own the scroll viewport. This is the recommended mode for large feeds, strongest virtualization, and precise near-end pagination.
View scroll lets the surrounding Bubble mobile View own scrolling. Use it when the gallery should flow naturally with other content on the same View.
Because Bubble does not expose the parent View's exact scroll offset to the element, View scroll does not provide the same precise parent-viewport virtualization or near-end pagination ownership as Gallery scroll.
Automatic uses the plugin's fit-height context to choose the appropriate behavior.
## Presets and Styling
Use Preset - Style for production-ready visual treatments.
Representative presets include:
Editorial Air
Soft Cards
Travel Story
Noir Glass
Neon Night
Creator Bold
The plugin includes 24 production presets plus None.
Presets do not silently change your data, pagination, image-loading, or virtualization settings.
You can override individual visual fields such as gallery and cell backgrounds, corner radius, borders, shadows, overlays, captions, badges, selected and disabled styling, and empty or error-state presentation.
Leave explicit visual overrides unset when you want the selected preset to control that value.
## Image Loading and Error Handling
Available controls include:
• Loading strategy
• Cover or Contain content fit
• Content position
• Cache policy
• Placeholder style
• Load transition and duration
• Error presentation and message
• Optional fallback image
• Automatic retry count and delay
Use the Retry failed images action when you want a Bubble workflow to retry failed media.
## Interactions and Selection
The plugin supports tap, double tap, and long press.
Configure:
• Interaction mode
• Double tap window
• Long press duration
• Haptic feedback
• Press feedback
• Press scale
• Press opacity
• Press duration
Selection modes in V1 are None and Single.
You can optionally allow tap-again deselection and choose selection feedback.
Useful states include:
• Last tapped index
• Last tapped image
• Last tapped Item ID
• Last tapped title
• Last interaction type
• Selected index
• Selected image
• Selected count
Useful events include:
• Image tapped
• Image double tapped
• Image long pressed
• Selection changed
Bubble-facing indexes are 1-based.
## Pagination
For Gallery scroll, enable Pagination - Enable load more and control Pagination - More items available? from Bubble.
When the user reaches the configured near-end threshold, the plugin publishes near-end and request-pending state and triggers More items requested.
Your Bubble workflow should fetch or reveal the next page and append it to the Images list.
The plugin does not query your Bubble database itself. Bubble remains responsible for fetching and updating data.
## Pull to Refresh
Enable Refresh - Enable pull to refresh.
When Refresh requested fires:
1. Set your Bubble refreshing state to yes.
2. Reload or replace the source data.
3. Set Refresh - Refreshing? back to no when complete.
## Workflow Actions
The element provides actions for:
• Scroll to top
• Scroll to index
• Scroll to item ID
• Scroll to end
• Retry failed images
• Recalculate layout
• Select image by index
• Select image by item ID
• Clear selection
These actions make it easy to connect buttons, tabs, search results, deep links, and other Bubble workflows to gallery navigation and selection.
## Useful States and Events
States include:
• Gallery readiness
• Image count
• Loaded image count
• Failed image count
• Current columns
• Current scroll mode
• Masonry content height
• Gallery scrollability
• Near-end status
• Load-more request status
• Selection states
• At-top state
• Initial-loading state
• Initial-batch-complete state
• Last interaction type
• Error information
Events include:
• Gallery ready
• Image tapped
• Image double tapped
• Image long pressed
• Image failed to load
• Error occurred
• More items requested
• Selection changed
• Refresh requested
## Accessibility, RTL, and Reduced Motion
Provide source-aligned Accessibility - Labels and optional hints where useful.
The plugin exposes semantic selected, disabled, and error context and suppresses duplicate child accessibility targets.
Use Accessibility - Layout direction for LTR, app direction, or local RTL presentation.
Local RTL mirrors masonry placement and logical preset/default caption and badge placement without mutating the app's global RTL state.
Use Accessibility - Reduced motion to follow the device preference or always reduce decorative motion.
Interaction remains functional when motion is reduced.
## Performance Guidance
For large galleries, prefer Gallery scroll.
The production runtime passed a controlled 100-image Gallery-scroll hardening gate.
250 and 500 images are stress-characterization tiers.
Performance at those sizes depends on device capability, image dimensions, network and cache state, styling, and overall app composition.
Do not treat 500 items as a universal smoothness guarantee.
## V1 Boundaries
Masonry Gallery (Mobile) is image-focused and native-mobile-only.
V1 does not include:
• Built-in fullscreen lightbox
• Pinch zoom or pan canvas
• Video or audio cells
• Arbitrary nested Bubble elements
• Drag reorder
• Multiple selection
## Device Test Checklist
Before shipping your own app, test the gallery in BubbleGo and on your target native devices with your real data.
At minimum verify:
• Initial gallery load
• Normal scrolling
• Enabled tap/double-tap/long-press interactions
• Selection if used
• Your chosen preset or styling overrides
• Broken or slow image behavior
• Pagination if enabled
• Pull-to-refresh if enabled
• RTL/reduced-motion/accessibility configuration if relevant
• Your expected production gallery size
Browser or web preview is not equivalent to BubbleGo or native iOS and Android runtime verification for this plugin.
Built with 🤍 by ANKHARA Studios.
Built on Bubble
