docs(gallery): add documentation for new gallery component

[brandyscarney]

⚠️ All instances of the dev build must be removed or updated before merging. ⚠️

Adds documentation & playgrounds for the new ion-gallery component.

Preview

Note: when opening the basic usage or masonry images examples in StackBlitz the img URL must be changed from https://ionicframework.com/ to https://ionic-docs-git-fw-7287-ionic1.vercel.app to load the images.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview, Comment	May 5, 2026 8:05pm

[brandyscarney]

I chose to add this under "Grids" because otherwise we would need to redo the component page to either add a new image for a top-level Gallery section or to add something like "Layout" which would reorder a few of them. I can change this if we want to categorize this differently.

[brandyscarney]

We need to actually merge this with a dev build otherwise the docs build will fail since Gallery only exists on the dev build.

[brandyscarney]

I don't love this location of images used by the demos but other demos use this as well so I followed the existing structure.

[thetaPC]

Do have a preferred folder structure that you would like to use?

[brandyscarney]

I would prefer to keep the images under the component's folder like this:

static
└── usage
    └── v9
        └── gallery
            └── assets
               |── 01.png 
               |── 02.png 
               |── 03.png 
               |── ...
               |── 10.png 
               |── 11.png 
               └── 12.png

But I am not going to try to refactor how this is currently working.

[brandyscarney]

I am following how other demos include images because the only other way to pass them to StackBlitz is using base64 encoding.

[ShaneK]

This looks so good, Brandy! Awesome work!!

[thetaPC]

LGTM, with minor requested changes

[thetaPC]

Thoughts on including a comment stating that the styles are for demo only and not needed to get gallery working? The same for the other frameworks.

[brandyscarney]

45123db

[thetaPC]

Could we point them to a permalink of the styles needed on the Ionic Framework repo?

[brandyscarney]

I don't think this is a good idea because if we update those styles in the future then they will be out of sync here. I included a code block to make it simpler to copy/paste: c2a85bb

[thetaPC]

The default value for columns did not render as expected. It just says DEFAULT_COLUMNS. Not sure if that's something we can fix easily or if it should be handle through another PR.

[brandyscarney]

This is just how docs are generated when you set the default to a const. You can see this happens in ion-split-pane too:

• Source
• Docs

The solution would involve updating how Stencil generates these docs.

[thetaPC]

Do have a preferred folder structure that you would like to use?

[thetaPC]

Is it intentional to not have it alphabetical?

[brandyscarney]

Yes because the main documentation (including playgrounds) for grid is in ion-grid and we always want to highlight the main documentation first. Grid is a bit of a weird one because it doesn't prefix all of its components with ion-grid-* like other components (card, fab, item, etc) do:

If it did this would look less weird. But when you navigate from the components page it would look even weirder to land in the middle here:

[thetaPC]

@brandyscarney I did notice that Firefox doesn't load the images even after changing the URL. I assume that it's something out of our scope but just wanted to let you know as a heads up.

[brandyscarney]

@thetaPC I confirmed that the same issue happens on the Cards example on Firefox so this seems to be a sitewide issue.