Skip to content

Commit 6ea351b

Browse files
brandyscarneybrandyscarney
authored
docs(gallery): add documentation for new gallery component (#4484)
Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
1 parent 65f9fd1 commit 6ea351b

74 files changed

Lines changed: 2426 additions & 6 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/api/gallery.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: "ion-gallery"
3+
---
4+
5+
import Props from '@ionic-internal/component-api/v9/gallery/props.md';
6+
import Events from '@ionic-internal/component-api/v9/gallery/events.md';
7+
import Methods from '@ionic-internal/component-api/v9/gallery/methods.md';
8+
import Parts from '@ionic-internal/component-api/v9/gallery/parts.md';
9+
import CustomProps from '@ionic-internal/component-api/v9/gallery/custom-props.mdx';
10+
import Slots from '@ionic-internal/component-api/v9/gallery/slots.md';
11+
12+
<head>
13+
<title>ion-gallery: Responsive Uniform and Masonry Gallery Layouts</title>
14+
<meta
15+
name="description"
16+
content="The gallery arranges images, cards, and other content in responsive uniform or masonry layouts with configurable column counts and masonry ordering modes."
17+
/>
18+
</head>
19+
20+
import EncapsulationPill from '@components/page/api/EncapsulationPill';
21+
22+
<EncapsulationPill type="shadow" />
23+
24+
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.
25+
26+
## Basic Usage
27+
28+
import Basic from '@site/static/usage/v9/gallery/basic/index.md';
29+
30+
<Basic />
31+
32+
## Uniform
33+
34+
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.
35+
36+
import Uniform from '@site/static/usage/v9/gallery/uniform/index.md';
37+
38+
<Uniform />
39+
40+
## Masonry
41+
42+
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.
43+
44+
:::important
45+
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.
46+
:::
47+
48+
### Sequential
49+
50+
Sequential is the default masonry ordering mode. Items are placed in DOM order, filling columns from left to right.
51+
52+
import MasonrySequential from '@site/static/usage/v9/gallery/masonry-sequential/index.md';
53+
54+
<MasonrySequential />
55+
56+
### Best Fit
57+
58+
Best fit places each item in the column with the most available space, helping balance column heights.
59+
60+
import MasonryBestFit from '@site/static/usage/v9/gallery/masonry-best-fit/index.md';
61+
62+
<MasonryBestFit />
63+
64+
### Images
65+
66+
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.
67+
68+
:::tip
69+
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:
70+
71+
```css
72+
figure img {
73+
display: block;
74+
75+
object-fit: cover;
76+
object-position: center;
77+
78+
aspect-ratio: inherit;
79+
}
80+
```
81+
:::
82+
83+
import Images from '@site/static/usage/v9/gallery/images/index.md';
84+
85+
<Images />
86+
87+
## Columns
88+
89+
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.
90+
91+
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:
92+
93+
| Breakpoint | Min Width | Default Columns |
94+
| --- | --- | ---|
95+
| `xs` | `0` | `2` |
96+
| `sm` | `576px` | `3` |
97+
| `md` | `768px` | `4` |
98+
| `lg` | `992px` | `6` |
99+
| `xl` | `1200px` | `8` |
100+
| `xxl` | `1400px` | `10` |
101+
102+
import Columns from '@site/static/usage/v9/gallery/columns/index.md';
103+
104+
<Columns />
105+
106+
## Gap
107+
108+
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.
109+
110+
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`.
111+
112+
import Gap from '@site/static/usage/v9/gallery/gap/index.md';
113+
114+
<Gap />
115+
116+
## Interfaces
117+
118+
### GalleryBreakpointColumns
119+
120+
```typescript
121+
interface GalleryBreakpointColumns {
122+
xs?: string | number;
123+
sm?: string | number;
124+
md?: string | number;
125+
lg?: string | number;
126+
xl?: string | number;
127+
xxl?: string | number;
128+
}
129+
```
130+
131+
## Types
132+
133+
### GalleryColumns
134+
135+
```typescript
136+
type GalleryColumns = GalleryBreakpointColumns | string | number;
137+
```
138+
139+
## Properties
140+
<Props />
141+
142+
## Events
143+
<Events />
144+
145+
## Methods
146+
<Methods />
147+
148+
## CSS Shadow Parts
149+
<Parts />
150+
151+
## CSS Custom Properties
152+
<CustomProps />
153+
154+
## Slots
155+
<Slots />

‎docs/components.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,8 @@ Ionic apps are made of high-level building blocks called Components, which allow
7474
<p>Floating action buttons are circular buttons that perform a primary action on a screen.</p>
7575
</DocsCard>
7676

77-
<DocsCard header="Grid" href="api/grid" icon="/icons/component-grid-icon.png">
78-
<p>The grid is a powerful mobile-first system for building custom layouts.</p>
77+
<DocsCard header="Grids" href="api/grid" icon="/icons/component-grid-icon.png">
78+
<p>A collection of layout components for building responsive grids and image layouts.</p>
7979
</DocsCard>
8080

8181
<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
8787
</DocsCard>
8888

8989
<DocsCard header="Inputs" href="api/input" icon="/icons/component-input-icon.png">
90-
<p>Inputs provides a way for users to enter data in your app.</p>
90+
<p>Inputs provide a way for users to enter data in your app.</p>
9191
</DocsCard>
9292

9393
<DocsCard header="Item" href="api/item" img="/icons/feature-component-item-icon.png">

‎plugins/docusaurus-plugin-ionic-component-api/index.js‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,10 @@ module.exports = function (context, options) {
5454
await generateMarkdownForVersion(version, npmTag, context.i18n.currentLocale, false);
5555
}
5656

57-
let npmTag = 'latest';
57+
// TODO(FW-7097): Replace this with `latest` when v9 is released.
58+
// Dev build based on the `next` branch of `ionic-framework`.
59+
// This must be used to build the docs with the new components.
60+
let npmTag = '8.8.7-dev.11779221548.1d38f927';
5861
if (currentVersion.banner === 'unreleased') {
5962
npmTag = 'next';
6063
} else if (currentVersion.path !== undefined) {

‎sidebars.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -336,9 +336,9 @@ module.exports = {
336336
},
337337
{
338338
type: 'category',
339-
label: 'Grid',
339+
label: 'Grids',
340340
collapsed: false,
341-
items: ['api/grid', 'api/col', 'api/row'],
341+
items: ['api/grid', 'api/col', 'api/row', 'api/gallery'],
342342
},
343343
{
344344
type: 'category',

‎static/img/demos/gallery/01.png‎

692 KB
Loading

‎static/img/demos/gallery/02.png‎

553 KB
Loading

‎static/img/demos/gallery/03.png‎

486 KB
Loading

‎static/img/demos/gallery/04.png‎

728 KB
Loading

‎static/img/demos/gallery/05.png‎

727 KB
Loading

‎static/img/demos/gallery/06.png‎

540 KB
Loading

0 commit comments

Comments
 (0)