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.11780690416.19d0d667

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 5, 2026 8:14pm

[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.