Skip to content

feat(gallery): add new gallery component#31101

Open
brandyscarney wants to merge 35 commits into
nextfrom
FW-7280
Open

feat(gallery): add new gallery component#31101
brandyscarney wants to merge 35 commits into
nextfrom
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.11777668103.132817bd

@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 May 11, 2026 9:12pm

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?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

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.

Added support for gap here: d494fab

I think if we wanted to support column & row we could just make it accept two values rather than doing two separate properties. I don't know, something to consider later.


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.

Comment thread core/src/components/gallery/gallery.tsx Outdated
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.`,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

@brandyscarney brandyscarney May 6, 2026

Choose a reason for hiding this comment

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

It looks kind of messy but I can add it:

CleanShot 2026-05-06 at 16 25 21@2x

Lmk if you still want it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

That looks good in my opinion. I'm getting the warning for <ion-gallery columns="{ xs: 2, sm: 3, md: 4, lg: 6, xl: 8, xxl: 12 }">. Is that expected for JS? It makes sense to me that I would get the error but just checking.

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.

Yes it doesn't accept the object as a string.

Comment thread core/src/components/gallery/gallery.tsx Outdated
Comment thread core/src/components/gallery/gallery.tsx Outdated
Comment thread core/src/components/gallery/gallery.scss Outdated
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We need to figure out the file structure. We have some files that separate by periods (gallery.spec.ts) and other by hyphens (gallery-interface.ts). Currently, ionic-modular is converting the interface files to periods (gallery-interface.ts -> gallery.interface.ts)

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 think it's fine to separate them with periods. I was just following the interface naming.

Comment thread core/src/components/gallery/test/layout/index.html
* Warn about an invalid gap value when it is set to a negative number
* or a breakpoint map object with invalid values.
*/
private warnInvalidGap(gap: GalleryGap) {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I was able to pass <ion-gallery gap="pink"> and I didn't get a warning.

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.

2 participants