ion-gallery

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

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.

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.

Best Fit

Best fit places each item in the column with the most available space, helping balance column heights.

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.

note

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.

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

Interfaces

GalleryBreakpointColumns

interface GalleryBreakpointColumns {
  xs?: string | number;
  sm?: string | number;
  md?: string | number;
  lg?: string | number;
  xl?: string | number;
  xxl?: string | number;
}

Types

GalleryColumns

type GalleryColumns = GalleryBreakpointColumns | string | number;

Properties

columns

Description	The number of columns to display. Can be set as a number or an object of breakpoint values (e.g. { xs: 2, sm: 3, md: 4 }).
Attribute	columns
Type	GalleryBreakpointColumns ｜ number ｜ string
Default	DEFAULT_COLUMNS

layout

Description	The visual layout of the gallery. When uniform, rows take up the height of the tallest item and are spaced evenly across the gallery. Additionally, items will have an aspect ratio of 1/1, forcing them to be square unless a height is explicitly set. When masonry, items will be positioned under each other with only the specified gap between them.
Attribute	layout
Type	"masonry" ｜ "uniform"
Default	'uniform'

mode

Description	The mode determines the platform behaviors of the component. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

order

Description	The order in which items are positioned. Only applies when layout is masonry. When sequential, items are positioned in the order they are placed in the DOM. When best-fit, items are positioned under the column with the most available space.
Attribute	order
Type	"best-fit" ｜ "sequential"
Default	'sequential'

theme

Description	The theme determines the visual appearance of the component. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	theme
Type	"ios" ｜ "md" ｜ "ionic"
Default	undefined

Events

No events available for this component.

Methods

No public methods available for this component.

CSS Shadow Parts

No CSS shadow parts available for this component.

CSS Custom Properties

Name	Description
--ion-gallery-gap	Space between gallery items

Slots

Name	Description
``	Content is placed in a responsive gallery layout.