feat(gallery): add new required gallery-item component for child items

[brandyscarney]

Issue number: internal

---

What is the current behavior?

The Gallery component queries all direct children and uses them to build both the uniform and masonry layouts. This causes issues when a wrapper element exists between the gallery and the gallery items. For example:

<ion-gallery>
  <div class="some-wrapper">
    <img src="/src/components/gallery/test/assets/01.png" alt="One" />
    <img src="/src/components/gallery/test/assets/02.png" alt="Two" />
    <img src="/src/components/gallery/test/assets/03.png" alt="Three" />
    <img src="/src/components/gallery/test/assets/04.png" alt="Four" />
  </div>
</ion-gallery>

In this scenario, the gallery treats the wrapper as a single item and does not correctly lay out the images contained within it.

What is the new behavior?

Several approaches were considered:

1. Add a class or attribute to wrapper elements that the Gallery could use to locate its items.
2. Query for items using a specific class or attribute when present, and fall back to querying direct children otherwise.
3. Introduce a new ion-gallery-item component that encapsulates all item-related styling and can contain arbitrary content (img, div, etc.).

We ultimately chose option 3 and introduced a new ion-gallery-item component. The ion-gallery component now queries for ion-gallery-item elements instead of relying on direct children.

As such, this PR does the following:

• Adds a new ion-gallery-item component.
• Updates ion-gallery to query for ion-gallery-item elements.
• Updates existing E2E and spec tests to use the new structure.
• Adds new E2E and spec tests for ion-gallery-item.
• Adds an E2E test verifying that wrapper elements around gallery items are effectively transparent to gallery layout calculations.

Does this introduce a breaking change?

• Yes
• No

Other information

Dev build: 8.8.9-dev.11781201980.1b6e8398

Previews:

• Basic
• Layout
• Wrapper

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Jun 12, 2026 10:15pm

[brandyscarney]

This change is actually more accurate. In both images the blue rectangle I added is 16px tall. You can see on the left there is a half pixel above and below it.

[brandyscarney]

I moved this to be on the items themselves because I can't apply them to all items or the ones containing img will also get an explicit height.

[brandyscarney]

I didn't change the name of this to replace divs with items so you could see there are not diffs on these but I can update them after it's been reviewed if desired.

[ShaneK]

This is looking really cool! I just had some change requests and some nits, but I'm loving the way it's looking!

[ShaneK]

Awesome work! Looks good to me 🚀

[thetaPC]

LGTM, left suggestions but not blockers

[thetaPC]

We might want to create const like we've been doing in the Modular Ionic so we can pass them to tests and the component itself. Doesn't have to happen now, but it'll have to during the migration.

Suggested change

	const LAYOUT_OPTIONS = ['uniform', 'masonry'];
	export const ION_GALLERY_LAYOUT_OPTIONS = ['uniform', 'masonry']as const;
	export type IonGalleryLayout = (typeof ION_GALLERY_LAYOUT_OPTIONS)[number];

[brandyscarney]

I'd rather just do that during the migration if that's okay since we will need to create the interfaces file and everything.

[thetaPC]

Works for me!