diff --git a/docs/api/gallery.md b/docs/api/gallery.md
new file mode 100644
index 00000000000..f5ab84373bd
--- /dev/null
+++ 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';
+
+
+ ion-gallery: Responsive Uniform and Masonry Gallery Layouts
+
+
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+
+
+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';
+
+
+
+## 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';
+
+
+
+## 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';
+
+
+
+### 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';
+
+
+
+### 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';
+
+
+
+## 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';
+
+
+
+## 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';
+
+
+
+## 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
+
+
+## Events
+
+
+## Methods
+
+
+## CSS Shadow Parts
+
+
+## CSS Custom Properties
+
+
+## Slots
+
diff --git a/docs/components.md b/docs/components.md
index 4d1b2cf28a2..4ea465990d4 100644
--- 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
Floating action buttons are circular buttons that perform a primary action on a screen.
-
-
The grid is a powerful mobile-first system for building custom layouts.
+
+
A collection of layout components for building responsive grids and image layouts.
@@ -87,7 +87,7 @@ Ionic apps are made of high-level building blocks called Components, which allow
-
Inputs provides a way for users to enter data in your app.
+
Inputs provide a way for users to enter data in your app.
diff --git a/plugins/docusaurus-plugin-ionic-component-api/index.js b/plugins/docusaurus-plugin-ionic-component-api/index.js
index 8d9acb8c144..7bfad796faf 100644
--- 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
index 661395b2463..93fd41dfb79 100644
--- 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
new file mode 100644
index 00000000000..f3e49e2a22c
Binary files /dev/null and b/static/img/demos/gallery/01.png differ
diff --git a/static/img/demos/gallery/02.png b/static/img/demos/gallery/02.png
new file mode 100644
index 00000000000..1c82befeb86
Binary files /dev/null and b/static/img/demos/gallery/02.png differ
diff --git a/static/img/demos/gallery/03.png b/static/img/demos/gallery/03.png
new file mode 100644
index 00000000000..3f454de0a06
Binary files /dev/null and b/static/img/demos/gallery/03.png differ
diff --git a/static/img/demos/gallery/04.png b/static/img/demos/gallery/04.png
new file mode 100644
index 00000000000..d026972f7e1
Binary files /dev/null and b/static/img/demos/gallery/04.png differ
diff --git a/static/img/demos/gallery/05.png b/static/img/demos/gallery/05.png
new file mode 100644
index 00000000000..461e1ef0e94
Binary files /dev/null and b/static/img/demos/gallery/05.png differ
diff --git a/static/img/demos/gallery/06.png b/static/img/demos/gallery/06.png
new file mode 100644
index 00000000000..dfb2ac54caf
Binary files /dev/null and b/static/img/demos/gallery/06.png differ
diff --git a/static/img/demos/gallery/07.png b/static/img/demos/gallery/07.png
new file mode 100644
index 00000000000..a2e9d55ac6e
Binary files /dev/null and b/static/img/demos/gallery/07.png differ
diff --git a/static/img/demos/gallery/08.png b/static/img/demos/gallery/08.png
new file mode 100644
index 00000000000..ce617520d89
Binary files /dev/null and b/static/img/demos/gallery/08.png differ
diff --git a/static/img/demos/gallery/09.png b/static/img/demos/gallery/09.png
new file mode 100644
index 00000000000..5fa6ee4e75f
Binary files /dev/null and b/static/img/demos/gallery/09.png differ
diff --git a/static/img/demos/gallery/10.png b/static/img/demos/gallery/10.png
new file mode 100644
index 00000000000..fa28d4c1005
Binary files /dev/null and b/static/img/demos/gallery/10.png differ
diff --git a/static/img/demos/gallery/11.png b/static/img/demos/gallery/11.png
new file mode 100644
index 00000000000..8d2baefd257
Binary files /dev/null and b/static/img/demos/gallery/11.png differ
diff --git a/static/img/demos/gallery/12.png b/static/img/demos/gallery/12.png
new file mode 100644
index 00000000000..c20056d1579
Binary files /dev/null and b/static/img/demos/gallery/12.png differ
diff --git a/static/usage/v9/gallery/basic/angular/example_component_html.md b/static/usage/v9/gallery/basic/angular/example_component_html.md
new file mode 100644
index 00000000000..7e51f617d3f
--- /dev/null
+++ b/static/usage/v9/gallery/basic/angular/example_component_html.md
@@ -0,0 +1,23 @@
+```html
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/static/usage/v9/gallery/basic/angular/example_component_ts.md b/static/usage/v9/gallery/basic/angular/example_component_ts.md
new file mode 100644
index 00000000000..c73d7da46c8
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..b289722cb1d
--- /dev/null
+++ b/static/usage/v9/gallery/basic/demo.html
@@ -0,0 +1,49 @@
+
+
+
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/static/usage/v9/gallery/basic/javascript.md b/static/usage/v9/gallery/basic/javascript.md
new file mode 100644
index 00000000000..7e51f617d3f
--- /dev/null
+++ b/static/usage/v9/gallery/basic/javascript.md
@@ -0,0 +1,23 @@
+```html
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/static/usage/v9/gallery/basic/react.md b/static/usage/v9/gallery/basic/react.md
new file mode 100644
index 00000000000..6a3b91dc416
--- /dev/null
+++ 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 (
+ <>
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+export default Example;
+```
diff --git a/static/usage/v9/gallery/basic/vue.md b/static/usage/v9/gallery/basic/vue.md
new file mode 100644
index 00000000000..15a7ad5b47c
--- /dev/null
+++ b/static/usage/v9/gallery/basic/vue.md
@@ -0,0 +1,29 @@
+```vue
+
+
+
+ Gallery
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/static/usage/v9/gallery/columns/angular/example_component_css.md b/static/usage/v9/gallery/columns/angular/example_component_css.md
new file mode 100644
index 00000000000..d67c1064ee0
--- /dev/null
+++ b/static/usage/v9/gallery/columns/angular/example_component_css.md
@@ -0,0 +1,60 @@
+```css
+/* These styles are for demonstration only. */
+/* They are not required for gallery to work. */
+ion-gallery div {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ color: #fff;
+ border-radius: 16px;
+}
+
+ion-gallery div:nth-child(1) {
+ background: #ff6b6b;
+}
+
+ion-gallery div:nth-child(2) {
+ background: #4ecdc4;
+}
+
+ion-gallery div:nth-child(3) {
+ background: #ffe66d;
+ color: #333;
+}
+
+ion-gallery div:nth-child(4) {
+ background: #5f27cd;
+}
+
+ion-gallery div:nth-child(5) {
+ background: #7f8c8d;
+}
+
+ion-gallery div:nth-child(6) {
+ background: #ff9f43;
+}
+
+ion-gallery div:nth-child(7) {
+ background: #ff3f34;
+}
+
+ion-gallery div:nth-child(8) {
+ background: #2ecc71;
+}
+
+ion-gallery div:nth-child(9) {
+ background: #34495e;
+}
+
+ion-gallery div:nth-child(10) {
+ background: #1abc9c;
+}
+
+ion-gallery div:nth-child(11) {
+ background: #e67e22;
+}
+
+ion-gallery div:nth-child(12) {
+ background: #9b59b6;
+}
+```
diff --git a/static/usage/v9/gallery/columns/angular/example_component_html.md b/static/usage/v9/gallery/columns/angular/example_component_html.md
new file mode 100644
index 00000000000..baaa5f87dc2
--- /dev/null
+++ b/static/usage/v9/gallery/columns/angular/example_component_html.md
@@ -0,0 +1,16 @@
+```html
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+