Skip to content

feat(gallery): add new gallery component#31101

Open
brandyscarney wants to merge 17 commits intonextfrom
FW-7280
Open

feat(gallery): add new gallery component#31101
brandyscarney wants to merge 17 commits intonextfrom
FW-7280

Conversation

@brandyscarney
Copy link
Copy Markdown
Member

@brandyscarney brandyscarney commented Apr 29, 2026

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.11777569278.1613db2e

@brandyscarney brandyscarney requested a review from a team as a code owner April 29, 2026 15:53
@brandyscarney brandyscarney requested a review from thetaPC April 29, 2026 15:53
@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 29, 2026

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

Project Deployment Actions Updated (UTC)
ionic-framework Ready Ready Preview, Comment Apr 30, 2026 5:20pm

Request Review

@brandyscarney brandyscarney marked this pull request as draft April 29, 2026 15:53
@github-actions 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
Comment thread .vercelignore
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

// --------------------------------------------------

:host(.gallery-layout-uniform) {
gap: var(--ion-gallery-gap, 16px);
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


await page.setContent(
`
<ion-gallery style="--internal-gallery-columns: 2;">
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

// 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 = {
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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', () => {
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@brandyscarney brandyscarney marked this pull request as ready for review April 29, 2026 20:53
// Reset the default margin for slotted elements so wrapper elements
// (such as <figure>) align properly with other gallery items.
::slotted(*) {
@include margin(0);
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

package: angular @ionic/angular package package: core @ionic/core package package: react @ionic/react package package: vue @ionic/vue package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant