docs(gallery): add documentation for new gallery component #4484
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 /> | ||
|
Contributor
There was a problem hiding this comment. The default value for columns did not render as expected. It just says
Member
Author
|
||
|
|
||
| ## Events | ||
| <Events /> | ||
|
|
||
| ## Methods | ||
| <Methods /> | ||
|
|
||
| ## CSS Shadow Parts | ||
| <Parts /> | ||
|
|
||
| ## CSS Custom Properties | ||
| <CustomProps /> | ||
|
|
||
| ## Slots | ||
| <Slots /> | ||
|
Member
Author
There was a problem hiding this comment. I chose to add this under "Grids" because otherwise we would need to redo the component page to either add a new image for a top-level Gallery section or to add something like "Layout" which would reorder a few of them. I can change this if we want to categorize this differently. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -336,9 +336,9 @@ module.exports = { | |
| }, | ||
| { | ||
| type: 'category', | ||
| label: 'Grids', | ||
| collapsed: false, | ||
| items: ['api/grid', 'api/col', 'api/row', 'api/gallery'], | ||
|
Contributor
There was a problem hiding this comment. Is it intentional to not have it alphabetical?
Member
Author
There was a problem hiding this comment. Yes because the main documentation (including playgrounds) for grid is in 
If it did this would look less weird. But when you navigate from the components page it would look even weirder to land in the middle here: 
|
||
| }, | ||
| { | ||
| type: 'category', | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Normally I am against adding the default inline here but it doesn't populate in the prop's table due to it being set to a variable: