ionic-team · brandyscarney · May 20, 2026 · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026
@@ -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 />
@@ -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">

@@ -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) {

@@ -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',

@@ -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>
+```
@@ -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 {}
+```
@@ -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>
@@ -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>
+```
@@ -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;
+```
@@ -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>
+```