feat(gallery): add new gallery component by brandyscarney · Pull Request #31101 · ionic-team/ionic-framework

brandyscarney · 2026-04-29T15:53:26Z

Issue number: internal

What is the current behavior?

Developers who want to use a masonry layout must rely on third-party solutions or implement their own.

What is the new behavior?

Adds a new ion-gallery component.

Features

layout property:
- uniform - evenly sized grid rows
- masonry - stacked masonry layout
order property (masonry only):
- sequential - preserves DOM order
- best-fit - places items in the shortest column
columns property:
- Accepts number or string values
- Supports responsive values by breakpoint (xs, sm, md, lg, xl, xxl)
- Validates invalid inputs and falls back to defaults with warnings

Test Coverage

E2E (basic): uniform layout with images, including breakpoint screenshots
E2E (layout): uniform and masonry layouts across various div and image scenarios
Spec tests:
- columns fallback and normalization cases
- layout watcher, masonry scheduling, and load-event behavior
- order placement logic (sequential and best-fit)

Does this introduce a breaking change?

Yes
No

Other information

Basic Preview
Layout Preview

Dev build: 8.8.6-dev.11777668103.132817bd

vercel · 2026-04-29T15:53:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	May 5, 2026 5:02pm

brandyscarney · 2026-04-29T19:04:33Z

I updated this because this rule prevented the images in my assets/ directory from being served on Vercel.

brandyscarney · 2026-04-29T20:40:27Z

+// --------------------------------------------------
+
+:host(.gallery-layout-uniform) {
+  gap: var(--ion-gallery-gap, 16px);


Gap currently can only be changed by CSS. Should this be a property that can be updated based on breakpoint, like columns?

Yes, I lean towards it especially seeing that Chakra does that. I do wonder if we should split it into row-gap and column-gap but we can cross that bridge if we get a request for it so gap works for me.

brandyscarney · 2026-04-29T20:47:11Z

+
+        await page.setContent(
+          `
+            <ion-gallery style="--internal-gallery-columns: 2;">


Overriding the internal CSS variable for columns should have no effect since the columns property takes priority.

brandyscarney · 2026-04-29T20:49:48Z

+// This should match the default columns defined by the gallery component.
+// It is hardcoded here instead of grabbing the value from the gallery so
+// that changing it there without updating it here will break the tests.
+const DEFAULT_COLUMNS_BY_BREAKPOINT = {


I chose to define these here to catch any changes in the component but I can pull them from there if we want.

I would prefer getting them from gallery for a true source of truth.

brandyscarney · 2026-04-29T20:50:36Z

+      warningSpy.mockRestore();
+    });
+
+    it('should properly set columns for the md breakpoint but fallback to the default columns for all others when the columns property is set to an object with one valid breakpoint and the rest invalid', () => {


I decided to accept the valid breakpoint value and fallback for all the invalid ones, but I can change this behavior if something else is expected.

…layout test

brandyscarney · 2026-04-30T17:15:36Z

+// Reset the default margin for slotted elements so wrapper elements
+// (such as <figure>) align properly with other gallery items.
+::slotted(*) {
+  @include margin(0);


This is required to be here because if the user wraps the img in something with default margin (like figure) it will not properly align the element, even if they override the margin on their side. I will have to document that the top-level item in a gallery should not have margin to avoid issues with this.

…a column

thetaPC · 2026-05-04T17:35:27Z

+   * Normalize a columns value to a positive integer.
+   * Returns undefined when the input cannot be interpreted as a finite number.


Suggested change

* Normalize a columns value to a positive integer.

* Returns undefined when the input cannot be interpreted as a finite number.

* Normalize columns value to a positive integer.

* Returns `undefined` when the input cannot be interpreted as a finite number.

thetaPC · 2026-05-04T17:45:11Z

+    printIonWarning(
+      `[ion-gallery] - Invalid "columns" value (${JSON.stringify(
+        columns
+      )}). Expected a positive integer or breakpoint map object (e.g. { xs: 2, md: 4 }). Falling back to default responsive columns.`,


I wonder if it would be beneficial to display what the default responsive columns are so the dev can see it.

thetaPC · 2026-05-04T17:51:31Z

+    const columnsStr = styles.getPropertyValue('--internal-gallery-columns');
+    // Fallback to 2 columns for masonry calculations when the resolved
+    // --internal-gallery-columns CSS value is missing or unparsable.
+    const columns = parseInt(columnsStr, 10) || 2;


Do you think themes would want to define the fallback value instead of using 2?

thetaPC · 2026-05-04T17:52:37Z

+   * placed in the DOM. When `best-fit`, items are positioned under the column
+   * with the most available space.
+   */
+  @Prop({ reflect: true }) order: 'sequential' | 'best-fit' = 'sequential';


Let's give a warning if dev uses layout="uniform with order.

thetaPC · 2026-05-04T17:57:44Z

@@ -0,0 +1,64 @@
+@import "../../themes/native/native.globals";


Since this is a new component, let's use @use and only import the needed mixins since @import is deprecated and it would lessen the work for Modular Ionic.

thetaPC · 2026-05-04T21:25:04Z

The background is turning transparent because the content is too long. You'll need to adjust the viewport. I would recommend doing what I did with the badges in ionic-modular.

thetaPC · 2026-05-04T21:25:11Z

The background is turning transparent because the content is too long. You'll need to adjust the viewport. I would recommend doing what I did with the badges in ionic-modular.

thetaPC · 2026-05-04T21:25:20Z

The background is turning transparent because the content is too long. You'll need to adjust the viewport. I would recommend doing what I did with the badges in ionic-modular.

thetaPC · 2026-05-04T21:25:56Z

The background is turning transparent because the content is too long. You'll need to adjust the viewport. I would recommend doing what I did with the badges in ionic-modular. There seems to be quite a lot of screenshots like this so my comment goes to those as well.

thetaPC · 2026-05-04T21:28:29Z

The background is turning transparent because the content is too long. You'll need to adjust the viewport. I would recommend doing what I did with the badges in ionic-modular.

brandyscarney added 6 commits April 23, 2026 16:22

feat(gallery): add new gallery component

b0a3f1a

style(core): add TODOs for migrating global breakpoints

74332ac

test(gallery): add spec test for columns property

cca764d

refactor(gallery): convert columns css variable to an internal variable

ad2d0a2

test(gallery): add basic e2e test

6a19314

chore(): add updated snapshots

fdd55c4

brandyscarney requested a review from a team as a code owner April 29, 2026 15:53

brandyscarney requested a review from thetaPC April 29, 2026 15:53

brandyscarney marked this pull request as draft April 29, 2026 15:53

github-actions Bot added package: core @ionic/core package package: angular @ionic/angular package package: vue @ionic/vue package package: react @ionic/react package labels Apr 29, 2026

vercel Bot deployed to Preview April 29, 2026 15:54 View deployment

brandyscarney added 2 commits April 29, 2026 13:59

test(gallery): add layout e2e test

e9cdc62

chore(): add updated snapshots

f865311

vercel Bot deployed to Preview April 29, 2026 18:18 View deployment

refactor(gallery): move types to separate file

ca9305e

vercel Bot deployed to Preview April 29, 2026 18:22 View deployment

brandyscarney added 2 commits April 29, 2026 14:36

test(gallery): add spec tests for layout and order

8e9c9b0

style: lint

576c569

vercel Bot deployed to Preview April 29, 2026 18:39 View deployment

chore: pass non-snapshot images to Vercel

f40ea8b

vercel Bot deployed to Preview April 29, 2026 19:01 View deployment

brandyscarney commented Apr 29, 2026

View reviewed changes

Merge branch 'next' into FW-7280

970e4f2

vercel Bot deployed to Preview April 29, 2026 19:10 View deployment

brandyscarney commented Apr 29, 2026

View reviewed changes

brandyscarney marked this pull request as ready for review April 29, 2026 20:53

brandyscarney added 4 commits April 30, 2026 12:54

fix(gallery): reset margin on slotted elements to properly position them

f862f49

test(gallery): add tests for dynamically appended images and fix the …

eb6d900

…layout test

chore(): add updated snapshots

89e6886

Merge branch 'next' into FW-7280

613db2e

brandyscarney commented Apr 30, 2026

View reviewed changes

vercel Bot deployed to Preview April 30, 2026 17:19 View deployment

brandyscarney added 2 commits May 1, 2026 15:51

fix(gallery): remove the bottom margin from the last masonry item in …

9dfc81c

…a column

chore(): add updated snapshots

32817bd

vercel Bot deployed to Preview May 1, 2026 19:57 View deployment

thetaPC requested changes May 4, 2026

View reviewed changes

test(gallery): import default columns directly from gallery

4009a8a

vercel Bot deployed to Preview May 5, 2026 17:02 View deployment

		* Normalize a columns value to a positive integer.
		* Returns undefined when the input cannot be interpreted as a finite number.

		@@ -0,0 +1,64 @@
		@import "../../themes/native/native.globals";

Conversation

brandyscarney commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Features

Test Coverage

Does this introduce a breaking change?

Other information

Uh oh!

vercel Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brandyscarney commented Apr 29, 2026 •

edited

Loading

vercel Bot commented Apr 29, 2026 •

edited

Loading