ionic-team · brandyscarney · May 20, 2026 · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026
diff --git a/docs/api/gallery.md b/docs/api/gallery.md
@@ -0,0 +1,155 @@
+---
+title: "ion-gallery"
+---
+
+import Props from '@ionic-internal/component-api/v9/gallery/props.md';
+import Events from '@ionic-internal/component-api/v9/gallery/events.md';
+import Methods from '@ionic-internal/component-api/v9/gallery/methods.md';
+import Parts from '@ionic-internal/component-api/v9/gallery/parts.md';
+import CustomProps from '@ionic-internal/component-api/v9/gallery/custom-props.mdx';
+import Slots from '@ionic-internal/component-api/v9/gallery/slots.md';
+
+<head>
+ <title>ion-gallery: Responsive Uniform and Masonry Gallery Layouts</title>
+ <meta
+ name="description"
+ content="The gallery arranges images, cards, and other content in responsive uniform or masonry layouts with configurable column counts and masonry ordering modes."
+ />
+</head>
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+<EncapsulationPill type="shadow" />
+
+The gallery arranges images, cards, and other content in a responsive grid. It supports uniform and masonry layouts, configurable column counts (fixed or breakpoint-based), and multiple masonry ordering modes.
+
+## Basic Usage
+
+import Basic from '@site/static/usage/v9/gallery/basic/index.md';
+
+<Basic />
+
+## Uniform
+
+Uniform is the default layout. It creates a consistent grid where items appear at the same visual size with a `1 / 1` aspect ratio. This layout is ideal when visual alignment is more important than preserving each item's natural height.
+
+import Uniform from '@site/static/usage/v9/gallery/uniform/index.md';
+
+<Uniform />
+
+## Masonry
+
+Masonry preserves each item's natural height and stacks items vertically within each column, creating a staggered layout with minimal gaps. Masonry supports two ordering modes: sequential and best fit.
+
+:::important
+Avoid adding margin to top-level items in a masonry layout, as it can cause incorrect item placement. To add spacing, wrap the content in a child element and apply margin to that wrapper instead.
+:::
+
+### Sequential
+
+Sequential is the default masonry ordering mode. Items are placed in DOM order, filling columns from left to right.
+
+import MasonrySequential from '@site/static/usage/v9/gallery/masonry-sequential/index.md';
+
+<MasonrySequential />
+
+### Best Fit
+
+Best fit places each item in the column with the most available space, helping balance column heights.
+
+import MasonryBestFit from '@site/static/usage/v9/gallery/masonry-best-fit/index.md';
+
+<MasonryBestFit />
+
+### Images
+
+In masonry layouts, top-level `img` elements are given default styles to ensure consistent rendering. These styles make images fill their container while preserving their aspect ratio and keeping them centered.
+
+:::tip
+Images wrapped in other elements (for example, inside a `figure`) do not inherit these defaults. Apply the same styles to the nested `img` if you want matching behavior, for example:
+
+```css
+figure img {
+ display: block;
+
+ object-fit: cover;
+ object-position: center;
+
+ aspect-ratio: inherit;
+}
+```
+:::
+
+import Images from '@site/static/usage/v9/gallery/images/index.md';
+
+<Images />
+
+## Columns
+
+Columns can be configured with the `columns` property using either a single number for a fixed column count, or a breakpoint map to change columns across screen sizes.
+
+If no value is provided, or if an invalid value is used, the gallery falls back to its default responsive column behavior. The default column counts by breakpoint are:
+
+| Breakpoint | Min Width | Default Columns |
+| --- | --- | ---|
+| `xs` | `0` | `2` |
+| `sm` | `576px` | `3` |
+| `md` | `768px` | `4` |
+| `lg` | `992px` | `6` |
+| `xl` | `1200px` | `8` |
+| `xxl` | `1400px` | `10` |
+
+import Columns from '@site/static/usage/v9/gallery/columns/index.md';
+
+<Columns />
+
+## Gap
+
+Gap can be configured with the `gap` property using either a single value for a fixed gap, or a breakpoint map to change gap across screen sizes.
+
+If no value is provided, or if an invalid value is used, the gallery falls back to its default gap value. The default value is `16px`.
+
+import Gap from '@site/static/usage/v9/gallery/gap/index.md';
+
+<Gap />
+
+## Interfaces
+
+### GalleryBreakpointColumns
+
+```typescript
+interface GalleryBreakpointColumns {
+ xs?: string | number;
+ sm?: string | number;
+ md?: string | number;
+ lg?: string | number;
+ xl?: string | number;
+ xxl?: string | number;
+}
+```
+
+## Types
+
+### GalleryColumns
+
+```typescript
+type GalleryColumns = GalleryBreakpointColumns | string | number;
+```
+
+## Properties
+<Props />
+
+## Events
+<Events />
+
+## Methods
+<Methods />
+
+## CSS Shadow Parts
+<Parts />
+
+## CSS Custom Properties
+<CustomProps />
+
+## Slots
+<Slots />
diff --git a/docs/components.md b/docs/components.md
@@ -74,8 +74,8 @@ Ionic apps are made of high-level building blocks called Components, which allow
  <p>Floating action buttons are circular buttons that perform a primary action on a screen.</p>
 </DocsCard>
 
-<DocsCard header="Grid" href="api/grid" icon="/icons/component-grid-icon.png">
- <p>The grid is a powerful mobile-first system for building custom layouts.</p>
+<DocsCard header="Grids" href="api/grid" icon="/icons/component-grid-icon.png">
+ <p>A collection of layout components for building responsive grids and image layouts.</p>
 </DocsCard>
 
 <DocsCard header="Icons" href="api/icon" icon="/icons/component-icons-icon.png">
@@ -87,7 +87,7 @@ Ionic apps are made of high-level building blocks called Components, which allow
 </DocsCard>
 
 <DocsCard header="Inputs" href="api/input" icon="/icons/component-input-icon.png">
- <p>Inputs provides a way for users to enter data in your app.</p>
+ <p>Inputs provide a way for users to enter data in your app.</p>
 </DocsCard>
 
 <DocsCard header="Item" href="api/item" img="/icons/feature-component-item-icon.png">

diff --git a/plugins/docusaurus-plugin-ionic-component-api/index.js b/plugins/docusaurus-plugin-ionic-component-api/index.js
@@ -54,7 +54,10 @@ module.exports = function (context, options) {
  await generateMarkdownForVersion(version, npmTag, context.i18n.currentLocale, false);
  }
 
- let npmTag = 'latest';
+ // TODO(FW-7097): Replace this with `latest` when v9 is released.
+ // Dev build based on the `next` branch of `ionic-framework`.
+ // This must be used to build the docs with the new components.
+ let npmTag = '8.8.7-dev.11779221548.1d38f927';
  if (currentVersion.banner === 'unreleased') {
  npmTag = 'next';
  } else if (currentVersion.path !== undefined) {

diff --git a/sidebars.js b/sidebars.js
@@ -336,9 +336,9 @@ module.exports = {
  },
  {
  type: 'category',
- label: 'Grid',
+ label: 'Grids',
  collapsed: false,
- items: ['api/grid', 'api/col', 'api/row'],
+ items: ['api/grid', 'api/col', 'api/row', 'api/gallery'],
  },
  {
  type: 'category',

diff --git a/static/img/demos/gallery/01.png b/static/img/demos/gallery/01.png
diff --git a/static/img/demos/gallery/02.png b/static/img/demos/gallery/02.png
diff --git a/static/img/demos/gallery/03.png b/static/img/demos/gallery/03.png
diff --git a/static/img/demos/gallery/04.png b/static/img/demos/gallery/04.png
diff --git a/static/img/demos/gallery/05.png b/static/img/demos/gallery/05.png
diff --git a/static/img/demos/gallery/06.png b/static/img/demos/gallery/06.png
diff --git a/static/img/demos/gallery/07.png b/static/img/demos/gallery/07.png
diff --git a/static/img/demos/gallery/08.png b/static/img/demos/gallery/08.png
diff --git a/static/img/demos/gallery/09.png b/static/img/demos/gallery/09.png
diff --git a/static/img/demos/gallery/10.png b/static/img/demos/gallery/10.png
diff --git a/static/img/demos/gallery/11.png b/static/img/demos/gallery/11.png
diff --git a/static/img/demos/gallery/12.png b/static/img/demos/gallery/12.png
diff --git a/static/usage/v9/gallery/basic/angular/example_component_html.md b/static/usage/v9/gallery/basic/angular/example_component_html.md
@@ -0,0 +1,23 @@
+```html
+<ion-header>
+ <ion-toolbar>
+ <ion-title>Gallery</ion-title>
+ </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">
+ <ion-gallery>
+ <img src="https://ionicframework.com/docs/img/demos/gallery/01.png" alt="Image 1" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/02.png" alt="Image 2" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/03.png" alt="Image 3" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/04.png" alt="Image 4" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/05.png" alt="Image 5" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/06.png" alt="Image 6" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/07.png" alt="Image 7" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/08.png" alt="Image 8" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/09.png" alt="Image 9" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/10.png" alt="Image 10" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/11.png" alt="Image 11" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/12.png" alt="Image 12" />
+ </ion-gallery>
+</ion-content>
+```
diff --git a/static/usage/v9/gallery/basic/angular/example_component_ts.md b/static/usage/v9/gallery/basic/angular/example_component_ts.md
@@ -0,0 +1,12 @@
+```ts
+import { Component } from '@angular/core';
+import { IonContent, IonGallery, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+ selector: 'app-example',
+ templateUrl: 'example.component.html',
+ styleUrls: ['example.component.css'],
+ imports: [IonContent, IonGallery, IonHeader, IonTitle, IonToolbar],
+})
+export class ExampleComponent {}
+```
diff --git a/static/usage/v9/gallery/basic/demo.html b/static/usage/v9/gallery/basic/demo.html
@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Gallery</title>
+ <link rel="stylesheet" href="../../common.css" />
+ <script src="../../common.js"></script>
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@8/dist/ionic/ionic.esm.js"></script>
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@8/css/ionic.bundle.css" />
+
+ <style>
+ /* Content padding + home indicator height */
+ .ios {
+ --ion-safe-area-bottom: 36px;
+ }
+
+ ion-content::part(scroll) {
+ padding-bottom: var(--ion-safe-area-bottom, 0);
+ }
+ </style>
+ </head>
+
+ <body>
+ <ion-app>
+ <ion-header>
+ <ion-toolbar>
+ <ion-title>Gallery</ion-title>
+ </ion-toolbar>
+ </ion-header>
+ <ion-content class="ion-padding">
+ <ion-gallery>
+ <img src="/docs/img/demos/gallery/01.png" alt="Image 1" />
+ <img src="/docs/img/demos/gallery/02.png" alt="Image 2" />
+ <img src="/docs/img/demos/gallery/03.png" alt="Image 3" />
+ <img src="/docs/img/demos/gallery/04.png" alt="Image 4" />
+ <img src="/docs/img/demos/gallery/05.png" alt="Image 5" />
+ <img src="/docs/img/demos/gallery/06.png" alt="Image 6" />
+ <img src="/docs/img/demos/gallery/07.png" alt="Image 7" />
+ <img src="/docs/img/demos/gallery/08.png" alt="Image 8" />
+ <img src="/docs/img/demos/gallery/09.png" alt="Image 9" />
+ <img src="/docs/img/demos/gallery/10.png" alt="Image 10" />
+ <img src="/docs/img/demos/gallery/11.png" alt="Image 11" />
+ <img src="/docs/img/demos/gallery/12.png" alt="Image 12" />
+ </ion-gallery>
+ </ion-content>
+ </ion-app>
+ </body>
+</html>
diff --git a/static/usage/v9/gallery/basic/javascript.md b/static/usage/v9/gallery/basic/javascript.md
@@ -0,0 +1,23 @@
+```html
+<ion-header>
+ <ion-toolbar>
+ <ion-title>Gallery</ion-title>
+ </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">
+ <ion-gallery>
+ <img src="https://ionicframework.com/docs/img/demos/gallery/01.png" alt="Image 1" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/02.png" alt="Image 2" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/03.png" alt="Image 3" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/04.png" alt="Image 4" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/05.png" alt="Image 5" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/06.png" alt="Image 6" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/07.png" alt="Image 7" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/08.png" alt="Image 8" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/09.png" alt="Image 9" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/10.png" alt="Image 10" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/11.png" alt="Image 11" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/12.png" alt="Image 12" />
+ </ion-gallery>
+</ion-content>
+```
diff --git a/static/usage/v9/gallery/basic/react.md b/static/usage/v9/gallery/basic/react.md
@@ -0,0 +1,33 @@
+```tsx
+import React from 'react';
+import { IonContent, IonGallery, IonHeader, IonTitle, IonToolbar } from '@ionic/react';
+
+function Example() {
+ return (
+ <>
+ <IonHeader>
+ <IonToolbar>
+ <IonTitle>Gallery</IonTitle>
+ </IonToolbar>
+ </IonHeader>
+ <IonContent className="ion-padding">
+ <IonGallery>
+ <img src="https://ionicframework.com/docs/img/demos/gallery/01.png" alt="Image 1" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/02.png" alt="Image 2" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/03.png" alt="Image 3" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/04.png" alt="Image 4" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/05.png" alt="Image 5" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/06.png" alt="Image 6" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/07.png" alt="Image 7" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/08.png" alt="Image 8" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/09.png" alt="Image 9" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/10.png" alt="Image 10" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/11.png" alt="Image 11" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/12.png" alt="Image 12" />
+ </IonGallery>
+ </IonContent>
+ </>
+ );
+}
+export default Example;
+```
diff --git a/static/usage/v9/gallery/basic/vue.md b/static/usage/v9/gallery/basic/vue.md
@@ -0,0 +1,29 @@
+```vue
+<template>
+ <ion-header>
+ <ion-toolbar>
+ <ion-title>Gallery</ion-title>
+ </ion-toolbar>
+ </ion-header>
+ <ion-content class="ion-padding">
+ <ion-gallery>
+ <img src="https://ionicframework.com/docs/img/demos/gallery/01.png" alt="Image 1" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/02.png" alt="Image 2" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/03.png" alt="Image 3" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/04.png" alt="Image 4" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/05.png" alt="Image 5" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/06.png" alt="Image 6" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/07.png" alt="Image 7" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/08.png" alt="Image 8" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/09.png" alt="Image 9" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/10.png" alt="Image 10" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/11.png" alt="Image 11" />
+ <img src="https://ionicframework.com/docs/img/demos/gallery/12.png" alt="Image 12" />
+ </ion-gallery>
+ </ion-content>
+</template>
+
+<script setup lang="ts">
+import { IonContent, IonGallery, IonHeader, IonTitle, IonToolbar } from '@ionic/vue';
+</script>
+```