Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/api/gallery-item.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
title: "ion-gallery-item"
---

import Props from '@ionic-internal/component-api/v9/gallery-item/props.md';
import Events from '@ionic-internal/component-api/v9/gallery-item/events.md';
import Methods from '@ionic-internal/component-api/v9/gallery-item/methods.md';
import Parts from '@ionic-internal/component-api/v9/gallery-item/parts.md';
import CustomProps from '@ionic-internal/component-api/v9/gallery-item/custom-props.mdx';
import Slots from '@ionic-internal/component-api/v9/gallery-item/slots.md';

<head>
<title>ion-gallery-item: Gallery Cell for Text, Images, and Cards</title>
<meta
name="description"
content="ion-gallery-item wraps the content for a single cell in an ion-gallery, such as an image, card, or text. Read to learn more about gallery item usage."
/>
</head>

import EncapsulationPill from '@components/page/api/EncapsulationPill';

<EncapsulationPill type="shadow" />

Gallery Item is a child component of [Gallery](./gallery.md). It wraps the content for a single cell of the grid. The content can be plain text or any element, including an `img`, a `figure` with a caption, or a [Card](./card.md).

Gallery Items must be placed inside a Gallery, which arranges them and applies layout-specific styling to each item, such as a square aspect ratio in the uniform layout.

Refer to the [Gallery](./gallery.md) documentation for more information.

## Properties
<Props />

## Events
<Events />

## Methods
<Methods />

## CSS Shadow Parts
<Parts />

## CSS Custom Properties
<CustomProps />

## Slots
<Slots />
20 changes: 11 additions & 9 deletions docs/api/gallery.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,9 @@ 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.
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.

Each [Gallery Item](./gallery-item.md) is a single cell of the grid and can contain plain text or any element, such as an `img`, a `figure` with a caption, or a [Card](./card.md).

## Basic Usage

Expand All @@ -41,10 +43,6 @@ import Uniform from '@site/static/usage/v9/gallery/uniform/index.md';

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.
Expand All @@ -63,10 +61,10 @@ import MasonryBestFit from '@site/static/usage/v9/gallery/masonry-best-fit/index

### 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.
An `img` placed directly inside a Gallery Item is given default styles to ensure consistent rendering. These styles make images fill their cell 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:
Images wrapped in another element (for example, inside a `figure`) do not receive these defaults. Apply the same styles to the nested `img` if you want matching behavior, for example:

```css
figure img {
Expand All @@ -88,7 +86,7 @@ import Images from '@site/static/usage/v9/gallery/images/index.md';

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:
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 |
| --- | --- | ---|
Expand All @@ -112,7 +110,11 @@ Whether provided as a single value or as a value inside a breakpoint map, each g
- A **string** can be any valid CSS [length-percentage](https://developer.mozilla.org/en-US/docs/Web/CSS/length-percentage) (such as `16px`, `1rem`, or `20%`), a math function (such as `calc(1rem + 8px)`), or a CSS variable (such as `var(--app-gallery-gap)`).
- A **number** is treated as a pixel value, so `16` is equivalent to `"16px"`.

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`.
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`.

:::tip
Use the `gap` property to space items apart rather than CSS margins. Margins set on item content are reset so they cannot disrupt the layout calculations, so they will not produce the spacing you expect. Use `gap` for the space _between_ items, and `padding` on your content to inset it _within_ an item.
:::

import Gap from '@site/static/usage/v9/gallery/gap/index.md';

Expand Down
2 changes: 1 addition & 1 deletion plugins/docusaurus-plugin-ionic-component-api/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ module.exports = function (context, options) {
// 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.9-dev.11780493108.1d8e1a89';
let npmTag = '8.8.9-dev.11780945313.14080cb4';
if (currentVersion.banner === 'unreleased') {
npmTag = 'next';
} else if (currentVersion.path !== undefined) {
Expand Down
2 changes: 1 addition & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -338,7 +338,7 @@ module.exports = {
type: 'category',
label: 'Grids',
collapsed: false,
items: ['api/grid', 'api/col', 'api/row', 'api/gallery'],
items: ['api/grid', 'api/col', 'api/row', 'api/gallery', 'api/gallery-item'],
},
{
type: 'category',
Expand Down
14 changes: 7 additions & 7 deletions static/code/stackblitz/v9/angular/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions static/code/stackblitz/v9/angular/package.json

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.

Note: this file has conflicts with major-9.0 that I am purposely not resolving right now because it uses an Ionic Angular version that supports Angular 21 but my dev build is off a different branch and it will not work with Angular 21.

Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@
"@angular/platform-browser": "^20.0.0",
"@angular/platform-browser-dynamic": "^20.0.0",
"@angular/router": "^20.0.0",
"@ionic/angular": "8.7.11",
"@ionic/core": "8.7.11",
"@ionic/angular": "8.8.9-dev.11780945313.14080cb4",
"@ionic/core": "8.8.9-dev.11780945313.14080cb4",
"ionicons": "8.0.13",
"rxjs": "^7.8.1",
"tslib": "^2.5.0",
Expand Down
6 changes: 3 additions & 3 deletions static/code/stackblitz/v9/html/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion static/code/stackblitz/v9/html/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"start": "vite preview"
},
"dependencies": {
"@ionic/core": "8.7.11",
"@ionic/core": "8.8.9-dev.11780945313.14080cb4",
"ionicons": "8.0.13"
},
"devDependencies": {
Expand Down
20 changes: 10 additions & 10 deletions static/code/stackblitz/v9/react/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions static/code/stackblitz/v9/react/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
"version": "0.1.0",
"private": true,
"dependencies": {
"@ionic/react": "8.7.11",
"@ionic/react-router": "8.7.11",
"@ionic/react": "8.8.9-dev.11780945313.14080cb4",
"@ionic/react-router": "8.8.9-dev.11780945313.14080cb4",
"@types/node": "^24.0.0",
"@types/react": "^19.0.0",
"@types/react-dom": "^19.0.0",
Expand Down
20 changes: 10 additions & 10 deletions static/code/stackblitz/v9/vue/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions static/code/stackblitz/v9/vue/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
"preview": "vite preview"
},
"dependencies": {
"@ionic/vue": "8.7.11",
"@ionic/vue-router": "8.7.11",
"@ionic/vue": "8.8.9-dev.11780945313.14080cb4",
"@ionic/vue-router": "8.8.9-dev.11780945313.14080cb4",
"vue": "^3.2.25",
"vue-router": "4.6.3"
},
Expand Down
48 changes: 36 additions & 12 deletions static/usage/v9/gallery/basic/angular/example_component_html.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,42 @@
</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-item
><img src="https://ionicframework.com/docs/img/demos/gallery/01.png" alt="Image 1"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/02.png" alt="Image 2"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/03.png" alt="Image 3"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/04.png" alt="Image 4"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/05.png" alt="Image 5"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/06.png" alt="Image 6"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/07.png" alt="Image 7"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/08.png" alt="Image 8"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/09.png" alt="Image 9"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/10.png" alt="Image 10"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/11.png" alt="Image 11"
/></ion-gallery-item>
<ion-gallery-item
><img src="https://ionicframework.com/docs/img/demos/gallery/12.png" alt="Image 12"
/></ion-gallery-item>
</ion-gallery>
</ion-content>
```
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
```ts
import { Component } from '@angular/core';
import { IonContent, IonGallery, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { IonContent, IonGallery, IonGalleryItem, 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],
imports: [IonContent, IonGallery, IonGalleryItem, IonHeader, IonTitle, IonToolbar],
})
export class ExampleComponent {}
```
Loading